Command-Line Help for hivectl

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

Command Overview:

• hivectl↴
• hivectl forge↴
• hivectl forge create-user↴
• hivectl matrix↴
• hivectl matrix create-user↴
• hivectl matrix sync-admin↴
• hivectl matrix promote-user↴
• hivectl matrix reset-password↴
• hivectl matrix invite↴
• hivectl gateway↴
• hivectl gateway create-user↴
• hivectl gateway delete-user↴
• hivectl gateway list-users↴
• hivectl agents↴
• hivectl agents restart↴
• hivectl agents restart-all↴
• hivectl choom↴

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

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 [OPTIONS] <NAME>

Arguments:

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

Options:

• --socket <SOCKET> — Path to the hive-c0re host admin socket

  Default value: /run/hyperhive/host.sock

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 [OPTIONS]

Options:

• --socket <SOCKET> — Path to the hive-c0re host admin socket

  Default value: /run/hyperhive/host.sock

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

This document was generated automatically by clap-markdown.