# 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 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 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. 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 * `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 ` (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 `). A targeted `--agent ` 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 `). 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 ` — 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 ` ###### **Subcommands:** * `create-user` — Create or refresh the Forgejo account + token for `` ## `hivectl forge create-user` Create or refresh the Forgejo account + token for ``. When `` matches an existing agent (i.e. it has a state dir under `/var/lib/hyperhive/agents/`), persists the token to `/forge-token` (idempotent: re-mints + rewrites every call so the on-disk scope matches the current `forge::TOKEN_SCOPES`). When `` 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] ` ###### **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 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 ` ###### **Subcommands:** * `create-user` — Create or refresh the matrix account + access token for `` * `sync-admin` — Provision (or re-provision) the hive system admin matrix account (`@hive:`). 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/-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 ``. When `` matches an existing agent (i.e. it has a state dir under `/var/lib/hyperhive/agents/`), persists the token to `/matrix-token`. Skips registration when the file is already populated; delete it to force re-registration. When `` 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] ` ###### **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 (`@hive:`). 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 ` ###### **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 and persist the new password to `/var/lib/hyperhive/matrix/creds/-password` so the next `ensure_user_for` (or `create-user`) can re-login. After this command succeeds, run `hivectl matrix create-user ` to mint a fresh access token for the agent. **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 (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] ` ###### **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 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 ` ###### **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] ` ###### **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` * `-f`, `--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] ` ###### **Arguments:** * `` — Username to remove ###### **Options:** * `-f`, `--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 ` — 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 ` ###### **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] ` ###### **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 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 ` ###### **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 `` 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
` — 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 `` from the peer's `hivectl wg init` **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 (`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 ` — 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. Runs claude as the agent user from its state dir with the harness's settings / MCP / system prompt. Bare `choom ` is a fresh session; `--resume ` 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] ` ###### **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** — 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 ` (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 ` — 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 `). A targeted `--agent ` start is never filtered. Requires the hive-c0re daemon **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 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 `). 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 ` — 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 ` ###### **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:** * `` — 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 ` ###### **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. 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 ` 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 ` ###### **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//` 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 ## `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//` 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] ` ###### **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 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.`. 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:** * `` — Which surface to open. Defaults to the operator dashboard Default value: `home` Possible values: - `home`: The operator dashboard (`https:///`) - `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 ` ###### **Arguments:** * `` — Shell to emit completions for Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`
This document was generated automatically by clap-markdown.