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

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

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

## 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 h-<name>` running
`claude --continue`. 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.