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
atlas 60a253a2f6 fix(#1763): address argus review on PR #2430 
- regenerate docs/tools/hivectl-cli.md for the new `subvol snapshot send` verb
- close the TOCTOU on the no-overwrite guard: File::options().create_new(true)
  (O_CREAT|O_EXCL) instead of exists()-then-create, so the guarantee is
  atomic against a concurrent request racing the same dest filename
- warn (not silently swallow) if cleaning up a partial export after a
  failed btrfs send itself fails, so a stuck garbage file masquerading
  as a completed export is visible in the log
2026-07-14 19:23:59 +02:00

683 lines
36 KiB
Markdown
Raw Blame History

# 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 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 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] <COMMAND>`
###### **Subcommands:**
* `forge` — Forgejo user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (`forge::ensure_all`) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes without bouncing the daemon
* `matrix` — matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (`matrix::ensure_all`) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register after wiping a token file
* `github` — GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `github-token` state file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (`hyperhive.github.enable`), so no per-agent config is needed
* `gateway` — Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (`services.hyperhive.gateway.auth`). Credentials are stored as `BCrypt` hashes — no extra service or PAM required
* `agents` — Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
* `wg` — WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`)
* `peer-config` — Generate the federation peer-config block for THIS hive — the nix a peer operator pastes into their `services.hyperhive.swarm.peers` to trust + reach this hive. Emits `caCert` (+ a `cp` line for the cert) when this hive serves a self-signed CA, the WireGuard public key when the mesh key exists, and the `wireguard{Address,Endpoint}` you pass. The hive's own domain is filled in automatically from the running daemon (`services.hyperhive.domain`). Reads local state (the TLS CA cert, the wg key); never mutates. `wg init` calls this at the end, so a fresh mesh setup prints the hand-over block too
* `choom` — Open an interactive Claude session inside an agent container
* `stop` — Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **everything** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
* `start` — Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` restores the previously-running agents from the last broad-scope `stop`, or starts everything if no prior stop exists; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). A targeted `--agent <name>` start is never filtered. Requires the hive-c0re daemon
* `restart` — Restart containers hive-wide — `stop` then `start` over the same scope. Bare `hivectl restart` restarts **everything** (all sub-agents plus the ci/forge/gateway/matrix infra containers); the same scope flags as `stop`/`start` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). If the stop phase reports a failure the start phase is skipped so the operator can investigate. Requires the hive-c0re daemon
* `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 flow c0re runs automatically at boot (`forge::ensure_all`) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes 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>`.
When `<name>` matches an existing agent (i.e. it has a state dir under `/var/lib/hyperhive/agents/`), persists the token to `<state>/forge-token` (idempotent: re-mints + rewrites every call so the on-disk scope matches the current `forge::TOKEN_SCOPES`).
When `<name>` is **not** an agent (a human or any other non-container account), creates the forgejo user and prints the freshly-minted token to stdout — no `/var/lib/hyperhive/agents/` directory is created for the user.
Without `--password` / `--password-stdin` a random throwaway is used (fine for agents — they auth by token via tea / hive-forge). Set a password to log into the forge web UI afterwards. `--password` is idempotent: re-running with the same value sets the same password (covers password resets on already-created accounts since `forgejo admin user create` silently no-ops once the user exists).
**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 flow c0re runs automatically at boot (`matrix::ensure_all`) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register 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 (`@hive:<server>`). hive-c0re runs this automatically on startup before the agent sweep so the account is the first registered user — Conduit/tuwunel grants admin rights to the first user. Run manually to recover a missing admin token file
* `promote-user` — Promote a matrix user to homeserver admin via the admin API. Uses the hive system admin token at `/var/lib/hyperhive/matrix/admin-token`. The `server_name` is discovered automatically from the running homeserver
* `reset-password` — Reset a matrix user's password via the admin API and persist the new password to `/var/lib/hyperhive/matrix/creds/<name>-password` so the next `ensure_user_for` (or `create-user`) can re-login
* `invite` — Invite a matrix user to the hive Space (default) or a specific room. Uses the hive admin token; the admin account must be a member of the target room with invite power (it owns the hive Space). Idempotent — already-member / already-invited is a no-op
## `hivectl matrix create-user`
Create or refresh the matrix account + access token for `<name>`.
When `<name>` matches an existing agent (i.e. it has a state dir under `/var/lib/hyperhive/agents/`), persists the token to `<state>/matrix-token`. Skips registration when the file is already populated; delete it to force re-registration.
When `<name>` is **not** an agent (a human or any other non-container account), registers the matrix user and prints the freshly-minted access token to stdout — no `/var/lib/hyperhive/agents/` directory is created for the user.
Without `--password` / `--password-stdin` a random throwaway is used (fine for agents — they auth by `access_token`, never by password). Set a password to log into a matrix web client afterwards.
**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 (`@hive:<server>`). hive-c0re runs this automatically on startup before the agent sweep so the account is the first registered user — Conduit/tuwunel grants admin rights to the first user. Run manually to recover a missing admin token file
**Usage:** `hivectl matrix sync-admin`
## `hivectl matrix promote-user`
Promote a matrix user to homeserver admin via the admin API. Uses the hive system admin token at `/var/lib/hyperhive/matrix/admin-token`. The `server_name` is discovered automatically from the running homeserver
**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 and persist the new password to `/var/lib/hyperhive/matrix/creds/<name>-password` so the next `ensure_user_for` (or `create-user`) can re-login.
After this command succeeds, run `hivectl matrix create-user <name>` to mint a fresh access token for the agent.
**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 (default) or a specific room. Uses the hive admin token; the admin account must be a member of the target room with invite power (it owns the hive Space). Idempotent — already-member / already-invited is a no-op
**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: write an operator-supplied personal access token (PAT) into an agent's `github-token` state file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (`hyperhive.github.enable`), so no per-agent config is needed
**Usage:** `hivectl github <COMMAND>`
###### **Subcommands:**
* `set-token` — Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (`hyperhive.github.enable`), so the `gh` wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
## `hivectl github set-token`
Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (`hyperhive.github.enable`), so the `gh` wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
**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 in an htpasswd file used by the gateway's HTTP Basic auth (`services.hyperhive.gateway.auth`). Credentials are stored as `BCrypt` hashes — no extra service or PAM required
**Usage:** `hivectl gateway <COMMAND>`
###### **Subcommands:**
* `create-user` — Add a new user or update the password of an existing user in the gateway htpasswd file. The password is hashed with `BCrypt` (cost 12)
* `delete-user` — Remove a user from the gateway htpasswd file. Exits with an error when the user is not found so callers can detect the no-op case
* `list-users` — List all usernames in the gateway htpasswd file, one per line
## `hivectl gateway create-user`
Add a new user or update the password of an existing user in the gateway htpasswd file. The password is hashed with `BCrypt` (cost 12).
Pass `--password-stdin` when scripting or when you don't want the password visible in shell history. The file is created if it does not exist; its parent directory must already exist.
**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`
* `-f`, `--file <FILE>` — Path to the htpasswd file. Defaults to the standard gateway credential store at `/var/lib/hyperhive/gateway/gateway.htpasswd`
Default value: `/var/lib/hyperhive/gateway/gateway.htpasswd`
## `hivectl gateway delete-user`
Remove a user from the gateway htpasswd file. Exits with an error when the user is not found so callers can detect the no-op case
**Usage:** `hivectl gateway delete-user [OPTIONS] <USERNAME>`
###### **Arguments:**
* `<USERNAME>` — Username to remove
###### **Options:**
* `-f`, `--file <FILE>` — Path to the htpasswd file. Defaults to the standard gateway credential store
Default value: `/var/lib/hyperhive/gateway/gateway.htpasswd`
## `hivectl gateway list-users`
List all usernames in the gateway htpasswd file, one per line
**Usage:** `hivectl gateway list-users [OPTIONS]`
###### **Options:**
* `-f`, `--file <FILE>` — Path to the htpasswd file. Defaults to the standard gateway credential store
Default value: `/var/lib/hyperhive/gateway/gateway.htpasswd`
## `hivectl agents`
Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
**Usage:** `hivectl agents <COMMAND>`
###### **Subcommands:**
* `list` — Show all managed agents with their status (running / needs-login / needs-update) and technical state (deployed sha, parent, pending reminders). The host roster overview; reuses the dashboard's per-agent aggregation. Requires the daemon running
* `restart` — Stop and start a single agent container without rebuilding config. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config. Rides the job queue (serialized against in-flight rebuilds for the same agent); waits with live progress unless `--no-wait`
* `restart-all` — Restart ALL managed agent containers via one restart DAG each — unrelated agents overlap, each serializes on its own lease. Waits for the whole set with live progress unless `--no-wait`
## `hivectl agents list`
Show all managed agents with their status (running / needs-login / needs-update) and technical state (deployed sha, parent, pending reminders). The host roster overview; reuses the dashboard's per-agent aggregation. Requires the daemon running
**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. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config. Rides the job queue (serialized against in-flight rebuilds for the same agent); waits with live progress unless `--no-wait`
**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 via one restart DAG each — unrelated agents overlap, each serializes on its own lease. Waits for the whole set with live progress unless `--no-wait`
**Usage:** `hivectl agents restart-all [OPTIONS]`
###### **Options:**
* `--no-wait` — Return immediately after the restart DAGs are queued
## `hivectl wg`
WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`).
One-time-setup convenience so nobody has to remember the `wg` dance: `wg init` generates + stores this hive's private key and prints the public key plus the nix snippet to enable the mesh; `wg peer` prints the snippet to add a remote hive; `wg status` wraps `wg show`. The verbs own the imperative state (the key file); the printed nix goes into the operator's host config (kept in git), so nothing here mutates declarative config behind the operator's back.
**Usage:** `hivectl wg <COMMAND>`
###### **Subcommands:**
* `init` — Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives
* `peer` — Print the nix snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get `<pubkey>` from the peer's `hivectl wg init`
* `status` — Show the live mesh interface state (`wg show wg-hive`). Requires the mesh to be enabled + up
## `hivectl wg init`
Generate (if absent) this hive's WireGuard private key, print its public key, and print the nix snippet to enable the mesh. Idempotent: an existing key is reused, never clobbered (clobbering would break a live mesh). Share the printed public key with peer hives
**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 snippet to add a peer hive to the mesh. Pure output — paste it into this hive's config. Get `<pubkey>` from the peer's `hivectl wg init`
**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 (`wg show wg-hive`). Requires the mesh to be enabled + up
**Usage:** `hivectl wg status`
## `hivectl peer-config`
Generate the federation peer-config block for THIS hive — the nix a peer operator pastes into their `services.hyperhive.swarm.peers` to trust + reach this hive. Emits `caCert` (+ a `cp` line for the cert) when this hive serves a self-signed CA, the WireGuard public key when the mesh key exists, and the `wireguard{Address,Endpoint}` you pass. The hive's own domain is filled in automatically from the running daemon (`services.hyperhive.domain`). Reads local state (the TLS CA cert, the wg key); never mutates. `wg init` calls this at the end, so a fresh mesh setup prints the hand-over block too
**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.
Runs claude as the agent user from its state dir with the harness's settings / MCP / system prompt. Bare `choom <name>` is a fresh session; `--resume <session-id>` rejoins a prior one. Never collides with the harness's live session. Requires root + a running container. See `docs/tools/hivectl.md` (Choom) for details.
**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** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
**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 previously-running agents from the last broad-scope `stop`, or starts everything if no prior stop exists; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). A targeted `--agent <name>` start is never filtered. Requires the hive-c0re daemon
**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 the same scope. Bare `hivectl restart` restarts **everything** (all sub-agents plus the ci/forge/gateway/matrix infra containers); the same scope flags as `stop`/`start` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). If the stop phase reports a failure the start phase is skipped so the operator can investigate. Requires the hive-c0re daemon
**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: `quota enable` turns on btrfs qgroup accounting for the agent-state filesystem (a one-time, I/O-heavy rescan — that's why it isn't automatic). Then `quota show` reports per-agent usage and `quota limit` caps an agent. No-op on non-btrfs hosts. Operates on agent state subvolumes (created by the btrfs-subvolume migration); agents still on a plain dir report no qgroup usage.
**Usage:** `hivectl quota <COMMAND>`
###### **Subcommands:**
* `enable` — Enable btrfs qgroup accounting on the agent-state filesystem. Run once before `show` / `limit`. Triggers a full btrfs rescan (I/O heavy on a large filesystem), so it's a deliberate opt-in. Idempotent; a no-op on non-btrfs hosts
* `show` — Report per-agent disk usage (referenced + exclusive bytes) from btrfs qgroups. With no name, shows every agent that has a state subvolume; pass a name to show just that one. Requires `enable` first
* `limit` — Set or clear an agent's disk quota (a referenced-usage cap). `size` accepts a byte count or a `K`/`M`/`G`/`T` suffix (e.g. `5G`), or `none` to clear the limit. Requires `enable` first
## `hivectl quota enable`
Enable btrfs qgroup accounting on the agent-state filesystem. Run once before `show` / `limit`. Triggers a full btrfs rescan (I/O heavy on a large filesystem), so it's a deliberate opt-in. Idempotent; a no-op on non-btrfs hosts
**Usage:** `hivectl quota enable`
## `hivectl quota show`
Report per-agent disk usage (referenced + exclusive bytes) from btrfs qgroups. With no name, shows every agent that has a state subvolume; pass a name to show just that one. Requires `enable` first
**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 quota (a referenced-usage cap). `size` accepts a byte count or a `K`/`M`/`G`/`T` suffix (e.g. `5G`), or `none` to clear the limit. Requires `enable` first
**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.
New agents get a btrfs subvolume state root automatically (when the host FS is btrfs); agents that predate that are left on plain dirs. `subvol upgrade <agent>` opts an existing plain-dir agent into the subvolume feature set (snapshots, per-subvol usage/quota, migration) by migrating its state dir in place. Requires the hive-c0re daemon (for the stop/start) and root (for the privileged migration).
**Usage:** `hivectl subvol <COMMAND>`
###### **Subcommands:**
* `upgrade` — Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates `…/agents/<name>/` to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires `--yes` since it bounces the agent and moves its state
* `snapshot` — Read-only snapshots of an agent's state subvolume — the first step of the (in-progress) inter-hive migration path, or a manual point-in-time backup
## `hivectl subvol upgrade`
Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates `…/agents/<name>/` to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires `--yes` since it bounces the agent and moves its state
**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 — the first step of the (in-progress) inter-hive migration path, or a manual point-in-time backup
**Usage:** `hivectl subvol snapshot <COMMAND>`
###### **Subcommands:**
* `create` — Create a read-only snapshot. Agent must already be a subvolume (`subvol upgrade` first). Prints the snapshot's host path
* `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 (`subvol upgrade` first). Prints the snapshot's host path
**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 (`HostRequest::Urls`), so custom forge / matrix domains work without guessing `forge.<domain>`. Prints the URL unconditionally — the reliable core, since the host is usually headless / driven over SSH where `xdg-open` is a no-op — then tries `xdg-open` as a convenience. 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.
Pipe it into your shell's completion path — e.g. for zsh: `hivectl completions zsh > ~/.zsh/completions/_hivectl` (with that dir on `$fpath`). The hyperhive NixOS module installs the zsh script system-wide automatically, so this is mainly for ad-hoc / other-shell use. Supports bash, zsh, fish, elvish, and powershell.
**Usage:** `hivectl completions <SHELL>`
###### **Arguments:**
* `<SHELL>` — Shell to emit completions for
Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>
Reference in a new issue View git blame Copy permalink