# hivectl

`hivectl` is the operator-facing host CLI for hyperhive. It lives on the
host (not inside any container) and requires root for most operations.
Available via the `hive-c0re` package in the host NixOS config.

Unlike the `hive-c0re` daemon subcommands (which go through the broker),
`hivectl` covers direct host-side administration: manual provisioning of
forge + matrix accounts, gateway htpasswd management, container
lifecycle shortcuts, and interactive agent shell access.

This page is the curated guide. For the exhaustive flag-by-flag
reference auto-generated from the binary's own command tree, see
[`hivectl-cli.md`](hivectl-cli.md) — emitted by the hidden `hivectl
markdown-docs` subcommand and kept in lockstep with the code by the
`hivectl-docs` flake check (CI fails if the committed copy drifts).
Regenerate with `nix build .#default && ./result/bin/hivectl
markdown-docs > docs/tools/hivectl-cli.md`.

## Forge

Manual entry to the same idempotent provisioning flow `hive-c0re` runs
at boot. Useful for recovery, ad-hoc re-provisioning, or fixing a single
agent without bouncing the daemon.

```bash
hivectl forge create-user iris          # provision (or refresh) forge account for agent `iris`
hivectl forge create-user mara          # create forge account for a human user; prints token to stdout
hivectl forge create-user mara --password hunter2  # set a web-login password
hivectl forge create-user mara --password-stdin    # read password from stdin (safer for scripting)
```

- For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
  token is persisted to `<state>/forge-token`. Re-running refreshes the
  token (idempotent — scope always matches current `TOKEN_SCOPES`).
- For **non-agents** (humans): creates the account and prints the token to
  stdout; no state dir is created. Re-running after account already exists
  re-mints the token and prints it again — safe for password resets.
- Without `--password` / `--password-stdin` a random throwaway password
  is used (fine for agents — they auth by token).

## Matrix

Manual entry to the same idempotent matrix provisioning flow
`hive-c0re` runs at boot. Requires the `hive-matrix` container to be
running (`services.hyperhive.matrix.enable = true`).

```bash
hivectl matrix create-user iris         # provision (or re-provision) matrix account for agent `iris`
hivectl matrix create-user mara         # create matrix account for a human; prints access_token to stdout
hivectl matrix create-user mara --password hunter2  # set a client-login password
hivectl matrix sync-admin               # provision / refresh the hive internal admin account
hivectl matrix promote-user mara        # promote an existing matrix user to homeserver admin
hivectl matrix reset-password iris      # generate and set a new random password for `iris`; prints it
hivectl matrix invite mara              # invite a user to the hive Space
hivectl matrix invite @mara:server --room '#hive-chat:server'  # ...or to a specific room/alias
```

- `create-user`: for agents, persists the `access_token` to
  `<state>/matrix-token`. Skips registration when the file already
  exists — delete it first to force re-registration.
- `sync-admin`: ensures the hive's internal admin matrix user exists
  (used by `hive-c0re` for admin-room commands). Token persisted to the
  admin token path. Safe to run again — idempotent.
- `promote-user`: promotes an already-registered user to homeserver
  admin via the matrix admin API. Requires `sync-admin` to have run
  first (needs a valid admin token).
- `reset-password`: calls the matrix admin API to set a new random
  password and prints it to stdout. Useful if an agent or human lost
  credentials.
- `invite`: invites a matrix user (full `@user:server` or a bare
  localpart, qualified with the homeserver's `server_name`) to the hive
  Space by default, or to a `--room` id / `#alias`. Uses the hive admin
  token; the admin account must be a member of the target room with
  invite power (it owns the hive Space, so that case always works).
  Idempotent — already-member / already-invited is a no-op.

## Gateway

Manage users in the gateway's HTTP Basic auth htpasswd file
(`services.hyperhive.gateway.auth`). All commands default to
`/var/lib/hyperhive/gateway/gateway.htpasswd`; pass `--file` to target
a different path.

```bash
hivectl gateway create-user alice --password-stdin  # add (or update) user; read password from stdin
hivectl gateway create-user bob --password hunter2  # add user inline (visible in shell history)
hivectl gateway delete-user bob                     # remove user
hivectl gateway list-users                          # list all usernames, one per line
```

Passwords are hashed with BCrypt (cost 12). The file is created if it
does not exist. Re-running `create-user` with the same username updates
the password hash in place.

## Agents

Container lifecycle shortcuts that go through the host admin socket.
Requires the `hive-c0re` daemon to be running.

```bash
hivectl agents restart iris        # stop + start the `iris` container (no rebuild)
hivectl agents restart-all         # stop + start every managed agent container in sequence
```

`restart` is the manual equivalent of the MCP `restart` tool — useful
when you need to kick a container from the host without going through
the agent hierarchy. Failures on `restart-all` are collected and
reported at the end rather than aborting mid-run.

## Choom

Drop into 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. Requires root
(same as all `machinectl shell` operations).

```bash
hivectl choom iris                # join iris's ongoing Claude session (--continue)
hivectl choom iris --fresh        # start a new Claude session instead
```

Without `--fresh`, `--continue` is passed so the operator joins the
agent's live context window. With `--fresh` a clean session starts.
The container must be running.

choom reproduces the harness's own claude invocation so the operator
lands in a faithful copy of the agent's environment:

- **as the agent user**, not root: `machinectl shell` defaults to root,
  which would make claude read `/root/.claude` (empty) instead of the
  agent's `/home/<name>/.claude` where its OAuth credentials live. choom
  prefixes the machine with `<name>@` (the meta-flake sets the agent's
  unix user name to its label).
- **from `/agents/<name>/state`**: `--continue` resolves the session for
  that project dir and `CLAUDE.md` (the persona) loads from the cwd.
- **with the harness flags**: `--settings`, `--mcp-config`, and
  `--system-prompt-file` from `/run/hive-config/` — the same files the
  harness writes each turn — so the operator gets the agent's settings,
  the hyperhive/matrix MCP tools (which `--continue` needs to replay a
  tool-using history), and the role prompt. Each flag is included only
  when its file exists.