keep hivectl verb help concise: short about + terse long help (#2512)
This commit is contained in:
damocles
mara
parent
39fd02235c
commit
30e48d202b
2 changed files with 219 additions and 306 deletions
|
|
@ -63,18 +63,18 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
|
|||
|
||||
###### **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)
|
||||
* `approvals` — Operator approval queue: list pending requests, approve / deny them. 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
|
||||
* `forge` — Forgejo user provisioning
|
||||
* `matrix` — matrix-tuwunel user provisioning
|
||||
* `github` — GitHub account provisioning
|
||||
* `gateway` — Gateway htpasswd user management
|
||||
* `agents` — Agent container management
|
||||
* `approvals` — Operator approval queue: list, approve, or deny pending requests
|
||||
* `wg` — WireGuard inter-hive mesh setup helpers
|
||||
* `peer-config` — Generate the federation peer-config block for THIS hive
|
||||
* `choom` — Open an interactive Claude session inside an agent container
|
||||
* `stop` — Stop containers hive-wide in one operator action. 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
|
||||
* `stop` — Stop containers hive-wide in one operator action
|
||||
* `start` — Start containers hive-wide — the inverse of `hivectl stop`
|
||||
* `restart` — Restart containers hive-wide — `stop` then `start` over one scope
|
||||
* `quota` — Per-agent disk accounting + optional quotas via btrfs qgroups
|
||||
* `subvol` — btrfs subvolume management for agent state dirs
|
||||
* `open` — Print (and best-effort open in a browser) a hive web surface URL
|
||||
|
|
@ -90,7 +90,9 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
|
|||
|
||||
## `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
|
||||
Forgejo user provisioning.
|
||||
|
||||
Manual entry point to the same idempotent provisioning c0re runs at boot — for recovery, ad-hoc reprovisioning, or fixing one agent without bouncing the daemon.
|
||||
|
||||
**Usage:** `hivectl forge <COMMAND>`
|
||||
|
||||
|
|
@ -104,11 +106,7 @@ Forgejo user provisioning. Manual entry point to the same idempotent flow c0re r
|
|||
|
||||
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).
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the token to stdout. Set a password to enable forge web-UI login (a random throwaway is used otherwise).
|
||||
|
||||
**Usage:** `hivectl forge create-user [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -125,17 +123,19 @@ Without `--password` / `--password-stdin` a random throwaway is used (fine for a
|
|||
|
||||
## `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
|
||||
matrix-tuwunel user provisioning.
|
||||
|
||||
Manual entry point to the same idempotent provisioning c0re runs at boot — for re-registering an agent the boot sweep skipped, or after wiping a token file.
|
||||
|
||||
**Usage:** `hivectl matrix <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
|
||||
* `sync-admin` — Provision (or re-provision) the hive system admin matrix account
|
||||
* `promote-user` — Promote a matrix user to homeserver admin
|
||||
* `reset-password` — Reset a matrix user's password via the admin API
|
||||
* `invite` — Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent
|
||||
|
||||
|
||||
|
||||
|
|
@ -143,11 +143,7 @@ matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow
|
|||
|
||||
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.
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the access token to stdout. Set a password to enable matrix web-client login (a random throwaway is used otherwise).
|
||||
|
||||
**Usage:** `hivectl matrix create-user [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -164,7 +160,9 @@ Without `--password` / `--password-stdin` a random throwaway is used (fine for a
|
|||
|
||||
## `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
|
||||
Provision (or re-provision) the hive system admin matrix account.
|
||||
|
||||
Runs automatically on startup; run manually to recover a missing admin token.
|
||||
|
||||
**Usage:** `hivectl matrix sync-admin`
|
||||
|
||||
|
|
@ -172,7 +170,7 @@ Provision (or re-provision) the hive system admin matrix account (`@hive:<server
|
|||
|
||||
## `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
|
||||
Promote a matrix user to homeserver admin
|
||||
|
||||
**Usage:** `hivectl matrix promote-user <NAME>`
|
||||
|
||||
|
|
@ -184,9 +182,9 @@ Promote a matrix user to homeserver admin via the admin API. Uses the hive syste
|
|||
|
||||
## `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.
|
||||
Reset a matrix user's password via the admin API.
|
||||
|
||||
After this command succeeds, run `hivectl matrix create-user <name>` to mint a fresh access token for the agent.
|
||||
Persists the new password so a later `create-user` can re-login.
|
||||
|
||||
**Usage:** `hivectl matrix reset-password <NAME>`
|
||||
|
||||
|
|
@ -198,7 +196,7 @@ After this command succeeds, run `hivectl matrix create-user <name>` to mint a f
|
|||
|
||||
## `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
|
||||
Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent
|
||||
|
||||
**Usage:** `hivectl matrix invite [OPTIONS] <USER>`
|
||||
|
||||
|
|
@ -214,19 +212,23 @@ Invite a matrix user to the hive Space (default) or a specific room. Uses the hi
|
|||
|
||||
## `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
|
||||
GitHub account provisioning.
|
||||
|
||||
Store an operator-supplied personal access token (PAT) for an agent so its `gh` and git can authenticate. No account is created — the PAT is for an existing GitHub account.
|
||||
|
||||
**Usage:** `hivectl github <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
|
||||
* `set-token` — Store a GitHub PAT for `<agent>` so its `gh` and git can authenticate
|
||||
|
||||
|
||||
|
||||
## `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
|
||||
Store a GitHub PAT for `<agent>` so its `gh` and git can authenticate.
|
||||
|
||||
Prefer `--token-stdin` — an inline `--token` is visible in shell history.
|
||||
|
||||
**Usage:** `hivectl github set-token [OPTIONS] <AGENT>`
|
||||
|
||||
|
|
@ -243,23 +245,25 @@ Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned
|
|||
|
||||
## `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
|
||||
Gateway htpasswd user management.
|
||||
|
||||
Add, remove, or list users for the gateway's HTTP Basic auth.
|
||||
|
||||
**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 daemon bcrypt-hashes the password (cost 12) and writes the credential store — hivectl relays over the host socket and never touches the file
|
||||
* `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
|
||||
* `create-user` — Add a user or update an existing user's password in the gateway htpasswd
|
||||
* `delete-user` — Remove a user from the gateway htpasswd
|
||||
* `list-users` — List all gateway htpasswd usernames, one per line
|
||||
|
||||
|
||||
|
||||
## `hivectl gateway create-user`
|
||||
|
||||
Add a new user or update the password of an existing user in the gateway htpasswd file. The daemon bcrypt-hashes the password (cost 12) and writes the credential store — hivectl relays over the host socket and never touches the file.
|
||||
Add a user or update an existing user's password in the gateway htpasswd.
|
||||
|
||||
Pass `--password-stdin` when scripting or when you don't want the password visible in shell history.
|
||||
Use `--password-stdin` to keep the password out of shell history.
|
||||
|
||||
**Usage:** `hivectl gateway create-user [OPTIONS] <USERNAME>`
|
||||
|
||||
|
|
@ -276,7 +280,7 @@ Pass `--password-stdin` when scripting or when you don't want the password visib
|
|||
|
||||
## `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
|
||||
Remove a user from the gateway htpasswd
|
||||
|
||||
**Usage:** `hivectl gateway delete-user <USERNAME>`
|
||||
|
||||
|
|
@ -296,27 +300,29 @@ List all gateway htpasswd usernames, one per line
|
|||
|
||||
## `hivectl agents`
|
||||
|
||||
Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
|
||||
Agent container management.
|
||||
|
||||
Lifecycle actions on managed agent containers. Needs the hive-c0re daemon running.
|
||||
|
||||
**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`
|
||||
* `spawn` — Spawn a new agent container directly (`h-<name>`). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use `request-spawn`
|
||||
* `request-spawn` — Queue a spawn request as an approval. The container is created on `hivectl approvals approve <id>` (or the dashboard APPR0VE button)
|
||||
* `list` — Show all managed agents with their status and technical state
|
||||
* `restart` — Stop and start a single agent container without rebuilding config
|
||||
* `restart-all` — Restart all managed agent containers
|
||||
* `spawn` — Spawn a new agent container directly, bypassing the approval queue
|
||||
* `request-spawn` — Queue a spawn request for operator approval
|
||||
* `kill` — Stop a managed container (graceful)
|
||||
* `destroy` — Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass `--purge` to also wipe the agent's state dirs (config + creds + notes). No undo
|
||||
* `destroy` — Tear down a sub-agent container, keeping its state by default. No undo
|
||||
* `rebuild` — Apply pending config to a managed container
|
||||
* `set-parent` — Move an agent in the topology tree. Set `--parent` to a new parent agent name, or pass `--root` to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents
|
||||
* `set-parent` — Move an agent in the topology tree — under a new parent, or to root
|
||||
|
||||
|
||||
|
||||
## `hivectl agents list`
|
||||
|
||||
Show all managed agents with their status (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
|
||||
Show all managed agents with their status and technical state
|
||||
|
||||
**Usage:** `hivectl agents list [OPTIONS]`
|
||||
|
||||
|
|
@ -328,7 +334,7 @@ Show all managed agents with their status (running / needs-login / needs-update)
|
|||
|
||||
## `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`
|
||||
Stop and start a single agent container without rebuilding config
|
||||
|
||||
**Usage:** `hivectl agents restart [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -344,7 +350,7 @@ Stop and start a single agent container without rebuilding config. Useful for "k
|
|||
|
||||
## `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`
|
||||
Restart all managed agent containers
|
||||
|
||||
**Usage:** `hivectl agents restart-all [OPTIONS]`
|
||||
|
||||
|
|
@ -356,7 +362,9 @@ Restart ALL managed agent containers via one restart DAG each — unrelated agen
|
|||
|
||||
## `hivectl agents spawn`
|
||||
|
||||
Spawn a new agent container directly (`h-<name>`). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use `request-spawn`
|
||||
Spawn a new agent container directly, bypassing the approval queue.
|
||||
|
||||
Operator-on-the-host only; use `request-spawn` for an approval-gated spawn.
|
||||
|
||||
**Usage:** `hivectl agents spawn <NAME>`
|
||||
|
||||
|
|
@ -368,7 +376,7 @@ Spawn a new agent container directly (`h-<name>`). Bypasses the approval queue
|
|||
|
||||
## `hivectl agents request-spawn`
|
||||
|
||||
Queue a spawn request as an approval. The container is created on `hivectl approvals approve <id>` (or the dashboard APPR0VE button)
|
||||
Queue a spawn request for operator approval
|
||||
|
||||
**Usage:** `hivectl agents request-spawn <NAME>`
|
||||
|
||||
|
|
@ -392,7 +400,7 @@ Stop a managed container (graceful)
|
|||
|
||||
## `hivectl agents destroy`
|
||||
|
||||
Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass `--purge` to also wipe the agent's state dirs (config + creds + notes). No undo
|
||||
Tear down a sub-agent container, keeping its state by default. No undo
|
||||
|
||||
**Usage:** `hivectl agents destroy [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -402,7 +410,7 @@ Tear down a sub-agent container. The container is removed; persistent state (con
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--purge`
|
||||
* `--purge` — Also wipe the agent's state dirs (config + creds + notes)
|
||||
|
||||
|
||||
|
||||
|
|
@ -420,7 +428,7 @@ Apply pending config to a managed container
|
|||
|
||||
## `hivectl agents set-parent`
|
||||
|
||||
Move an agent in the topology tree. Set `--parent` to a new parent agent name, or pass `--root` to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents
|
||||
Move an agent in the topology tree — under a new parent, or to root
|
||||
|
||||
**Usage:** `hivectl agents set-parent [OPTIONS] <CHILD>`
|
||||
|
||||
|
|
@ -437,7 +445,9 @@ Move an agent in the topology tree. Set `--parent` to a new parent agent name, o
|
|||
|
||||
## `hivectl approvals`
|
||||
|
||||
Operator approval queue: list pending requests, approve / deny them. Requires the hive-c0re daemon to be running (connects to the host admin socket)
|
||||
Operator approval queue: list, approve, or deny pending requests.
|
||||
|
||||
Needs the hive-c0re daemon running.
|
||||
|
||||
**Usage:** `hivectl approvals <COMMAND>`
|
||||
|
||||
|
|
@ -483,23 +493,23 @@ Deny a pending request by id
|
|||
|
||||
## `hivectl wg`
|
||||
|
||||
WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`).
|
||||
WireGuard inter-hive mesh setup helpers.
|
||||
|
||||
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.
|
||||
Generate this hive's mesh key and print the nix to enable the mesh, add a peer, or inspect live interface state.
|
||||
|
||||
**Usage:** `hivectl wg <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
|
||||
* `init` — Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh
|
||||
* `peer` — Print the nix to add a peer hive to the mesh
|
||||
* `status` — Show the live mesh interface state
|
||||
|
||||
|
||||
|
||||
## `hivectl wg init`
|
||||
|
||||
Generate (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
|
||||
Generate this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh
|
||||
|
||||
**Usage:** `hivectl wg init [OPTIONS]`
|
||||
|
||||
|
|
@ -511,7 +521,7 @@ Generate (if absent) this hive's WireGuard private key, print its public key, an
|
|||
|
||||
## `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`
|
||||
Print the nix to add a peer hive to the mesh
|
||||
|
||||
**Usage:** `hivectl wg peer [OPTIONS] --pubkey <PUBKEY> --address <ADDRESS> <DOMAIN>`
|
||||
|
||||
|
|
@ -529,7 +539,7 @@ Print the nix snippet to add a peer hive to the mesh. Pure output — paste it i
|
|||
|
||||
## `hivectl wg status`
|
||||
|
||||
Show the live mesh interface state (`wg show wg-hive`). Requires the mesh to be enabled + up
|
||||
Show the live mesh interface state
|
||||
|
||||
**Usage:** `hivectl wg status`
|
||||
|
||||
|
|
@ -537,7 +547,9 @@ Show the live mesh interface state (`wg show wg-hive`). Requires the mesh to be
|
|||
|
||||
## `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
|
||||
Generate the federation peer-config block for THIS hive.
|
||||
|
||||
Prints the nix a peer operator pastes into their swarm config to trust and reach this hive.
|
||||
|
||||
**Usage:** `hivectl peer-config [OPTIONS]`
|
||||
|
||||
|
|
@ -552,7 +564,7 @@ Generate the federation peer-config block for THIS hive — the nix a peer opera
|
|||
|
||||
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.
|
||||
A fresh session by default, or resume a prior one. Requires root and a running container.
|
||||
|
||||
**Usage:** `hivectl choom [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -568,7 +580,9 @@ Runs claude as the agent user from its state dir with the harness's settings / M
|
|||
|
||||
## `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
|
||||
Stop containers hive-wide in one operator action.
|
||||
|
||||
Bare `hivectl stop` stops everything; scope flags narrow it to specific sub-agents or infra containers.
|
||||
|
||||
**Usage:** `hivectl stop [OPTIONS]`
|
||||
|
||||
|
|
@ -587,7 +601,9 @@ Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **ev
|
|||
|
||||
## `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
|
||||
Start containers hive-wide — the inverse of `hivectl stop`.
|
||||
|
||||
Bare `hivectl start` restores the agents stopped by the last broad-scope `stop` (or starts everything if none); scope flags narrow it.
|
||||
|
||||
**Usage:** `hivectl start [OPTIONS]`
|
||||
|
||||
|
|
@ -605,7 +621,9 @@ Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl star
|
|||
|
||||
## `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
|
||||
Restart containers hive-wide — `stop` then `start` over one scope.
|
||||
|
||||
Bare `hivectl restart` restarts everything; scope flags narrow it.
|
||||
|
||||
**Usage:** `hivectl restart [OPTIONS]`
|
||||
|
||||
|
|
@ -625,21 +643,23 @@ Restart containers hive-wide — `stop` then `start` over the same scope. Bare `
|
|||
|
||||
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.
|
||||
Opt-in: enable qgroup accounting, then report per-agent usage or cap an agent. No-op on non-btrfs hosts.
|
||||
|
||||
**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
|
||||
* `enable` — Enable btrfs qgroup accounting on the agent-state filesystem
|
||||
* `show` — Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
|
||||
* `limit` — Set or clear an agent's disk-usage quota
|
||||
|
||||
|
||||
|
||||
## `hivectl quota enable`
|
||||
|
||||
Enable btrfs qgroup accounting on the agent-state filesystem. Run once before `show` / `limit`. 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
|
||||
Enable btrfs qgroup accounting on the agent-state filesystem.
|
||||
|
||||
Run once before `show` / `limit`. No-op on non-btrfs hosts.
|
||||
|
||||
**Usage:** `hivectl quota enable`
|
||||
|
||||
|
|
@ -647,7 +667,7 @@ Enable btrfs qgroup accounting on the agent-state filesystem. Run once before `s
|
|||
|
||||
## `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
|
||||
Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
|
||||
|
||||
**Usage:** `hivectl quota show [NAME]`
|
||||
|
||||
|
|
@ -659,7 +679,7 @@ Report per-agent disk usage (referenced + exclusive bytes) from btrfs qgroups. W
|
|||
|
||||
## `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
|
||||
Set or clear an agent's disk-usage quota
|
||||
|
||||
**Usage:** `hivectl quota limit <NAME> <SIZE>`
|
||||
|
||||
|
|
@ -674,20 +694,22 @@ Set or clear an agent's disk quota (a referenced-usage cap). `size` accepts a by
|
|||
|
||||
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).
|
||||
Upgrade an existing plain-dir agent's state into a btrfs subvolume so it gains snapshots and per-subvol usage/quota.
|
||||
|
||||
**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
|
||||
* `upgrade` — Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota
|
||||
* `snapshot` — Read-only snapshots of an agent's state subvolume
|
||||
|
||||
|
||||
|
||||
## `hivectl subvol upgrade`
|
||||
|
||||
Convert 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
|
||||
Convert a plain-dir agent state root into a btrfs subvolume in place, so it gains snapshots and per-subvol usage/quota.
|
||||
|
||||
Bounces the agent to migrate its state, so it requires `--yes`.
|
||||
|
||||
**Usage:** `hivectl subvol upgrade [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -703,13 +725,13 @@ Convert an existing plain-dir agent state root into a btrfs subvolume in place.
|
|||
|
||||
## `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
|
||||
Read-only snapshots of an agent's state subvolume
|
||||
|
||||
**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
|
||||
* `create` — Create a read-only snapshot (agent must already be a subvolume)
|
||||
* `delete` — Delete a snapshot created by `subvol snapshot create`
|
||||
* `send` — Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
|
||||
|
||||
|
|
@ -717,7 +739,7 @@ Read-only snapshots of an agent's state subvolume — the first step of the (in-
|
|||
|
||||
## `hivectl subvol snapshot create`
|
||||
|
||||
Create a read-only snapshot. Agent must already be a subvolume (`subvol upgrade` first). Prints the snapshot's host path
|
||||
Create a read-only snapshot (agent must already be a subvolume)
|
||||
|
||||
**Usage:** `hivectl subvol snapshot create --label <LABEL> <NAME>`
|
||||
|
||||
|
|
@ -766,7 +788,7 @@ Export a snapshot to a local file via `btrfs send` (the local-file half of inter
|
|||
|
||||
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.
|
||||
Resolves the URL from the running daemon so custom forge / matrix domains work. Bare `hivectl open` opens the operator dashboard.
|
||||
|
||||
**Usage:** `hivectl open [TARGET]`
|
||||
|
||||
|
|
@ -791,7 +813,7 @@ Resolves the URL from the running daemon (`HostRequest::Urls`), so custom forge
|
|||
|
||||
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.
|
||||
Supports bash, zsh, fish, elvish, and powershell. The NixOS module already installs the zsh script system-wide; this is for ad-hoc or other-shell use.
|
||||
|
||||
**Usage:** `hivectl completions <SHELL>`
|
||||
|
||||
|
|
|
|||
|
|
@ -53,77 +53,67 @@ struct Cli {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum Cmd {
|
||||
/// 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.
|
||||
/// Forgejo user provisioning.
|
||||
///
|
||||
/// Manual entry point to the same idempotent provisioning c0re runs at
|
||||
/// boot — for recovery, ad-hoc reprovisioning, or fixing one agent
|
||||
/// without bouncing the daemon.
|
||||
Forge {
|
||||
#[command(subcommand)]
|
||||
cmd: ForgeCmd,
|
||||
},
|
||||
/// 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.
|
||||
/// matrix-tuwunel user provisioning.
|
||||
///
|
||||
/// Manual entry point to the same idempotent provisioning c0re runs at
|
||||
/// boot — for re-registering an agent the boot sweep skipped, or after
|
||||
/// wiping a token file.
|
||||
Matrix {
|
||||
#[command(subcommand)]
|
||||
cmd: MatrixCmd,
|
||||
},
|
||||
/// 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.
|
||||
/// GitHub account provisioning.
|
||||
///
|
||||
/// Store an operator-supplied personal access token (PAT) for an agent
|
||||
/// so its `gh` and git can authenticate. No account is created — the
|
||||
/// PAT is for an existing GitHub account.
|
||||
Github {
|
||||
#[command(subcommand)]
|
||||
cmd: GithubCmd,
|
||||
},
|
||||
/// 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.
|
||||
/// Gateway htpasswd user management.
|
||||
///
|
||||
/// Add, remove, or list users for the gateway's HTTP Basic auth.
|
||||
Gateway {
|
||||
#[command(subcommand)]
|
||||
cmd: GatewayCmd,
|
||||
},
|
||||
/// Agent container management. Requires the hive-c0re daemon to be
|
||||
/// running (connects to the host admin socket).
|
||||
/// Agent container management.
|
||||
///
|
||||
/// Lifecycle actions on managed agent containers. Needs the hive-c0re
|
||||
/// daemon running.
|
||||
Agents {
|
||||
#[command(subcommand)]
|
||||
cmd: AgentsCmd,
|
||||
},
|
||||
/// Operator approval queue: list pending requests, approve / deny them.
|
||||
/// Requires the hive-c0re daemon to be running (connects to the host
|
||||
/// admin socket).
|
||||
/// Operator approval queue: list, approve, or deny pending requests.
|
||||
///
|
||||
/// Needs the hive-c0re daemon running.
|
||||
Approvals {
|
||||
#[command(subcommand)]
|
||||
cmd: ApprovalsCmd,
|
||||
},
|
||||
/// WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`).
|
||||
/// WireGuard inter-hive mesh setup helpers.
|
||||
///
|
||||
/// 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.
|
||||
/// Generate this hive's mesh key and print the nix to enable the mesh,
|
||||
/// add a peer, or inspect live interface state.
|
||||
Wg {
|
||||
#[command(subcommand)]
|
||||
cmd: WgCmd,
|
||||
},
|
||||
/// 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.
|
||||
/// Generate the federation peer-config block for THIS hive.
|
||||
///
|
||||
/// Prints the nix a peer operator pastes into their swarm config to
|
||||
/// trust and reach this hive.
|
||||
PeerConfig {
|
||||
/// This hive's WireGuard mesh address (e.g. `10.42.0.1/32`),
|
||||
/// emitted as `wireguardAddress`. Omit when not running the mesh.
|
||||
|
|
@ -136,11 +126,8 @@ enum Cmd {
|
|||
},
|
||||
/// 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.
|
||||
/// A fresh session by default, or resume a prior one. Requires root
|
||||
/// and a running container.
|
||||
Choom {
|
||||
/// Agent name (e.g. `damocles`, `iris`).
|
||||
name: String,
|
||||
|
|
@ -153,14 +140,10 @@ enum Cmd {
|
|||
#[arg(long = "resume", value_name = "SESSION")]
|
||||
resume_session: Option<String>,
|
||||
},
|
||||
/// 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.
|
||||
/// Stop containers hive-wide in one operator action.
|
||||
///
|
||||
/// Bare `hivectl stop` stops everything; scope flags narrow it to
|
||||
/// specific sub-agents or infra containers.
|
||||
Stop {
|
||||
#[command(flatten)]
|
||||
scope: ScopeArgs,
|
||||
|
|
@ -177,13 +160,11 @@ enum Cmd {
|
|||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
},
|
||||
/// 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.
|
||||
/// Start containers hive-wide — the inverse of `hivectl stop`.
|
||||
///
|
||||
/// Bare `hivectl start` restores the agents stopped by the last
|
||||
/// broad-scope `stop` (or starts everything if none); scope flags
|
||||
/// narrow it.
|
||||
Start {
|
||||
#[command(flatten)]
|
||||
scope: ScopeArgs,
|
||||
|
|
@ -192,13 +173,9 @@ enum Cmd {
|
|||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
},
|
||||
/// 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.
|
||||
/// Restart containers hive-wide — `stop` then `start` over one scope.
|
||||
///
|
||||
/// Bare `hivectl restart` restarts everything; scope flags narrow it.
|
||||
Restart {
|
||||
#[command(flatten)]
|
||||
scope: ScopeArgs,
|
||||
|
|
@ -209,36 +186,24 @@ enum Cmd {
|
|||
},
|
||||
/// 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.
|
||||
/// Opt-in: enable qgroup accounting, then report per-agent usage or
|
||||
/// cap an agent. No-op on non-btrfs hosts.
|
||||
Quota {
|
||||
#[command(subcommand)]
|
||||
cmd: QuotaCmd,
|
||||
},
|
||||
/// 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).
|
||||
/// Upgrade an existing plain-dir agent's state into a btrfs subvolume
|
||||
/// so it gains snapshots and per-subvol usage/quota.
|
||||
Subvol {
|
||||
#[command(subcommand)]
|
||||
cmd: SubvolCmd,
|
||||
},
|
||||
/// 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.
|
||||
/// Resolves the URL from the running daemon so custom forge / matrix
|
||||
/// domains work. Bare `hivectl open` opens the operator dashboard.
|
||||
Open {
|
||||
/// Which surface to open. Defaults to the operator dashboard.
|
||||
#[arg(value_enum, default_value_t = OpenTarget::Home)]
|
||||
|
|
@ -246,21 +211,16 @@ enum Cmd {
|
|||
},
|
||||
/// Emit the full CLI reference as `CommonMark` to stdout.
|
||||
///
|
||||
/// Hidden tooling command (not part of day-to-day operator admin):
|
||||
/// walks this binary's own clap command tree and renders every verb,
|
||||
/// flag, and help string as markdown. Used by the docs build to keep
|
||||
/// the published `hivectl` reference in lockstep with the code — no
|
||||
/// hand-maintained command list to drift out of date.
|
||||
/// Hidden tooling command used by the docs build to keep the published
|
||||
/// `hivectl` reference in lockstep with the code.
|
||||
#[command(hide = true)]
|
||||
MarkdownDocs,
|
||||
/// 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.
|
||||
/// Supports bash, zsh, fish, elvish, and powershell. The NixOS module
|
||||
/// already installs the zsh script system-wide; this is for ad-hoc or
|
||||
/// other-shell use.
|
||||
Completions {
|
||||
/// Shell to emit completions for.
|
||||
shell: clap_complete::Shell,
|
||||
|
|
@ -325,24 +285,9 @@ impl ScopeArgs {
|
|||
enum ForgeCmd {
|
||||
/// 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).
|
||||
/// For an existing agent, persists the token to its state dir; for a
|
||||
/// human/other account, prints the token to stdout. Set a password to
|
||||
/// enable forge web-UI login (a random throwaway is used otherwise).
|
||||
CreateUser {
|
||||
/// Forgejo username. For agents: the container/agent name
|
||||
/// (`<n>` in `h-<n>`; manager uses the literal `manager`).
|
||||
|
|
@ -368,20 +313,10 @@ enum ForgeCmd {
|
|||
enum MatrixCmd {
|
||||
/// 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.
|
||||
/// For an existing agent, persists the token to its state dir; for a
|
||||
/// human/other account, prints the access token to stdout. Set a
|
||||
/// password to enable matrix web-client login (a random throwaway is
|
||||
/// used otherwise).
|
||||
CreateUser {
|
||||
/// Matrix localpart. For agents: the container/agent name.
|
||||
/// For humans: any matrix localpart — `mara`, `damocles`, etc.
|
||||
|
|
@ -400,34 +335,25 @@ enum MatrixCmd {
|
|||
#[arg(long, conflicts_with = "password")]
|
||||
password_stdin: bool,
|
||||
},
|
||||
/// 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.
|
||||
/// Provision (or re-provision) the hive system admin matrix account.
|
||||
///
|
||||
/// Runs automatically on startup; run manually to recover a missing
|
||||
/// admin token.
|
||||
SyncAdmin,
|
||||
/// 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.
|
||||
/// Promote a matrix user to homeserver admin.
|
||||
PromoteUser {
|
||||
/// Matrix localpart of the user to promote (e.g. `argus`).
|
||||
name: String,
|
||||
},
|
||||
/// 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.
|
||||
/// Reset a matrix user's password via the admin API.
|
||||
///
|
||||
/// After this command succeeds, run `hivectl matrix create-user
|
||||
/// <name>` to mint a fresh access token for the agent.
|
||||
/// Persists the new password so a later `create-user` can re-login.
|
||||
ResetPassword {
|
||||
/// Matrix localpart of the account to reset (e.g. `argus`).
|
||||
name: String,
|
||||
},
|
||||
/// 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.
|
||||
/// Invite a matrix user to the hive Space, or a specific room with
|
||||
/// `--room`. Idempotent.
|
||||
Invite {
|
||||
/// User to invite: a full id (`@mara:server`) or a bare
|
||||
/// localpart (qualified with the homeserver's `server_name`).
|
||||
|
|
@ -441,13 +367,11 @@ enum MatrixCmd {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum GithubCmd {
|
||||
/// 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.
|
||||
/// Store a GitHub PAT for `<agent>` so its `gh` and git can
|
||||
/// authenticate.
|
||||
///
|
||||
/// Prefer `--token-stdin` — an inline `--token` is visible in shell
|
||||
/// history.
|
||||
SetToken {
|
||||
/// Logical agent name (the container/agent name).
|
||||
agent: String,
|
||||
|
|
@ -463,13 +387,10 @@ enum GithubCmd {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum GatewayCmd {
|
||||
/// Add a new user or update the password of an existing user in the
|
||||
/// gateway htpasswd file. The daemon bcrypt-hashes the password (cost 12)
|
||||
/// and writes the credential store — hivectl relays over the host socket
|
||||
/// and never touches the file.
|
||||
/// Add a user or update an existing user's password in the gateway
|
||||
/// htpasswd.
|
||||
///
|
||||
/// Pass `--password-stdin` when scripting or when you don't want the
|
||||
/// password visible in shell history.
|
||||
/// Use `--password-stdin` to keep the password out of shell history.
|
||||
CreateUser {
|
||||
/// Username to add or update.
|
||||
username: String,
|
||||
|
|
@ -483,8 +404,7 @@ enum GatewayCmd {
|
|||
#[arg(long)]
|
||||
password_stdin: bool,
|
||||
},
|
||||
/// 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.
|
||||
/// Remove a user from the gateway htpasswd.
|
||||
DeleteUser {
|
||||
/// Username to remove.
|
||||
username: String,
|
||||
|
|
@ -495,19 +415,15 @@ enum GatewayCmd {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum WgCmd {
|
||||
/// 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.
|
||||
/// Generate this hive's WireGuard key (if absent) and print its public
|
||||
/// key plus the nix to enable the mesh.
|
||||
Init {
|
||||
/// 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.
|
||||
#[arg(long)]
|
||||
address: Option<String>,
|
||||
},
|
||||
/// 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`.
|
||||
/// Print the nix to add a peer hive to the mesh.
|
||||
Peer {
|
||||
/// Peer hive's DNS domain (the `swarm.peers` attrset key).
|
||||
domain: String,
|
||||
|
|
@ -522,29 +438,23 @@ enum WgCmd {
|
|||
#[arg(long)]
|
||||
endpoint: Option<String>,
|
||||
},
|
||||
/// Show the live mesh interface state (`wg show wg-hive`). Requires the
|
||||
/// mesh to be enabled + up.
|
||||
/// Show the live mesh interface state.
|
||||
Status,
|
||||
}
|
||||
|
||||
#[derive(Subcommand)]
|
||||
enum QuotaCmd {
|
||||
/// 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.
|
||||
/// Enable btrfs qgroup accounting on the agent-state filesystem.
|
||||
///
|
||||
/// Run once before `show` / `limit`. No-op on non-btrfs hosts.
|
||||
Enable,
|
||||
/// 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.
|
||||
/// Report per-agent disk usage from btrfs qgroups (all agents, or one
|
||||
/// by name).
|
||||
Show {
|
||||
/// Agent to show (omit for all agents with a state subvolume).
|
||||
name: Option<String>,
|
||||
},
|
||||
/// 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.
|
||||
/// Set or clear an agent's disk-usage quota.
|
||||
Limit {
|
||||
/// Agent whose state subvolume to limit.
|
||||
name: String,
|
||||
|
|
@ -560,10 +470,7 @@ use hive_host_sock::HOST_SOCKET as DEFAULT_HOST_SOCKET;
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum AgentsCmd {
|
||||
/// 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.
|
||||
/// Show all managed agents with their status and technical state.
|
||||
List {
|
||||
/// Emit the raw JSON rows instead of the padded table (for
|
||||
/// scripting). The table is the default human-readable shape.
|
||||
|
|
@ -571,10 +478,6 @@ enum AgentsCmd {
|
|||
json: bool,
|
||||
},
|
||||
/// 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 {
|
||||
/// Agent name (e.g. `damocles`, `ruth`).
|
||||
name: String,
|
||||
|
|
@ -582,23 +485,21 @@ enum AgentsCmd {
|
|||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
},
|
||||
/// 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`.
|
||||
/// Restart all managed agent containers.
|
||||
RestartAll {
|
||||
/// Return immediately after the restart DAGs are queued.
|
||||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
},
|
||||
/// Spawn a new agent container directly (`h-<name>`). Bypasses the
|
||||
/// approval queue — operator-on-the-host only. For approval-gated
|
||||
/// spawns, use `request-spawn`.
|
||||
/// Spawn a new agent container directly, bypassing the approval queue.
|
||||
///
|
||||
/// Operator-on-the-host only; use `request-spawn` for an approval-gated
|
||||
/// spawn.
|
||||
Spawn {
|
||||
/// Agent name (e.g. `iris`).
|
||||
name: String,
|
||||
},
|
||||
/// Queue a spawn request as an approval. The container is created on
|
||||
/// `hivectl approvals approve <id>` (or the dashboard APPR0VE button).
|
||||
/// Queue a spawn request for operator approval.
|
||||
RequestSpawn {
|
||||
/// Agent name.
|
||||
name: String,
|
||||
|
|
@ -608,13 +509,12 @@ enum AgentsCmd {
|
|||
/// Agent name.
|
||||
name: String,
|
||||
},
|
||||
/// Tear down a sub-agent container. The container is removed; persistent
|
||||
/// state (config repos + Claude credentials) is kept by default. Pass
|
||||
/// `--purge` to also wipe the agent's state dirs (config + creds +
|
||||
/// notes). No undo.
|
||||
/// Tear down a sub-agent container, keeping its state by default. No
|
||||
/// undo.
|
||||
Destroy {
|
||||
/// Agent name.
|
||||
name: String,
|
||||
/// Also wipe the agent's state dirs (config + creds + notes).
|
||||
#[arg(long)]
|
||||
purge: bool,
|
||||
},
|
||||
|
|
@ -623,9 +523,7 @@ enum AgentsCmd {
|
|||
/// Agent name.
|
||||
name: String,
|
||||
},
|
||||
/// Move an agent in the topology tree. Set `--parent` to a new parent
|
||||
/// agent name, or pass `--root` to promote the agent to root (no
|
||||
/// parent). Exactly one is required. Refuses cycles and unknown agents.
|
||||
/// Move an agent in the topology tree — under a new parent, or to root.
|
||||
SetParent {
|
||||
/// Agent to move.
|
||||
child: String,
|
||||
|
|
@ -638,8 +536,7 @@ enum AgentsCmd {
|
|||
},
|
||||
}
|
||||
|
||||
/// Operator approval queue: list pending requests and approve / deny them.
|
||||
/// Requires the hive-c0re daemon (connects to the host admin socket).
|
||||
/// Operator approval queue: list, approve, or deny pending requests.
|
||||
#[derive(Subcommand)]
|
||||
enum ApprovalsCmd {
|
||||
/// List pending approval requests submitted by agents.
|
||||
|
|
@ -658,13 +555,10 @@ enum ApprovalsCmd {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum SubvolCmd {
|
||||
/// 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.
|
||||
/// Convert a plain-dir agent state root into a btrfs subvolume in
|
||||
/// place, so it gains snapshots and per-subvol usage/quota.
|
||||
///
|
||||
/// Bounces the agent to migrate its state, so it requires `--yes`.
|
||||
Upgrade {
|
||||
/// Agent name (e.g. `damocles`, `iris`).
|
||||
name: String,
|
||||
|
|
@ -673,9 +567,7 @@ enum SubvolCmd {
|
|||
#[arg(long)]
|
||||
yes: bool,
|
||||
},
|
||||
/// 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.
|
||||
/// Read-only snapshots of an agent's state subvolume.
|
||||
Snapshot {
|
||||
#[command(subcommand)]
|
||||
cmd: SnapshotCmd,
|
||||
|
|
@ -684,8 +576,7 @@ enum SubvolCmd {
|
|||
|
||||
#[derive(Subcommand)]
|
||||
enum SnapshotCmd {
|
||||
/// Create a read-only snapshot. Agent must already be a subvolume
|
||||
/// (`subvol upgrade` first). Prints the snapshot's host path.
|
||||
/// Create a read-only snapshot (agent must already be a subvolume).
|
||||
Create {
|
||||
/// Agent name (e.g. `damocles`, `iris`).
|
||||
name: String,
|
||||
|
|
|
|||
Loading…
Reference in a new issue