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
atlas 5da1ef4963 hivectl: trim --graceful doc to 'applies to agents only' 
Drop the enumeration of what the flag does not apply to, per operator
review on the sibling graceful-stop change. Regenerate the CLI doc so
the markdown-docs self-diff check stays in sync.
2026-06-19 12:30:25 +02:00

19 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. 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
  • 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)
  • 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 starts everything back up; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). 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
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 flow c0re runs automatically at boot (forge::ensure_all) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes without bouncing the daemon

Usage: hivectl forge <COMMAND>

Subcommands:
  • create-user — Create or refresh the Forgejo account + token for <name>

hivectl forge create-user

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).

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 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

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

hivectl matrix create-user

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.

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 (@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

Usage: hivectl matrix sync-admin

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

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 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.

After this command succeeds, run hivectl matrix create-user <name> to mint a fresh access token for the agent.

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 (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

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 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

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 password is hashed with BCrypt (cost 12)
  • 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
  • list-users — List all usernames in the gateway htpasswd file, 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 password is hashed with BCrypt (cost 12).

Pass --password-stdin when scripting or when you don't want the password visible in shell history. The file is created if it does not exist; its parent directory must already exist.

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

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store at /var/lib/hyperhive/gateway/gateway.htpasswd

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

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

Usage: hivectl gateway delete-user [OPTIONS] <USERNAME>

Arguments:
  • <USERNAME> — Username to remove
Options:

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

hivectl gateway list-users

List all usernames in the gateway htpasswd file, one per line

Usage: hivectl gateway list-users [OPTIONS]

Options:

  • -f, --file <FILE> — Path to the htpasswd file. Defaults to the standard gateway credential store

    Default value: /var/lib/hyperhive/gateway/gateway.htpasswd

hivectl agents

Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)

Usage: hivectl agents <COMMAND>

Subcommands:
  • 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
  • restart-all — Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt

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

Usage: hivectl agents restart <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, ruth)

hivectl agents restart-all

Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt

Usage: hivectl agents restart-all

hivectl choom

Open an interactive Claude session inside an agent container.

Replaces the current process with machinectl shell <name>@h-<name> running claude --continue from the agent's state dir — drops the operator straight into the agent's live Claude session with its full loaded context and persona. Requires root (same as all machinectl shell operations) and the container must be running.

To match the harness exactly, choom enters as the agent user (not root) so claude reads the OAuth credentials from the agent's /home/<name>/.claude; runs from the agent's state dir (/agents/<name>/state) so --continue resumes the right per-project session and CLAUDE.md loads; and passes the same --settings / --mcp-config / --system-prompt-file the harness writes to /run/hive-config/ (settings, MCP tools, role prompt). Entering as root (the machinectl shell default) loses all of it.

Pass --fresh to start a new Claude session instead of continuing the most recent one.

Usage: hivectl choom [OPTIONS] <NAME>

Arguments:
  • <NAME> — Agent name (e.g. damocles, iris)
Options:
  • --fresh — Start a fresh Claude session instead of continuing the most recent one. Without this flag --continue is passed to Claude so the operator joins the agent's ongoing session context

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

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 is enqueued as a GracefulStop on the rebuild 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). Applies to agents only

hivectl start

Start containers hive-wide — the inverse of hivectl stop. Bare hivectl start starts everything back up; the same scope flags as stop narrow it (--agents, --ci, --forge, --gateway, --matrix, --agent <name>). Requires the hive-c0re daemon

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)

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

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

This document was generated automatically by clap-markdown.