vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/tools/hivectl-cli.md

25 KiB
Raw Blame History

Command-Line Help for hivectl

This document contains the help content for the hivectl command-line program.

Command Overview:

hivectl

Sibling to the hive-c0re daemon binary. Covers host-side admin operations that don't go through the broker — manual user provisioning on the bundled forge + matrix containers, plus future recovery / debugging verbs.

Usage: hivectl [OPTIONS] <COMMAND>

Subcommands:
  • forge — Forgejo user provisioning
  • matrix — matrix-tuwunel user provisioning
  • github — GitHub account provisioning
  • gateway — Gateway htpasswd user management
  • agents — Agent container management
  • approvals — Operator approval queue: list, approve, or deny pending requests
  • wg — WireGuard inter-hive mesh setup helpers
  • peer-config — Generate the federation peer-config block for THIS hive
  • choom — Open an interactive Claude session inside an agent container
  • stop — Stop containers hive-wide in one operator action
  • start — Start containers hive-wide — the inverse of hivectl stop
  • restart — Restart containers hive-wide — stop then start over one scope
  • quota — Per-agent disk accounting + optional quotas via btrfs qgroups
  • subvol — btrfs subvolume management for agent state dirs
  • open — Print (and best-effort open in a browser) a hive web surface URL
  • completions — Generate a shell completion script for hivectl and print it to stdout
Options:

  • --socket <SOCKET> — Path to the hive-c0re host admin socket, used by the daemon-assisted verbs (agents, stop, start). Global: accepted before or after the subcommand. Verbs that don't talk to the daemon ignore it

    Default value: /run/hyperhive/host.sock

hivectl forge

Forgejo user provisioning.

Manual entry point to the same idempotent provisioning c0re runs at boot — for recovery, ad-hoc reprovisioning, or fixing one agent without bouncing the daemon.

Usage: hivectl forge <COMMAND>

Subcommands:
  • create-user — Create or refresh the Forgejo account + token for <name>

hivectl forge create-user

Create or refresh the Forgejo account + token for <name>.

For an existing agent, persists the token to its state dir; for a human/other account, prints the token to stdout. Set a password to enable forge web-UI login (a random throwaway is used otherwise).

Usage: hivectl forge create-user [OPTIONS] <NAME>

Arguments:
  • <NAME> — Forgejo username. For agents: the container/agent name (<n> in h-<n>; manager uses the literal manager). For humans: any forgejo username — mara, damocles, etc
Options:
  • --password <PASSWORD> — Set the account password to this string instead of a random throwaway. Use this for operator accounts that need to log into the forge web UI. Mutually exclusive with --password-stdin. WARNING: the password is visible in shell history + process listings; prefer --password-stdin for anything sensitive
  • --password-stdin — Read the password from stdin (single line, trailing newline stripped) instead of an inline flag. Mutually exclusive with --password

hivectl matrix

matrix-tuwunel user provisioning.

Manual entry point to the same idempotent provisioning c0re runs at boot — for re-registering an agent the boot sweep skipped, or after wiping a token file.

Usage: hivectl matrix <COMMAND>

Subcommands:
  • create-user — Create or refresh the matrix account + access token for <name>
  • sync-admin — Provision (or re-provision) the hive system admin matrix account
  • promote-user — Promote a matrix user to homeserver admin
  • reset-password — Reset a matrix user's password via the admin API
  • invite — Invite a matrix user to the hive Space, or a specific room with --room. Idempotent

hivectl matrix create-user

Create or refresh the matrix account + access token for <name>.

For an existing agent, persists the token to its state dir; for a human/other account, prints the access token to stdout. Set a password to enable matrix web-client login (a random throwaway is used otherwise).

Usage: hivectl matrix create-user [OPTIONS] <NAME>

Arguments:
  • <NAME> — Matrix localpart. For agents: the container/agent name. For humans: any matrix localpart — mara, damocles, etc
Options:
  • --password <PASSWORD> — Set the account password to this string instead of a random throwaway. Use this for operator accounts that need to log into matrix web clients via m.login.password. Mutually exclusive with --password-stdin. WARNING: the password is visible in shell history + process listings; prefer --password-stdin for anything sensitive
  • --password-stdin — Read the password from stdin (single line, trailing newline stripped) instead of an inline flag. Mutually exclusive with --password

hivectl matrix sync-admin

Provision (or re-provision) the hive system admin matrix account.

Runs automatically on startup; run manually to recover a missing admin token.

Usage: hivectl matrix sync-admin

hivectl matrix promote-user

Promote a matrix user to homeserver admin

Usage: hivectl matrix promote-user <NAME>

Arguments:
  • <NAME> — Matrix localpart of the user to promote (e.g. argus)

hivectl matrix reset-password

Reset a matrix user's password via the admin API.

Persists the new password so a later create-user can re-login.

Usage: hivectl matrix reset-password <NAME>

Arguments:
  • <NAME> — Matrix localpart of the account to reset (e.g. argus)

hivectl matrix invite

Invite a matrix user to the hive Space, or a specific room with --room. Idempotent

Usage: hivectl matrix invite [OPTIONS] <USER>

Arguments:
  • <USER> — User to invite: a full id (@mara:server) or a bare localpart (qualified with the homeserver's server_name)
Options:
  • --room <ROOM> — Target room id (!abc:server) or alias (#name:server). Omit to invite to the hive Space

hivectl github

GitHub account provisioning.

Store an operator-supplied personal access token (PAT) for an agent so its gh and git can authenticate. No account is created — the PAT is for an existing GitHub account.

Usage: hivectl github <COMMAND>

Subcommands:
  • set-token — Store a GitHub PAT for <agent> so its gh and git can authenticate

hivectl github set-token

Store a GitHub PAT for <agent> so its gh and git can authenticate.

Prefer --token-stdin — an inline --token is visible in shell history.

Usage: hivectl github set-token [OPTIONS] <AGENT>

Arguments:
  • <AGENT> — Logical agent name (the container/agent name)
Options:
  • --token <TOKEN> — The PAT value inline. Mutually exclusive with --token-stdin
  • --token-stdin — Read the PAT from stdin (trailing newline stripped). Mutually exclusive with --token

hivectl gateway

Gateway htpasswd user management.

Add, remove, or list users for the gateway's HTTP Basic auth.

Usage: hivectl gateway <COMMAND>

Subcommands:
  • create-user — Add a user or update an existing user's password in the gateway htpasswd
  • delete-user — Remove a user from the gateway htpasswd
  • list-users — List all gateway htpasswd usernames, one per line

hivectl gateway create-user

Add a user or update an existing user's password in the gateway htpasswd.

Use --password-stdin to keep the password out of shell history.

Usage: hivectl gateway create-user [OPTIONS] <USERNAME>

Arguments:
  • <USERNAME> — Username to add or update
Options:
  • --password <PASSWORD> — Set the password inline. WARNING: visible in shell history and process listings — prefer --password-stdin for sensitive input. Mutually exclusive with --password-stdin
  • --password-stdin — Read the password from stdin (single line, trailing newline stripped). Mutually exclusive with --password

hivectl gateway delete-user

Remove a user from the gateway htpasswd

Usage: hivectl gateway delete-user <USERNAME>

Arguments:
  • <USERNAME> — Username to remove

hivectl gateway list-users

List all gateway htpasswd usernames, one per line

Usage: hivectl gateway list-users

hivectl agents

Agent container management.

Lifecycle actions on managed agent containers. Needs the hive-c0re daemon running.

Usage: hivectl agents <COMMAND>

Subcommands:
  • list — Show all managed agents with their status and technical state
  • restart — Stop and start a single agent container without rebuilding config
  • restart-all — Restart all managed agent containers
  • spawn — Spawn a new agent container directly, bypassing the approval queue
  • request-spawn — Queue a spawn request for operator approval
  • kill — Stop a managed container (graceful)
  • destroy — Tear down a sub-agent container, keeping its state by default. No undo
  • rebuild — Apply pending config to a managed container
  • set-parent — Move an agent in the topology tree — under a new parent, or to root

hivectl agents list

Show all managed agents with their status and technical state

Usage: hivectl agents list [OPTIONS]

Options:
  • --json — Emit the raw JSON rows instead of the padded table (for scripting). The table is the default human-readable shape

hivectl agents restart

Stop and start a single agent container without rebuilding config

Usage: hivectl agents restart [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, ruth)
Options:
  • --no-wait — Return immediately after the restart DAG is queued

hivectl agents restart-all

Restart all managed agent containers

Usage: hivectl agents restart-all [OPTIONS]

Options:
  • --no-wait — Return immediately after the restart DAGs are queued

hivectl agents spawn

Spawn a new agent container directly, bypassing the approval queue.

Operator-on-the-host only; use request-spawn for an approval-gated spawn.

Usage: hivectl agents spawn <NAME>

Arguments:
  • <NAME> — Agent name (e.g. iris)

hivectl agents request-spawn

Queue a spawn request for operator approval

Usage: hivectl agents request-spawn <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents kill

Stop a managed container (graceful)

Usage: hivectl agents kill <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents destroy

Tear down a sub-agent container, keeping its state by default. No undo

Usage: hivectl agents destroy [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name
Options:
  • --purge — Also wipe the agent's state dirs (config + creds + notes)

hivectl agents rebuild

Apply pending config to a managed container

Usage: hivectl agents rebuild <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents set-parent

Move an agent in the topology tree — under a new parent, or to root

Usage: hivectl agents set-parent [OPTIONS] <CHILD>

Arguments:
  • <CHILD> — Agent to move
Options:
  • --parent <PARENT> — New parent agent name. Mutually exclusive with --root
  • --root — Promote child to root (no parent)

hivectl approvals

Operator approval queue: list, approve, or deny pending requests.

Needs the hive-c0re daemon running.

Usage: hivectl approvals <COMMAND>

Subcommands:
  • pending — List pending approval requests submitted by agents
  • approve — Approve a pending request by id; the action runs immediately
  • deny — Deny a pending request by id

hivectl approvals pending

List pending approval requests submitted by agents

Usage: hivectl approvals pending

hivectl approvals approve

Approve a pending request by id; the action runs immediately

Usage: hivectl approvals approve <ID>

Arguments:
  • <ID> — Approval id (from hivectl approvals pending)

hivectl approvals deny

Deny a pending request by id

Usage: hivectl approvals deny <ID>

Arguments:
  • <ID> — Approval id

hivectl wg

WireGuard inter-hive mesh setup helpers.

Generate this hive's mesh key and print the nix to enable the mesh, add a peer, or inspect live interface state.

Usage: hivectl wg <COMMAND>

Subcommands:
  • init — Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh
  • peer — Print the nix to add a peer hive to the mesh
  • status — Show the live mesh interface state

hivectl wg init

Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh

Usage: hivectl wg init [OPTIONS]

Options:
  • --address <ADDRESS> — This hive's mesh address (e.g. 10.42.0.1/32) to bake into the printed snippet. Omit to get a placeholder you fill in

hivectl wg peer

Print the nix to add a peer hive to the mesh

Usage: hivectl wg peer [OPTIONS] --pubkey <PUBKEY> --address <ADDRESS> <DOMAIN>

Arguments:
  • <DOMAIN> — Peer hive's DNS domain (the swarm.peers attrset key)
Options:
  • --pubkey <PUBKEY> — Peer's WireGuard public key (from its hivectl wg init)
  • --address <ADDRESS> — Peer's mesh address (e.g. 10.42.0.2/32)
  • --endpoint <ENDPOINT> — Peer's host:port endpoint (omit for a peer that only dials out, e.g. one behind NAT — it must set an endpoint pointing back here)

hivectl wg status

Show the live mesh interface state

Usage: hivectl wg status

hivectl peer-config

Generate the federation peer-config block for THIS hive.

Prints the nix a peer operator pastes into their swarm config to trust and reach this hive.

Usage: hivectl peer-config [OPTIONS]

Options:
  • --wg-address <WG_ADDRESS> — This hive's WireGuard mesh address (e.g. 10.42.0.1/32), emitted as wireguardAddress. Omit when not running the mesh
  • --wg-endpoint <WG_ENDPOINT> — This hive's public WireGuard endpoint (host:port), emitted as wireguardEndpoint. Omit when peers dial in / no mesh

hivectl choom

Open an interactive Claude session inside an agent container.

A fresh session by default, or resume a prior one. Requires root and a running container.

Usage: hivectl choom [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --resume <SESSION> — Resume a prior claude session by its session id, passed through as claude --resume <value> (claude's --continue takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. A value is required when the flag is given

hivectl stop

Stop containers hive-wide in one operator action.

Bare hivectl stop stops everything; scope flags narrow it to specific sub-agents or infra containers.

Usage: hivectl stop [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)
  • --graceful — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent gets a graceful-stop DAG on the job queue: the harness is signalled, runs one stop-checkpoint turn to flush durable /state, drains, then the container is stopped (bounded by a 3-min timeout that falls back to a hard stop). All drains overlap. Applies to agents only
  • --no-wait — Return immediately after the stop DAGs are queued instead of waiting for them with live per-node progress

hivectl start

Start containers hive-wide — the inverse of hivectl stop.

Bare hivectl start restores the agents stopped by the last broad-scope stop (or starts everything if none); scope flags narrow it.

Usage: hivectl start [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)
  • --no-wait — Return immediately after the start DAGs are queued instead of waiting for them with live per-node progress

hivectl restart

Restart containers hive-wide — stop then start over one scope.

Bare hivectl restart restarts everything; scope flags narrow it.

Usage: hivectl restart [OPTIONS]

Options:
  • --agents — All sub-agent containers
  • --agent <NAME> — A specific sub-agent by name. Repeatable: --agent a --agent b
  • --ci — The CI runner container (hive-ci)
  • --forge — The forge container (hive-forge)
  • --gateway — The gateway container (hive-gateway)
  • --matrix — The matrix container (hive-matrix)
  • --graceful — Gracefully quiesce each agent on the stop half (see stop --graceful). Applies to agents only

hivectl quota

Per-agent disk accounting + optional quotas via btrfs qgroups.

Opt-in: enable qgroup accounting, then report per-agent usage or cap an agent. No-op on non-btrfs hosts.

Usage: hivectl quota <COMMAND>

Subcommands:
  • enable — Enable btrfs qgroup accounting on the agent-state filesystem
  • show — Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
  • limit — Set or clear an agent's disk-usage quota

hivectl quota enable

Enable btrfs qgroup accounting on the agent-state filesystem.

Run once before show / limit. No-op on non-btrfs hosts.

Usage: hivectl quota enable

hivectl quota show

Report per-agent disk usage from btrfs qgroups (all agents, or one by name)

Usage: hivectl quota show [NAME]

Arguments:
  • <NAME> — Agent to show (omit for all agents with a state subvolume)

hivectl quota limit

Set or clear an agent's disk-usage quota

Usage: hivectl quota limit <NAME> <SIZE>

Arguments:
  • <NAME> — Agent whose state subvolume to limit
  • <SIZE> — Size cap (5G, 500M, 1073741824) or none to clear

hivectl subvol

btrfs subvolume management for agent state dirs.

Upgrade an existing plain-dir agent's state into a btrfs subvolume so it gains snapshots and per-subvol usage/quota.

Usage: hivectl subvol <COMMAND>

Subcommands:
  • upgrade — Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota
  • snapshot — Read-only snapshots of an agent's state subvolume

hivectl subvol upgrade

Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota.

Bounces the agent to migrate its state, so it requires --yes.

Usage: hivectl subvol upgrade [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --yes — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it

hivectl subvol snapshot

Read-only snapshots of an agent's state subvolume

Usage: hivectl subvol snapshot <COMMAND>

Subcommands:
  • create — Create a read-only snapshot (agent must already be a subvolume)
  • delete — Delete a snapshot created by subvol snapshot create
  • send — Export a snapshot to a local file via btrfs send (the local-file half of inter-hive migration transport; the cross-hive ssh ... btrfs receive leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no --parent produces a self-contained archive of the snapshot

hivectl subvol snapshot create

Create a read-only snapshot (agent must already be a subvolume)

Usage: hivectl subvol snapshot create --label <LABEL> <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --label <LABEL> — Snapshot label. Mandatory, and must start with hive- — the prefix doubles as an allow-list hive-priv checks so only hivectl-issued snapshot names can reach the btrfs subvolume snapshot shellout

hivectl subvol snapshot delete

Delete a snapshot created by subvol snapshot create

Usage: hivectl subvol snapshot delete <NAME> <LABEL>

Arguments:
  • <NAME> — Agent name the snapshot belongs to
  • <LABEL> — Snapshot label passed to subvol snapshot create --label

hivectl subvol snapshot send

Export a snapshot to a local file via btrfs send (the local-file half of inter-hive migration transport; the cross-hive ssh ... btrfs receive leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no --parent produces a self-contained archive of the snapshot

Usage: hivectl subvol snapshot send [OPTIONS] --dest <DEST> <NAME> <LABEL>

Arguments:
  • <NAME> — Agent name the snapshot belongs to
  • <LABEL> — Snapshot label passed to subvol snapshot create --label
Options:
  • --parent <PARENT> — Optional parent snapshot label for an incremental send (btrfs send -p) — must be an existing, older snapshot of the same agent. Omit for a full send
  • --dest <DEST> — Destination filename (not a path) under the migrate-staging dir. Refused if it already exists

hivectl open

Print (and best-effort open in a browser) a hive web surface URL.

Resolves the URL from the running daemon so custom forge / matrix domains work. Bare hivectl open opens the operator dashboard.

Usage: hivectl open [TARGET]

Arguments:

  • <TARGET> — Which surface to open. Defaults to the operator dashboard

    Default value: home

    Possible values:

    • home: The operator dashboard (https://<domain>/)
    • forge: The forge (Forgejo) web UI
    • matrix: The matrix GUI (fluffychat)

hivectl completions

Generate a shell completion script for hivectl and print it to stdout.

Supports bash, zsh, fish, elvish, and powershell. The NixOS module already installs the zsh script system-wide; this is for ad-hoc or other-shell use.

Usage: hivectl completions <SHELL>

Arguments:

  • <SHELL> — Shell to emit completions for

    Possible values: bash, elvish, fish, powershell, zsh

This document was generated automatically by clap-markdown.