862 lines
26 KiB
Markdown
862 lines
26 KiB
Markdown
# Command-Line Help for `hivectl`
|
|
|
|
This document contains the help content for the `hivectl` command-line program.
|
|
|
|
**Command Overview:**
|
|
|
|
* [`hivectl`↴](#hivectl)
|
|
* [`hivectl forge`↴](#hivectl-forge)
|
|
* [`hivectl forge create-user`↴](#hivectl-forge-create-user)
|
|
* [`hivectl forge reconcile-config`↴](#hivectl-forge-reconcile-config)
|
|
* [`hivectl matrix`↴](#hivectl-matrix)
|
|
* [`hivectl matrix create-user`↴](#hivectl-matrix-create-user)
|
|
* [`hivectl matrix sync-admin`↴](#hivectl-matrix-sync-admin)
|
|
* [`hivectl matrix promote-user`↴](#hivectl-matrix-promote-user)
|
|
* [`hivectl matrix reset-password`↴](#hivectl-matrix-reset-password)
|
|
* [`hivectl matrix invite`↴](#hivectl-matrix-invite)
|
|
* [`hivectl github`↴](#hivectl-github)
|
|
* [`hivectl github set-token`↴](#hivectl-github-set-token)
|
|
* [`hivectl gateway`↴](#hivectl-gateway)
|
|
* [`hivectl gateway create-user`↴](#hivectl-gateway-create-user)
|
|
* [`hivectl gateway delete-user`↴](#hivectl-gateway-delete-user)
|
|
* [`hivectl gateway list-users`↴](#hivectl-gateway-list-users)
|
|
* [`hivectl agents`↴](#hivectl-agents)
|
|
* [`hivectl agents list`↴](#hivectl-agents-list)
|
|
* [`hivectl agents restart`↴](#hivectl-agents-restart)
|
|
* [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
|
|
* [`hivectl agents spawn`↴](#hivectl-agents-spawn)
|
|
* [`hivectl agents request-spawn`↴](#hivectl-agents-request-spawn)
|
|
* [`hivectl agents kill`↴](#hivectl-agents-kill)
|
|
* [`hivectl agents destroy`↴](#hivectl-agents-destroy)
|
|
* [`hivectl agents rebuild`↴](#hivectl-agents-rebuild)
|
|
* [`hivectl agents set-parent`↴](#hivectl-agents-set-parent)
|
|
* [`hivectl approvals`↴](#hivectl-approvals)
|
|
* [`hivectl approvals pending`↴](#hivectl-approvals-pending)
|
|
* [`hivectl approvals approve`↴](#hivectl-approvals-approve)
|
|
* [`hivectl approvals deny`↴](#hivectl-approvals-deny)
|
|
* [`hivectl wg`↴](#hivectl-wg)
|
|
* [`hivectl wg init`↴](#hivectl-wg-init)
|
|
* [`hivectl wg peer`↴](#hivectl-wg-peer)
|
|
* [`hivectl wg status`↴](#hivectl-wg-status)
|
|
* [`hivectl peer-config`↴](#hivectl-peer-config)
|
|
* [`hivectl choom`↴](#hivectl-choom)
|
|
* [`hivectl stop`↴](#hivectl-stop)
|
|
* [`hivectl start`↴](#hivectl-start)
|
|
* [`hivectl restart`↴](#hivectl-restart)
|
|
* [`hivectl quota`↴](#hivectl-quota)
|
|
* [`hivectl quota enable`↴](#hivectl-quota-enable)
|
|
* [`hivectl quota show`↴](#hivectl-quota-show)
|
|
* [`hivectl quota limit`↴](#hivectl-quota-limit)
|
|
* [`hivectl subvol`↴](#hivectl-subvol)
|
|
* [`hivectl subvol upgrade`↴](#hivectl-subvol-upgrade)
|
|
* [`hivectl subvol snapshot`↴](#hivectl-subvol-snapshot)
|
|
* [`hivectl subvol snapshot create`↴](#hivectl-subvol-snapshot-create)
|
|
* [`hivectl subvol snapshot delete`↴](#hivectl-subvol-snapshot-delete)
|
|
* [`hivectl subvol snapshot send`↴](#hivectl-subvol-snapshot-send)
|
|
* [`hivectl open`↴](#hivectl-open)
|
|
* [`hivectl completions`↴](#hivectl-completions)
|
|
|
|
## `hivectl`
|
|
|
|
Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that don't go through the broker — manual user provisioning on the bundled forge + matrix containers, plus future recovery / debugging verbs.
|
|
|
|
**Usage:** `hivectl [OPTIONS] <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `forge` — Forgejo user provisioning
|
|
* `matrix` — matrix-tuwunel user provisioning
|
|
* `github` — GitHub account provisioning
|
|
* `gateway` — Gateway htpasswd user management
|
|
* `agents` — Agent container management
|
|
* `approvals` — Operator approval queue: list, approve, or deny pending requests
|
|
* `wg` — WireGuard inter-hive mesh setup helpers
|
|
* `peer-config` — Generate the federation peer-config block for THIS hive
|
|
* `choom` — Open an interactive Claude session inside an agent container
|
|
* `stop` — Stop containers hive-wide in one operator action
|
|
* `start` — Start containers hive-wide — the inverse of `hivectl stop`
|
|
* `restart` — Restart containers hive-wide — `stop` then `start` over one scope
|
|
* `quota` — Per-agent disk accounting + optional quotas via btrfs qgroups
|
|
* `subvol` — btrfs subvolume management for agent state dirs
|
|
* `open` — Print (and best-effort open in a browser) a hive web surface URL
|
|
* `completions` — Generate a shell completion script for `hivectl` and print it to stdout
|
|
|
|
###### **Options:**
|
|
|
|
* `--socket <SOCKET>` — Path to the hive-c0re host admin socket, used by the daemon-assisted verbs (`agents`, `stop`, `start`). Global: accepted before or after the subcommand. Verbs that don't talk to the daemon ignore it
|
|
|
|
Default value: `/run/hyperhive/host.sock`
|
|
|
|
|
|
|
|
## `hivectl forge`
|
|
|
|
Forgejo user provisioning.
|
|
|
|
Manual entry point to the same idempotent provisioning c0re runs at boot — for recovery, ad-hoc reprovisioning, or fixing one agent without bouncing the daemon.
|
|
|
|
**Usage:** `hivectl forge <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `create-user` — Create or refresh the Forgejo account + token for `<name>`
|
|
* `reconcile-config` — Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/<agent>` main
|
|
|
|
|
|
|
|
## `hivectl forge create-user`
|
|
|
|
Create or refresh the Forgejo account + token for `<name>`.
|
|
|
|
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>`
|
|
|
|
###### **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 forge reconcile-config`
|
|
|
|
Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/<agent>` main.
|
|
|
|
Always prints the diff first. `--from forge` resets the local checkout to forge main (effective on the next deploy); `--from local` is not supported yet. With no `--from`, prompts for the direction.
|
|
|
|
**Usage:** `hivectl forge reconcile-config [OPTIONS] <AGENT>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<AGENT>` — Agent whose config branches to reconcile
|
|
|
|
###### **Options:**
|
|
|
|
* `--from <FROM>` — Which side to reconcile from. Omit to be prompted after the diff
|
|
|
|
Possible values:
|
|
- `forge`:
|
|
Reset the local applied checkout to forge main
|
|
- `local`:
|
|
Advance forge main from local — not supported yet
|
|
|
|
* `--verbose` — Include the full diff (not just `--stat`) in the report
|
|
|
|
|
|
|
|
## `hivectl matrix`
|
|
|
|
matrix-tuwunel user provisioning.
|
|
|
|
Manual entry point to the same idempotent provisioning c0re runs at boot — for re-registering an agent the boot sweep skipped, or after wiping a token file.
|
|
|
|
**Usage:** `hivectl matrix <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
|
|
* `promote-user` — Promote a matrix user to homeserver admin
|
|
* `reset-password` — Reset a matrix user's password via the admin API
|
|
* `invite` — Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent
|
|
|
|
|
|
|
|
## `hivectl matrix create-user`
|
|
|
|
Create or refresh the matrix account + access token for `<name>`.
|
|
|
|
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>`
|
|
|
|
###### **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.
|
|
|
|
Runs automatically on startup; run manually to recover a missing admin token.
|
|
|
|
**Usage:** `hivectl matrix sync-admin`
|
|
|
|
|
|
|
|
## `hivectl matrix promote-user`
|
|
|
|
Promote a matrix user to homeserver admin
|
|
|
|
**Usage:** `hivectl matrix promote-user <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.
|
|
|
|
Persists the new password so a later `create-user` can re-login.
|
|
|
|
**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, or a specific room with `--room`. Idempotent
|
|
|
|
**Usage:** `hivectl matrix invite [OPTIONS] <USER>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<USER>` — User to invite: a full id (`@mara:server`) or a bare localpart (qualified with the homeserver's `server_name`)
|
|
|
|
###### **Options:**
|
|
|
|
* `--room <ROOM>` — Target room id (`!abc:server`) or alias (`#name:server`). Omit to invite to the hive Space
|
|
|
|
|
|
|
|
## `hivectl github`
|
|
|
|
GitHub account provisioning.
|
|
|
|
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` — Store a GitHub PAT for `<agent>` so its `gh` and git can authenticate
|
|
|
|
|
|
|
|
## `hivectl github set-token`
|
|
|
|
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>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<AGENT>` — Logical agent name (the container/agent name)
|
|
|
|
###### **Options:**
|
|
|
|
* `--token <TOKEN>` — The PAT value inline. Mutually exclusive with `--token-stdin`
|
|
* `--token-stdin` — Read the PAT from stdin (trailing newline stripped). Mutually exclusive with `--token`
|
|
|
|
|
|
|
|
## `hivectl gateway`
|
|
|
|
Gateway htpasswd user management.
|
|
|
|
Add, remove, or list users for the gateway's HTTP Basic auth.
|
|
|
|
**Usage:** `hivectl gateway <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `create-user` — Add a user or update an existing user's password in the gateway htpasswd
|
|
* `delete-user` — Remove a user from the gateway htpasswd
|
|
* `list-users` — List all gateway htpasswd usernames, one per line
|
|
|
|
|
|
|
|
## `hivectl gateway create-user`
|
|
|
|
Add a user or update an existing user's password in the gateway htpasswd.
|
|
|
|
Use `--password-stdin` to keep the password out of shell history.
|
|
|
|
**Usage:** `hivectl gateway create-user [OPTIONS] <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`
|
|
|
|
|
|
|
|
## `hivectl gateway delete-user`
|
|
|
|
Remove a user from the gateway htpasswd
|
|
|
|
**Usage:** `hivectl gateway delete-user <USERNAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<USERNAME>` — Username to remove
|
|
|
|
|
|
|
|
## `hivectl gateway list-users`
|
|
|
|
List all gateway htpasswd usernames, one per line
|
|
|
|
**Usage:** `hivectl gateway list-users`
|
|
|
|
|
|
|
|
## `hivectl agents`
|
|
|
|
Agent container management.
|
|
|
|
Lifecycle actions on managed agent containers. Needs the hive-c0re daemon running.
|
|
|
|
**Usage:** `hivectl agents <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `list` — Show all managed agents with their status and technical state
|
|
* `restart` — Stop and start a single agent container without rebuilding config
|
|
* `restart-all` — Restart all managed agent containers
|
|
* `spawn` — Spawn a new agent container directly, bypassing the approval queue
|
|
* `request-spawn` — Queue a spawn request for operator approval
|
|
* `kill` — Stop a managed container (graceful)
|
|
* `destroy` — Tear down a sub-agent container, keeping its state by default. No undo
|
|
* `rebuild` — Apply pending config to a managed container
|
|
* `set-parent` — Move an agent in the topology tree — under a new parent, or to root
|
|
|
|
|
|
|
|
## `hivectl agents list`
|
|
|
|
Show all managed agents with their status and technical state
|
|
|
|
**Usage:** `hivectl agents list [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--json` — Emit the raw JSON rows instead of the padded table (for scripting). The table is the default human-readable shape
|
|
|
|
|
|
|
|
## `hivectl agents restart`
|
|
|
|
Stop and start a single agent container without rebuilding config
|
|
|
|
**Usage:** `hivectl agents restart [OPTIONS] <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `damocles`, `ruth`)
|
|
|
|
###### **Options:**
|
|
|
|
* `--no-wait` — Return immediately after the restart DAG is queued
|
|
|
|
|
|
|
|
## `hivectl agents restart-all`
|
|
|
|
Restart all managed agent containers
|
|
|
|
**Usage:** `hivectl agents restart-all [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--no-wait` — Return immediately after the restart DAGs are queued
|
|
|
|
|
|
|
|
## `hivectl agents spawn`
|
|
|
|
Spawn a new agent container directly, bypassing the approval queue.
|
|
|
|
Operator-on-the-host only; use `request-spawn` for an approval-gated spawn.
|
|
|
|
**Usage:** `hivectl agents spawn <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `iris`)
|
|
|
|
|
|
|
|
## `hivectl agents request-spawn`
|
|
|
|
Queue a spawn request for operator approval
|
|
|
|
**Usage:** `hivectl agents request-spawn <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name
|
|
|
|
|
|
|
|
## `hivectl agents kill`
|
|
|
|
Stop a managed container (graceful)
|
|
|
|
**Usage:** `hivectl agents kill <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name
|
|
|
|
|
|
|
|
## `hivectl agents destroy`
|
|
|
|
Tear down a sub-agent container, keeping its state by default. No undo
|
|
|
|
**Usage:** `hivectl agents destroy [OPTIONS] <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name
|
|
|
|
###### **Options:**
|
|
|
|
* `--purge` — Also wipe the agent's state dirs (config + creds + notes)
|
|
|
|
|
|
|
|
## `hivectl agents rebuild`
|
|
|
|
Apply pending config to a managed container
|
|
|
|
**Usage:** `hivectl agents rebuild <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name
|
|
|
|
|
|
|
|
## `hivectl agents set-parent`
|
|
|
|
Move an agent in the topology tree — under a new parent, or to root
|
|
|
|
**Usage:** `hivectl agents set-parent [OPTIONS] <CHILD>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<CHILD>` — Agent to move
|
|
|
|
###### **Options:**
|
|
|
|
* `--parent <PARENT>` — New parent agent name. Mutually exclusive with `--root`
|
|
* `--root` — Promote `child` to root (no parent)
|
|
|
|
|
|
|
|
## `hivectl approvals`
|
|
|
|
Operator approval queue: list, approve, or deny pending requests.
|
|
|
|
Needs the hive-c0re daemon running.
|
|
|
|
**Usage:** `hivectl approvals <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `pending` — List pending approval requests submitted by agents
|
|
* `approve` — Approve a pending request by id; the action runs immediately
|
|
* `deny` — Deny a pending request by id
|
|
|
|
|
|
|
|
## `hivectl approvals pending`
|
|
|
|
List pending approval requests submitted by agents
|
|
|
|
**Usage:** `hivectl approvals pending`
|
|
|
|
|
|
|
|
## `hivectl approvals approve`
|
|
|
|
Approve a pending request by id; the action runs immediately
|
|
|
|
**Usage:** `hivectl approvals approve <ID>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<ID>` — Approval id (from `hivectl approvals pending`)
|
|
|
|
|
|
|
|
## `hivectl approvals deny`
|
|
|
|
Deny a pending request by id
|
|
|
|
**Usage:** `hivectl approvals deny <ID>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<ID>` — Approval id
|
|
|
|
|
|
|
|
## `hivectl wg`
|
|
|
|
WireGuard inter-hive mesh setup helpers.
|
|
|
|
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 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 this hive's WireGuard key (if absent) and print its public key plus the nix to enable the mesh
|
|
|
|
**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 to add a peer hive to the mesh
|
|
|
|
**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
|
|
|
|
**Usage:** `hivectl wg status`
|
|
|
|
|
|
|
|
## `hivectl peer-config`
|
|
|
|
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]`
|
|
|
|
###### **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.
|
|
|
|
A fresh session by default, or resume a prior one. Requires root and a running container.
|
|
|
|
**Usage:** `hivectl choom [OPTIONS] <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
|
|
|
|
###### **Options:**
|
|
|
|
* `--resume <SESSION>` — Resume a prior claude session by its session id, passed through as `claude --resume <value>` (claude's `--continue` takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. A value is required when the flag is given
|
|
|
|
|
|
|
|
## `hivectl stop`
|
|
|
|
Stop containers hive-wide in one operator action.
|
|
|
|
Bare `hivectl stop` stops everything; scope flags narrow it to specific sub-agents or infra containers.
|
|
|
|
**Usage:** `hivectl stop [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--agents` — All sub-agent containers
|
|
* `--agent <NAME>` — A specific sub-agent by name. Repeatable: `--agent a --agent b`
|
|
* `--ci` — The CI runner container (`hive-ci`)
|
|
* `--forge` — The forge container (`hive-forge`)
|
|
* `--gateway` — The gateway container (`hive-gateway`)
|
|
* `--matrix` — The matrix container (`hive-matrix`)
|
|
* `--graceful` — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent gets a graceful-stop DAG on the job queue: the harness is signalled, runs one stop-checkpoint turn to flush durable `/state`, drains, then the container is stopped (bounded by a 3-min timeout that falls back to a hard stop). All drains overlap. Applies to agents only
|
|
* `--no-wait` — Return immediately after the stop DAGs are queued instead of waiting for them with live per-node progress
|
|
|
|
|
|
|
|
## `hivectl start`
|
|
|
|
Start containers hive-wide — the inverse of `hivectl stop`.
|
|
|
|
Bare `hivectl start` restores the agents stopped by the last broad-scope `stop` (or starts everything if none); scope flags narrow it.
|
|
|
|
**Usage:** `hivectl start [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--agents` — All sub-agent containers
|
|
* `--agent <NAME>` — A specific sub-agent by name. Repeatable: `--agent a --agent b`
|
|
* `--ci` — The CI runner container (`hive-ci`)
|
|
* `--forge` — The forge container (`hive-forge`)
|
|
* `--gateway` — The gateway container (`hive-gateway`)
|
|
* `--matrix` — The matrix container (`hive-matrix`)
|
|
* `--no-wait` — Return immediately after the start DAGs are queued instead of waiting for them with live per-node progress
|
|
|
|
|
|
|
|
## `hivectl restart`
|
|
|
|
Restart containers hive-wide — `stop` then `start` over one scope.
|
|
|
|
Bare `hivectl restart` restarts everything; scope flags narrow it.
|
|
|
|
**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: 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
|
|
* `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`. No-op on non-btrfs hosts.
|
|
|
|
**Usage:** `hivectl quota enable`
|
|
|
|
|
|
|
|
## `hivectl quota show`
|
|
|
|
Report per-agent disk usage from btrfs qgroups (all agents, or one by name)
|
|
|
|
**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-usage quota
|
|
|
|
**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.
|
|
|
|
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 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 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>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
|
|
|
|
###### **Options:**
|
|
|
|
* `--yes` — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it
|
|
|
|
|
|
|
|
## `hivectl subvol snapshot`
|
|
|
|
Read-only snapshots of an agent's state subvolume
|
|
|
|
**Usage:** `hivectl subvol snapshot <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `create` — Create a read-only snapshot (agent must already be a subvolume)
|
|
* `delete` — Delete a snapshot created by `subvol snapshot create`
|
|
* `send` — Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
|
|
|
|
|
|
|
|
## `hivectl subvol snapshot create`
|
|
|
|
Create a read-only snapshot (agent must already be a subvolume)
|
|
|
|
**Usage:** `hivectl subvol snapshot create --label <LABEL> <NAME>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
|
|
|
|
###### **Options:**
|
|
|
|
* `--label <LABEL>` — Snapshot label. Mandatory, and must start with `hive-` — the prefix doubles as an allow-list hive-priv checks so only hivectl-issued snapshot names can reach the `btrfs subvolume snapshot` shellout
|
|
|
|
|
|
|
|
## `hivectl subvol snapshot delete`
|
|
|
|
Delete a snapshot created by `subvol snapshot create`
|
|
|
|
**Usage:** `hivectl subvol snapshot delete <NAME> <LABEL>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name the snapshot belongs to
|
|
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
|
|
|
|
|
|
|
|
## `hivectl subvol snapshot send`
|
|
|
|
Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
|
|
|
|
**Usage:** `hivectl subvol snapshot send [OPTIONS] --dest <DEST> <NAME> <LABEL>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name the snapshot belongs to
|
|
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
|
|
|
|
###### **Options:**
|
|
|
|
* `--parent <PARENT>` — Optional parent snapshot label for an incremental send (`btrfs send -p`) — must be an existing, older snapshot of the same agent. Omit for a full send
|
|
* `--dest <DEST>` — Destination filename (not a path) under the migrate-staging dir. Refused if it already exists
|
|
|
|
|
|
|
|
## `hivectl open`
|
|
|
|
Print (and best-effort open in a browser) a hive web surface URL.
|
|
|
|
Resolves the URL from the running daemon so custom forge / matrix domains work. Bare `hivectl open` opens the operator dashboard.
|
|
|
|
**Usage:** `hivectl open [TARGET]`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<TARGET>` — Which surface to open. Defaults to the operator dashboard
|
|
|
|
Default value: `home`
|
|
|
|
Possible values:
|
|
- `home`:
|
|
The operator dashboard (`https://<domain>/`)
|
|
- `forge`:
|
|
The forge (Forgejo) web UI
|
|
- `matrix`:
|
|
The matrix GUI (fluffychat)
|
|
|
|
|
|
|
|
|
|
## `hivectl completions`
|
|
|
|
Generate a shell completion script for `hivectl` and print it to stdout.
|
|
|
|
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>`
|
|
|
|
###### **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>
|