vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/tools/hivectl-cli.md

27 KiB
Raw Blame History

Command-Line Help for hivectl

This document contains the help content for the hivectl command-line program.

Command Overview:

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
  • pause — Park an agent's turn loop, leaving the container running
  • resume — Resume a paused agent — it drains whatever queued up while parked
  • 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 pause

Park an 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 agents pause <NAME>

Arguments:
  • <NAME> — Agent name

hivectl agents resume

Resume a paused agent — it drains whatever queued up while parked

Usage: hivectl agents resume <NAME>

Arguments:
  • <NAME> — Agent name

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

This document was generated automatically by clap-markdown.