7b23b53b75
docs/tools/hivectl-cli.md is generated by `hivectl markdown-docs` and diffed against a fresh run by the hivectl-docs flake check, so adding the push verb without regenerating it would have failed CI. The regeneration also retires two copies of a sentence describing the cross-hive leg as an ssh pipe that "isn't wired up yet" -- ssh was dropped when the WireGuard mesh became the authentication, and the leg is wired up now. snapshot-store.md documented only the receiving host, so a reader had no way to learn how a pushing hive is told where the store is. It now covers services.hyperhive.swarm.snapshotStore, including why address has no default and port does: an address is a deployment fact that cannot be guessed, a port is a convention both ends read from the same docs. It also states the namespace rule the two options illustrate -- swarm.* describes the swarm as seen from here, a bare services.hyperhive.<service> describes a role this host performs. swarm.md never mentioned the store even though the option lives in its namespace, so a reader configuring swarm.peers had no signal it exists.
881 lines
29 KiB
Markdown
881 lines
29 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 agent`↴](#hivectl-agent)
|
|
* [`hivectl agent restart`↴](#hivectl-agent-restart)
|
|
* [`hivectl agent pause`↴](#hivectl-agent-pause)
|
|
* [`hivectl agent resume`↴](#hivectl-agent-resume)
|
|
* [`hivectl agent spawn`↴](#hivectl-agent-spawn)
|
|
* [`hivectl agent request-spawn`↴](#hivectl-agent-request-spawn)
|
|
* [`hivectl agent kill`↴](#hivectl-agent-kill)
|
|
* [`hivectl agent destroy`↴](#hivectl-agent-destroy)
|
|
* [`hivectl agent rebuild`↴](#hivectl-agent-rebuild)
|
|
* [`hivectl agent set-parent`↴](#hivectl-agent-set-parent)
|
|
* [`hivectl agent set-limits`↴](#hivectl-agent-set-limits)
|
|
* [`hivectl agent choom`↴](#hivectl-agent-choom)
|
|
* [`hivectl agent watch`↴](#hivectl-agent-watch)
|
|
* [`hivectl agent quota`↴](#hivectl-agent-quota)
|
|
* [`hivectl agent quota show`↴](#hivectl-agent-quota-show)
|
|
* [`hivectl agent quota set`↴](#hivectl-agent-quota-set)
|
|
* [`hivectl agent subvol`↴](#hivectl-agent-subvol)
|
|
* [`hivectl agent subvol upgrade`↴](#hivectl-agent-subvol-upgrade)
|
|
* [`hivectl agent subvol snapshot`↴](#hivectl-agent-subvol-snapshot)
|
|
* [`hivectl agent subvol snapshot create`↴](#hivectl-agent-subvol-snapshot-create)
|
|
* [`hivectl agent subvol snapshot delete`↴](#hivectl-agent-subvol-snapshot-delete)
|
|
* [`hivectl agent subvol snapshot send`↴](#hivectl-agent-subvol-snapshot-send)
|
|
* [`hivectl agent subvol snapshot push`↴](#hivectl-agent-subvol-snapshot-push)
|
|
* [`hivectl list-agents`↴](#hivectl-list-agents)
|
|
* [`hivectl quota-enable`↴](#hivectl-quota-enable)
|
|
* [`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 stop`↴](#hivectl-stop)
|
|
* [`hivectl start`↴](#hivectl-start)
|
|
* [`hivectl restart`↴](#hivectl-restart)
|
|
* [`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
|
|
* `agent` — Lifecycle actions on ONE managed agent container. Needs the hive-c0re daemon running
|
|
* `list-agents` — Show all managed agents with their status and technical state
|
|
* `quota-enable` — Enable btrfs qgroup accounting on the agent-state filesystem
|
|
* `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
|
|
* `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
|
|
* `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 (`agent`, `list-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 agent`
|
|
|
|
Lifecycle actions on ONE managed agent container. Needs the hive-c0re daemon running.
|
|
|
|
Everything here targets a single named agent (`hivectl agent foo restart`, `hivectl agent foo choom`, …) — anything that acts hive-wide lives at the top level instead (`list-agents`, `restart`/`stop`/`start` with a scope, `quota-enable`).
|
|
|
|
**Usage:** `hivectl agent <NAME> <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `restart` — Stop and start this agent container without rebuilding config
|
|
* `pause` — Park this agent's turn loop, leaving the container running
|
|
* `resume` — Resume this paused agent — it drains whatever queued up while parked
|
|
* `spawn` — Spawn this agent container directly, bypassing the approval queue
|
|
* `request-spawn` — Queue a spawn request for operator approval
|
|
* `kill` — Stop this managed container (graceful)
|
|
* `destroy` — Tear down this sub-agent container, keeping its state by default. No undo
|
|
* `rebuild` — Apply pending config to this managed container
|
|
* `set-parent` — Move this agent in the topology tree — under a new parent, or to root
|
|
* `set-limits` — Declare this agent's CPU/memory limits, overriding the hive-wide defaults
|
|
* `choom` — Open an interactive Claude session inside this agent's container
|
|
* `watch` — Follow this agent's live turn/tool-call event stream from the CLI
|
|
* `quota` — This agent's disk accounting + optional quota via btrfs qgroups
|
|
* `subvol` — btrfs subvolume management for this agent's state dir
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
|
|
|
|
|
|
|
|
## `hivectl agent restart`
|
|
|
|
Stop and start this agent container without rebuilding config
|
|
|
|
**Usage:** `hivectl agent restart [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--no-wait` — Return immediately after the restart DAG is queued
|
|
|
|
|
|
|
|
## `hivectl agent pause`
|
|
|
|
Park this agent's turn loop, leaving the container running.
|
|
|
|
The harness stops driving turns but keeps serving its web UI and MCP daemons, so the container, its mounts and its warm caches stay up while it burns no tokens. Inbox messages queue unacked and the backlog drains on `resume`. Sticky: it survives a restart, and pausing a stopped agent makes it come up paused.
|
|
|
|
**Usage:** `hivectl agent pause`
|
|
|
|
|
|
|
|
## `hivectl agent resume`
|
|
|
|
Resume this paused agent — it drains whatever queued up while parked
|
|
|
|
**Usage:** `hivectl agent resume`
|
|
|
|
|
|
|
|
## `hivectl agent spawn`
|
|
|
|
Spawn this agent container directly, bypassing the approval queue.
|
|
|
|
Operator-on-the-host only; use `request-spawn` for an approval-gated spawn.
|
|
|
|
**Usage:** `hivectl agent spawn`
|
|
|
|
|
|
|
|
## `hivectl agent request-spawn`
|
|
|
|
Queue a spawn request for operator approval
|
|
|
|
**Usage:** `hivectl agent request-spawn`
|
|
|
|
|
|
|
|
## `hivectl agent kill`
|
|
|
|
Stop this managed container (graceful)
|
|
|
|
**Usage:** `hivectl agent kill`
|
|
|
|
|
|
|
|
## `hivectl agent destroy`
|
|
|
|
Tear down this sub-agent container, keeping its state by default. No undo
|
|
|
|
**Usage:** `hivectl agent destroy [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--purge` — Also wipe the agent's state dirs (config + creds + notes)
|
|
|
|
|
|
|
|
## `hivectl agent rebuild`
|
|
|
|
Apply pending config to this managed container
|
|
|
|
**Usage:** `hivectl agent rebuild`
|
|
|
|
|
|
|
|
## `hivectl agent set-parent`
|
|
|
|
Move this agent in the topology tree — under a new parent, or to root
|
|
|
|
**Usage:** `hivectl agent set-parent [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--parent <PARENT>` — New parent agent name. Mutually exclusive with `--root`
|
|
* `--root` — Promote this agent to root (no parent)
|
|
|
|
|
|
|
|
## `hivectl agent set-limits`
|
|
|
|
Declare this agent's CPU/memory limits, overriding the hive-wide defaults.
|
|
|
|
Replaces the agent's whole override entry rather than merging into it: any limit you don't pass returns to the hive-wide default. To change one and keep the other, pass both. Disk is a separate resource with its own group — see `quota`.
|
|
|
|
**Usage:** `hivectl agent set-limits [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--cpu-quota <CPU_QUOTA>` — systemd `CPUQuota=` value, e.g. `400%` (100% = one full core)
|
|
* `--memory-max <MEMORY_MAX>` — systemd `MemoryMax=` value, e.g. `8G`, `50%`, or `infinity`
|
|
* `--reset` — Drop all overrides — the agent returns to the hive-wide defaults. Required to clear limits, so that a `set-limits` with a forgotten value can't silently reset the agent
|
|
|
|
|
|
|
|
## `hivectl agent choom`
|
|
|
|
Open an interactive Claude session inside this agent's container.
|
|
|
|
A fresh session by default, or resume a prior one. Requires root and a running container.
|
|
|
|
**Usage:** `hivectl agent choom [OPTIONS]`
|
|
|
|
###### **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 agent watch`
|
|
|
|
Follow this agent's live turn/tool-call event stream from the CLI.
|
|
|
|
Prints one compact line per event as they happen. `Ctrl-C` to stop. Requires the agent to be running.
|
|
|
|
**Usage:** `hivectl agent watch`
|
|
|
|
|
|
|
|
## `hivectl agent quota`
|
|
|
|
This agent's disk accounting + optional quota via btrfs qgroups.
|
|
|
|
Needs `hivectl quota-enable` run once hive-wide first. No-op on non-btrfs hosts.
|
|
|
|
**Usage:** `hivectl agent quota <COMMAND>`
|
|
|
|
###### **Subcommands:**
|
|
|
|
* `show` — Report this agent's disk usage from btrfs qgroups
|
|
* `set` — Set or clear this agent's disk-usage quota
|
|
|
|
|
|
|
|
## `hivectl agent quota show`
|
|
|
|
Report this agent's disk usage from btrfs qgroups
|
|
|
|
**Usage:** `hivectl agent quota show`
|
|
|
|
|
|
|
|
## `hivectl agent quota set`
|
|
|
|
Set or clear this agent's disk-usage quota
|
|
|
|
**Usage:** `hivectl agent quota set <SIZE>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<SIZE>` — Size cap (`5G`, `500M`, `1073741824`) or `none` to clear
|
|
|
|
|
|
|
|
## `hivectl agent subvol`
|
|
|
|
btrfs subvolume management for this agent's state dir.
|
|
|
|
Upgrade an existing plain-dir agent's state into a btrfs subvolume so it gains snapshots and per-subvol usage/quota.
|
|
|
|
**Usage:** `hivectl agent 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 this agent's state subvolume
|
|
|
|
|
|
|
|
## `hivectl agent 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 agent subvol upgrade [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--yes` — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it
|
|
|
|
|
|
|
|
## `hivectl agent subvol snapshot`
|
|
|
|
Read-only snapshots of this agent's state subvolume
|
|
|
|
**Usage:** `hivectl agent 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 the inter-hive migration transport (`push` is the network half). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
|
|
* `push` — Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport
|
|
|
|
|
|
|
|
## `hivectl agent subvol snapshot create`
|
|
|
|
Create a read-only snapshot (agent must already be a subvolume)
|
|
|
|
**Usage:** `hivectl agent subvol snapshot create --label <LABEL>`
|
|
|
|
###### **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 agent subvol snapshot delete`
|
|
|
|
Delete a snapshot created by `subvol snapshot create`
|
|
|
|
**Usage:** `hivectl agent subvol snapshot delete <LABEL>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
|
|
|
|
|
|
|
|
## `hivectl agent subvol snapshot send`
|
|
|
|
Export a snapshot to a local file via `btrfs send` — the local-file half of the inter-hive migration transport (`push` is the network half). 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 agent subvol snapshot send [OPTIONS] --dest <DEST> <LABEL>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<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 agent subvol snapshot push`
|
|
|
|
Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport.
|
|
|
|
Nothing is staged locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here.
|
|
|
|
There is no destination argument: a swarm has one store, read from `services.hyperhive.swarm.snapshotStore`.
|
|
|
|
**Usage:** `hivectl agent subvol snapshot push [OPTIONS] <LABEL>`
|
|
|
|
###### **Arguments:**
|
|
|
|
* `<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, and must already be present on the receiver. Omit for a full send
|
|
|
|
|
|
|
|
## `hivectl list-agents`
|
|
|
|
Show all managed agents with their status and technical state.
|
|
|
|
Global — not scoped to one agent, so it lives at the top level rather than under `hivectl agent <name>`. Needs the hive-c0re daemon running.
|
|
|
|
**Usage:** `hivectl list-agents [OPTIONS]`
|
|
|
|
###### **Options:**
|
|
|
|
* `--json` — Emit the raw JSON rows instead of the padded table (for scripting). The table is the default human-readable shape
|
|
|
|
|
|
|
|
## `hivectl quota-enable`
|
|
|
|
Enable btrfs qgroup accounting on the agent-state filesystem.
|
|
|
|
Global one-shot toggle (not per-agent), hence top-level rather than under `hivectl agent <name>`. Idempotent — safe to re-run. Once enabled, `hivectl agent <name> quota show`/`quota set` work.
|
|
|
|
**Usage:** `hivectl quota-enable`
|
|
|
|
|
|
|
|
## `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 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 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>
|