305 lines
15 KiB
Markdown
305 lines
15 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 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 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 agents`↴](#hivectl-agents)
|
|
* [`hivectl agents restart`↴](#hivectl-agents-restart)
|
|
* [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
|
|
* [`hivectl choom`↴](#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
|
|
|
|
|
|
|
|
<hr/>
|
|
|
|
<small><i>
|
|
This document was generated automatically by
|
|
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
|
|
</i></small>
|