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 8ea19b3b12 feat(#1897): always auto-fill the hive domain — drop the --domain override 
Per operator review (#1899): the hive's own domain should never be
typed by hand. Remove the --domain flag from peer-config and wg init
entirely; both now resolve it from the daemon (HostRequest::HiveDomain).
peer-config errors with a clear hint if the daemon can't answer; wg init
prints the peer block best-effort (skips it, still enables the mesh, if
unresolved). Regenerated docs/tools/hivectl-cli.md.
2026-06-22 19:07:56 +02:00

538 lines
28 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 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 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 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
* `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` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). 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
* `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 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:**
* `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
* `restart-all` — Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt
## `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
**Usage:** `hivectl agents restart <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name (e.g. `damocles`, `ruth`)
## `hivectl agents restart-all`
Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt
**Usage:** `hivectl agents restart-all`
## `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.
Replaces the current process with `machinectl shell <name>@h-<name>` running `claude --continue` from the agent's state dir — drops the operator straight into the agent's live Claude session with its full loaded context and persona. Requires root (same as all machinectl shell operations) and the container must be running.
To match the harness exactly, choom enters **as the agent user** (not root) so claude reads the OAuth credentials from the agent's `/home/<name>/.claude`; runs from the agent's state dir (`/agents/<name>/state`) so `--continue` resumes the right per-project session and `CLAUDE.md` loads; and passes the same `--settings` / `--mcp-config` / `--system-prompt-file` the harness writes to `/run/hive-config/` (settings, MCP tools, role prompt). Entering as root (the `machinectl shell` default) loses all of it.
Pass `--fresh` to start a new Claude session instead of continuing the most recent one.
**Usage:** `hivectl choom [OPTIONS] <NAME>`
###### **Arguments:**
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
###### **Options:**
* `--fresh` — Start a fresh Claude session instead of continuing the most recent one. Without this flag `--continue` is passed to Claude so the operator joins the agent's ongoing session context
## `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 is enqueued as a `GracefulStop` on the rebuild 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). Applies to agents only
## `hivectl start`
Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). 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`)
## `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
## `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 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