# 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 pause`↴](#hivectl-agents-pause) * [`hivectl agents resume`↴](#hivectl-agents-resume) * [`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 agents set-limits`↴](#hivectl-agents-set-limits) * [`hivectl agents quota`↴](#hivectl-agents-quota) * [`hivectl agents quota enable`↴](#hivectl-agents-quota-enable) * [`hivectl agents quota show`↴](#hivectl-agents-quota-show) * [`hivectl agents quota set`↴](#hivectl-agents-quota-set) * [`hivectl agents subvol`↴](#hivectl-agents-subvol) * [`hivectl agents subvol upgrade`↴](#hivectl-agents-subvol-upgrade) * [`hivectl agents subvol snapshot`↴](#hivectl-agents-subvol-snapshot) * [`hivectl agents subvol snapshot create`↴](#hivectl-agents-subvol-snapshot-create) * [`hivectl agents subvol snapshot delete`↴](#hivectl-agents-subvol-snapshot-delete) * [`hivectl agents subvol snapshot send`↴](#hivectl-agents-subvol-snapshot-send) * [`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 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 * `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 * `pause` — Park an agent's turn loop, leaving the container running * `resume` — Resume a paused agent — it drains whatever queued up while parked * `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 * `set-limits` — Declare an agent's CPU/memory limits, overriding the hive-wide defaults * `quota` — Per-agent disk accounting + optional quotas via btrfs qgroups * `subvol` — btrfs subvolume management for agent state dirs ## `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 pause` Park an agent's turn loop, leaving the container running. The harness stops driving turns but keeps serving its web UI and MCP daemons, so the container, its mounts and its warm caches stay up while it burns no tokens. Inbox messages queue unacked and the backlog drains on `resume`. Sticky: it survives a restart, and pausing a stopped agent makes it come up paused. **Usage:** `hivectl agents pause ` ###### **Arguments:** * `` — Agent name ## `hivectl agents resume` Resume a paused agent — it drains whatever queued up while parked **Usage:** `hivectl agents resume ` ###### **Arguments:** * `` — Agent name ## `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 agents set-limits` Declare an agent's CPU/memory limits, overriding the hive-wide defaults. Replaces the agent's whole override entry rather than merging into it: any limit you don't pass returns to the hive-wide default. To change one and keep the other, pass both. Disk is a separate resource with its own group — see `agents quota`. **Usage:** `hivectl agents set-limits [OPTIONS] ` ###### **Arguments:** * `` — Agent name ###### **Options:** * `--cpu-quota ` — systemd `CPUQuota=` value, e.g. `400%` (100% = one full core) * `--memory-max ` — systemd `MemoryMax=` value, e.g. `8G`, `50%`, or `infinity` * `--reset` — Drop all overrides — the agent returns to the hive-wide defaults. Required to clear limits, so that a `set-limits` with a forgotten value can't silently reset the agent ## `hivectl agents 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 agents 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) * `set` — Set or clear an agent's disk-usage quota ## `hivectl agents quota enable` Enable btrfs qgroup accounting on the agent-state filesystem. Run once before `show` / `limit`. No-op on non-btrfs hosts. **Usage:** `hivectl agents quota enable` ## `hivectl agents quota show` Report per-agent disk usage from btrfs qgroups (all agents, or one by name) **Usage:** `hivectl agents quota show [NAME]` ###### **Arguments:** * `` — Agent to show (omit for all agents with a state subvolume) ## `hivectl agents quota set` Set or clear an agent's disk-usage quota. Named `set` rather than `set-quota` because the enclosing `quota` group already carries the noun — `agents quota set iris 5G`. The `set-` spelling stays for the flat verbs (`set-parent`, `set-limits`), which have no group to inherit it from. **Usage:** `hivectl agents quota set ` ###### **Arguments:** * `` — Agent whose state subvolume to limit * `` — Size cap (`5G`, `500M`, `1073741824`) or `none` to clear ## `hivectl agents 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 agents 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 agents 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 agents 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 agents subvol snapshot` Read-only snapshots of an agent's state subvolume **Usage:** `hivectl agents 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 agents subvol snapshot create` Create a read-only snapshot (agent must already be a subvolume) **Usage:** `hivectl agents subvol snapshot create --label