# hivectl

The operator-facing host CLI for hyperhive. A thin client for the
`hive-c0re` daemon: it speaks the host admin socket protocol
(`hive-host-sock`) and does **not** link the daemon crate.

Container lifecycle + the approval queue (`agents <spawn|kill|rebuild|
restart|…>`, `approvals <pending|approve|deny>`, `stop`/`start`) and
provisioning (`forge`/`matrix`/`github`/`gateway`) all forward to the
daemon, which owns the broker, the credentials, and the provisioning
logic — a running daemon is required for those verbs. A few verbs work
off local host state directly instead, so they don't need the socket:
`wg`/`peer-config` read the mesh key + TLS CA, and `choom` execs into a
container.

## When to use it

Reach for this crate when you're adding a new operator-run host
command, not an agent-run one — agents talk to the daemon over their
own per-agent MCP tool surface (`hive-agent-mcp`), not this binary.
`hivectl` is what a human operator (or a script on the host) runs.

## Shape

One module per subcommand family; `main.rs` is just the clap parse +
top-level dispatch match.

- **`cli.rs`** — the clap `Cli`/`Cmd` derive tree every other module's
  `Args` hangs off of.
- **`client.rs`** — the host admin socket client (`request`), split out
  so it lives with `hivectl` rather than in the daemon crate.
- **`agents.rs`** — `agents <spawn|kill|destroy|rebuild|restart|list|
  set-parent|…>` — container lifecycle.
- **`approvals.rs`** — `approvals <pending|approve|deny>` — the config/
  init-config/meta-input approval queue.
- **`dag_progress.rs`** — rebuild-queue progress rendering: everything
  that polls the daemon's DAG queue (`HostRequest::QueueDag`) and
  renders per-DAG / per-node progress (spinner or plain), split out
  because `agents.rs` was already large.
- **`power.rs`** — `restart`/`start`/`stop` at the container level.
- **`choom.rs`** — `hivectl choom <agent>`: drop into an interactive
  Claude session inside an agent container by exec-ing `machinectl
  shell` running claude as the agent user, mirroring the harness's own
  per-turn claude invocation.
- **`forge.rs`**, **`matrix.rs`**, **`github.rs`**, **`gateway.rs`** —
  per-agent account/token provisioning for each integration
  (`forge create-user`, `matrix …`, `github set-token`, `gateway
  create-user|delete-user|list-users`).
- **`wg.rs`** — `wg`/`peer-config`: WireGuard mesh helpers — generate
  this hive's key + the nix snippets to enable the mesh, add a peer,
  print the block a peer pastes to federate with us, show the live
  interface.
- **`subvol.rs`** — `agents subvol`: btrfs state-subvolume ops (migrate
  a plain-dir agent state root to a subvolume, snapshot create/delete/
  send).
- **`quota.rs`** — resource-quota reporting/enforcement helpers shared
  across the above.
- **`open.rs`** — `open <url>`: opens a hive URL (dashboard, agent UI)
  in the operator's browser.
- **`completions.rs`** — shell-completion generation
  (`clap_complete`/`clap-markdown`).
- **`util.rs`** — small shared helpers (formatting, table rendering)
  used across subcommand modules.

Full verb reference: `docs/tools/hivectl.md`.