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

## GitHub

Write an operator-supplied GitHub personal access token (PAT) into an
agent's token file so its `gh` wrapper + git credential helper can act as
the configured bot account. Unlike forge/matrix there is no account
creation — the PAT is for an existing GitHub account. The agent must
declare [`hyperhive.githubAccount`](../github.md).

```bash
hivectl github set-token damocles --token-stdin   # paste the PAT on stdin (preferred)
hivectl github set-token damocles --token <pat>    # inline (visible in shell history)
```

- `set-token`: writes `<state>/github-token` (`0600`, agent-owned) via
  hive-priv — the same credential-injection path as forge/matrix tokens.
  The `gh` wrapper / git credential helper read it live, so a freshly-set
  or rotated PAT takes effect with no rebuild or restart. Refuses an empty
  token. See [github.md](../github.md) for the full flow + security notes.

## 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 list                # roster: every agent's status + technical state
hivectl agents list --json         # same data as raw JSON rows (for scripting)
hivectl agents restart iris        # stop + start the `iris` container (no rebuild)
hivectl agents restart-all         # stop + start every managed agent container in sequence
```

`list` prints a padded table with one row per managed agent —
`NAME  STATUS  REV  PARENT  REMIND`. STATUS collapses the health flags
(`running` / `stopped`, plus ` needs-login` / ` needs-update` when set);
REV is the first 12 chars of the agent's locked config sha; PARENT is its
place in the topology tree (`-` for a root agent); REMIND is the count of
pending reminders. It reuses the same per-agent aggregation the dashboard
renders, so the CLI roster and the web UI never drift. `--json` emits the
raw rows instead of the table.

`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 from the agent's state dir. Requires root (same as all
`machinectl shell` operations).

```bash
hivectl choom iris                          # fresh blank Claude session in iris's container
hivectl choom iris --resume <session-id>    # rejoin a prior session by id
```

Bare `choom` starts a fresh blank session. `--resume <value>` passes
through as `claude --resume <value>` to rejoin a prior session by its
session id — the flag name deliberately matches the claude flag it maps
to. (choom never uses claude's `--continue`: that's a bare flag that
takes no argument and resumes the cwd's *latest* session, i.e. the
harness's; a value after it would be consumed as the first prompt,
silently poking the live harness session.) A value is required when the
flag is given. Either way choom never collides with the harness's live
session in the same project dir: the harness pins its own id via
`--resume`, so a blank choom session is invisible to it. 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`**: the session and `CLAUDE.md` (the
  persona) resolve against the right project dir.
- **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, and the role prompt. Each flag is
  included only when its file exists.
- **without the onboarding walkthrough**: a boot-time oneshot
  (`hive-claude-onboarding`) seeds `hasCompletedOnboarding` and the
  project trust flags into `~/.claude.json` once before the harness
  starts, so the first interactive choom lands straight in a session
  instead of the onboarding/trust dialog the headless harness never
  completes. It's the single place hyperhive touches that file.

## Open

Print (and best-effort open in a browser) one of the hive's web surfaces.
Requires the `hive-c0re` daemon to be running.

```bash
hivectl open            # operator dashboard (same as `open home`)
hivectl open home       # operator dashboard (https://<domain>/)
hivectl open forge      # the forge (Forgejo) web UI
hivectl open matrix     # the matrix GUI (fluffychat)
```

The URL is resolved from the running daemon (`HostRequest::Urls`), which
reads the per-surface public URLs from c0re's service env — so custom
forge / matrix domains resolve correctly instead of assuming
`forge.<domain>`. The URL is **always printed** (the reliable core, since
the host is usually headless / driven over SSH), then `xdg-open` is tried
as a convenience — a missing or failing opener is reported as a note, not
an error.

A surface has no URL when it isn't browser-reachable: `home` needs
`services.hyperhive.domain`; `forge` needs
`services.hyperhive.forge.behindGateway = true`; `matrix` needs
`services.hyperhive.matrix.gui.enable = true`. In those cases the command
exits with a hint naming the option to set.