# Command-Line Help for `hivectl` This document contains the help content for the `hivectl` command-line program. **Command Overview:** * [`hivectl`↴](#hivectl) * [`hivectl forge`↴](#hivectl-forge) * [`hivectl forge create-user`↴](#hivectl-forge-create-user) * [`hivectl forge reconcile-config`↴](#hivectl-forge-reconcile-config) * [`hivectl matrix`↴](#hivectl-matrix) * [`hivectl matrix create-user`↴](#hivectl-matrix-create-user) * [`hivectl matrix sync-admin`↴](#hivectl-matrix-sync-admin) * [`hivectl matrix promote-user`↴](#hivectl-matrix-promote-user) * [`hivectl matrix reset-password`↴](#hivectl-matrix-reset-password) * [`hivectl matrix invite`↴](#hivectl-matrix-invite) * [`hivectl github`↴](#hivectl-github) * [`hivectl github set-token`↴](#hivectl-github-set-token) * [`hivectl gateway`↴](#hivectl-gateway) * [`hivectl gateway create-user`↴](#hivectl-gateway-create-user) * [`hivectl gateway delete-user`↴](#hivectl-gateway-delete-user) * [`hivectl gateway list-users`↴](#hivectl-gateway-list-users) * [`hivectl agents`↴](#hivectl-agents) * [`hivectl agents list`↴](#hivectl-agents-list) * [`hivectl agents restart`↴](#hivectl-agents-restart) * [`hivectl agents restart-all`↴](#hivectl-agents-restart-all) * [`hivectl agents spawn`↴](#hivectl-agents-spawn) * [`hivectl agents request-spawn`↴](#hivectl-agents-request-spawn) * [`hivectl agents kill`↴](#hivectl-agents-kill) * [`hivectl agents destroy`↴](#hivectl-agents-destroy) * [`hivectl agents rebuild`↴](#hivectl-agents-rebuild) * [`hivectl agents set-parent`↴](#hivectl-agents-set-parent) * [`hivectl approvals`↴](#hivectl-approvals) * [`hivectl approvals pending`↴](#hivectl-approvals-pending) * [`hivectl approvals approve`↴](#hivectl-approvals-approve) * [`hivectl approvals deny`↴](#hivectl-approvals-deny) * [`hivectl wg`↴](#hivectl-wg) * [`hivectl wg init`↴](#hivectl-wg-init) * [`hivectl wg peer`↴](#hivectl-wg-peer) * [`hivectl wg status`↴](#hivectl-wg-status) * [`hivectl peer-config`↴](#hivectl-peer-config) * [`hivectl choom`↴](#hivectl-choom) * [`hivectl stop`↴](#hivectl-stop) * [`hivectl start`↴](#hivectl-start) * [`hivectl restart`↴](#hivectl-restart) * [`hivectl quota`↴](#hivectl-quota) * [`hivectl quota enable`↴](#hivectl-quota-enable) * [`hivectl quota show`↴](#hivectl-quota-show) * [`hivectl quota limit`↴](#hivectl-quota-limit) * [`hivectl subvol`↴](#hivectl-subvol) * [`hivectl subvol upgrade`↴](#hivectl-subvol-upgrade) * [`hivectl subvol snapshot`↴](#hivectl-subvol-snapshot) * [`hivectl subvol snapshot create`↴](#hivectl-subvol-snapshot-create) * [`hivectl subvol snapshot delete`↴](#hivectl-subvol-snapshot-delete) * [`hivectl subvol snapshot send`↴](#hivectl-subvol-snapshot-send) * [`hivectl open`↴](#hivectl-open) * [`hivectl completions`↴](#hivectl-completions) ## `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] ` ###### **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 ` — 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 ` ###### **Subcommands:** * `create-user` — Create or refresh the Forgejo account + token for `` * `reconcile-config` — Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/` main ## `hivectl forge create-user` Create or refresh the Forgejo account + token for ``. 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] ` ###### **Arguments:** * `` — Forgejo username. For agents: the container/agent name (`` in `h-`; manager uses the literal `manager`). For humans: any forgejo username — `mara`, `damocles`, etc ###### **Options:** * `--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 forge reconcile-config` Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/` main. Always prints the diff first. `--from forge` resets the local checkout to forge main (effective on the next deploy); `--from local` is not supported yet. With no `--from`, prompts for the direction. **Usage:** `hivectl forge reconcile-config [OPTIONS] ` ###### **Arguments:** * `` — Agent whose config branches to reconcile ###### **Options:** * `--from ` — Which side to reconcile from. Omit to be prompted after the diff Possible values: - `forge`: Reset the local applied checkout to forge main - `local`: Advance forge main from local — not supported yet * `--verbose` — Include the full diff (not just `--stat`) in the report ## `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 ` ###### **Subcommands:** * `create-user` — Create or refresh the matrix account + access token for `` * `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 ``. 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] ` ###### **Arguments:** * `` — Matrix localpart. For agents: the container/agent name. For humans: any matrix localpart — `mara`, `damocles`, etc ###### **Options:** * `--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 ` ###### **Arguments:** * `` — 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 ` ###### **Arguments:** * `` — 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] ` ###### **Arguments:** * `` — User to invite: a full id (`@mara:server`) or a bare localpart (qualified with the homeserver's `server_name`) ###### **Options:** * `--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 ` ###### **Subcommands:** * `set-token` — Store a GitHub PAT for `` so its `gh` and git can authenticate ## `hivectl github set-token` Store a GitHub PAT for `` so its `gh` and git can authenticate. Prefer `--token-stdin` — an inline `--token` is visible in shell history. **Usage:** `hivectl github set-token [OPTIONS] ` ###### **Arguments:** * `` — Logical agent name (the container/agent name) ###### **Options:** * `--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 ` ###### **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] ` ###### **Arguments:** * `` — Username to add or update ###### **Options:** * `--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 ` ###### **Arguments:** * `` — 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 ` ###### **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] ` ###### **Arguments:** * `` — 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 ` ###### **Arguments:** * `` — Agent name (e.g. `iris`) ## `hivectl agents request-spawn` Queue a spawn request for operator approval **Usage:** `hivectl agents request-spawn ` ###### **Arguments:** * `` — Agent name ## `hivectl agents kill` Stop a managed container (graceful) **Usage:** `hivectl agents kill ` ###### **Arguments:** * `` — Agent name ## `hivectl agents destroy` Tear down a sub-agent container, keeping its state by default. No undo **Usage:** `hivectl agents destroy [OPTIONS] ` ###### **Arguments:** * `` — 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 ` ###### **Arguments:** * `` — 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] ` ###### **Arguments:** * `` — Agent to move ###### **Options:** * `--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 ` ###### **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 ` ###### **Arguments:** * `` — Approval id (from `hivectl approvals pending`) ## `hivectl approvals deny` Deny a pending request by id **Usage:** `hivectl approvals deny ` ###### **Arguments:** * `` — 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 ` ###### **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
` — 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 --address
` ###### **Arguments:** * `` — Peer hive's DNS domain (the `swarm.peers` attrset key) ###### **Options:** * `--pubkey ` — Peer's WireGuard public key (from its `hivectl wg init`) * `--address
` — Peer's mesh address (e.g. `10.42.0.2/32`) * `--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 ` — This hive's WireGuard mesh address (e.g. `10.42.0.1/32`), emitted as `wireguardAddress`. Omit when not running the mesh * `--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] ` ###### **Arguments:** * `` — Agent name (e.g. `damocles`, `iris`) ###### **Options:** * `--resume ` — Resume a prior claude session by its session id, passed through as `claude --resume ` (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 ` — 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 ` — 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 ` — 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 ` ###### **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:** * `` — 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 ` ###### **Arguments:** * `` — Agent whose state subvolume to limit * `` — 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 ` ###### **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] ` ###### **Arguments:** * `` — 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 ` ###### **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