# Command-Line Help for `swarmctl` This document contains the help content for the `swarmctl` command-line program. **Command Overview:** * [`swarmctl`↴](#swarmctl) * [`swarmctl agent`↴](#swarmctl-agent) * [`swarmctl agent create`↴](#swarmctl-agent-create) * [`swarmctl agent mint-identity`↴](#swarmctl-agent-mint-identity) * [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token) * [`swarmctl agent inference`↴](#swarmctl-agent-inference) * [`swarmctl agent inference get`↴](#swarmctl-agent-inference-get) * [`swarmctl agent inference set`↴](#swarmctl-agent-inference-set) * [`swarmctl agent inference clear`↴](#swarmctl-agent-inference-clear) * [`swarmctl schedule`↴](#swarmctl-schedule) * [`swarmctl schedule add`↴](#swarmctl-schedule-add) * [`swarmctl schedule list`↴](#swarmctl-schedule-list) * [`swarmctl schedule edit`↴](#swarmctl-schedule-edit) * [`swarmctl schedule pause`↴](#swarmctl-schedule-pause) * [`swarmctl schedule resume`↴](#swarmctl-schedule-resume) * [`swarmctl schedule rm`↴](#swarmctl-schedule-rm) * [`swarmctl user`↴](#swarmctl-user) * [`swarmctl user add`↴](#swarmctl-user-add) * [`swarmctl user reset-password`↴](#swarmctl-user-reset-password) * [`swarmctl user update`↴](#swarmctl-user-update) * [`swarmctl user list`↴](#swarmctl-user-list) * [`swarmctl forge`↴](#swarmctl-forge) * [`swarmctl forge make-admin`↴](#swarmctl-forge-make-admin) * [`swarmctl completions`↴](#swarmctl-completions) ## `swarmctl` swarm-level operator CLI **Usage:** `swarmctl [OPTIONS] ` ###### **Subcommands:** * `agent` — Manage agents across the swarm * `schedule` — Manage scheduled prompts * `user` — Manage subjects in the swarm's SSO provider * `forge` — Manage human accounts on the swarm's forge * `completions` — Generate a shell completion script for `swarmctl` and print it to stdout ###### **Options:** * `--authelia-bin ` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH` * `--users-file ` — Host-side path of authelia's users database — that is, the path inside the container, prefixed with the container's root. This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file. ## `swarmctl agent` Manage agents across the swarm **Usage:** `swarmctl agent ` ###### **Subcommands:** * `create` — Queue creation of a new agent on a hive in this swarm * `mint-identity` — Queue a re-mint of an existing agent's identity at the swarm's secret store * `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale * `inference` — Show or change the model, effort and subagent models the swarm sets for an agent ## `swarmctl agent create` Queue creation of a new agent on a hive in this swarm. Asks the swarm-controller to insert its agent-creation job graph — SSO identity, forge user, config repo, and the deploy message that puts the agent on `--hive` — and prints the queued job's node id. **This returns as soon as it queues the work.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest. No approval gate guards this: running this binary already means being root on the controller's host. **Usage:** `swarmctl agent create [OPTIONS] --hive ` ###### **Arguments:** * `` — Name for the new agent: 1–63 characters of `[a-z0-9-]`. Becomes an SSO subject, a forge user and a repository name, so it's validated here before queuing. The controller refuses a name the swarm has already placed on a different hive; the same name on the same hive re-creates that agent. ###### **Options:** * `--hive ` — Hive in this swarm to deploy the agent to. Required, and deliberately not defaulted: it's an *address* — the hive that gets the deploy message — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses. * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl agent mint-identity` Queue a re-mint of an existing agent's identity at the swarm's secret store. **The backfill verb.** Agent creation is event-driven and nothing at swarm level sweeps for agents that are missing a credential, so an agent created before a credential joined the mint never receives one. This re-runs the mint for one agent that already exists. ⚠️ **It re-mints the agent's store certificate**, which that agent picks up the next time its container boots. It leaves an existing queue secret exactly as it stands, so running this against an already-migrated agent doesn't disturb its queue connection. Queues and returns, the same way `agent create` does — watch the swarm UI's job view for the outcome. **Usage:** `swarmctl agent mint-identity [OPTIONS] ` ###### **Arguments:** * `` — Name of an agent that already exists ###### **Options:** * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl agent mint-forge-token` Check one agent's forge token, and mint it if it's missing or stale. swarm-controller does this for every agent with a store identity at start and every five minutes; this is for when waiting isn't an option. It leaves a current token alone. Queues and returns, the same way `agent create` does — watch the swarm UI's job view for the outcome. **Usage:** `swarmctl agent mint-forge-token [OPTIONS] ` ###### **Arguments:** * `` — Name of an agent that already exists ###### **Options:** * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl agent inference` Show or change the model, effort and subagent models the swarm sets for an agent. A field the swarm sets wins over the agent's own value (its agent.nix, its `/effort` pick, or a `hyperhive-model` file) from its next turn on; the agent reads its settings every ten seconds. A field the swarm doesn't set, or clears, leaves the agent on its own value. **Usage:** `swarmctl agent inference ` ###### **Subcommands:** * `get` — Show what the swarm sets for an agent, naming the fields it doesn't set, and the model and effort the agent runs on, each with where it comes from * `set` — Set fields for an agent. Only the flags given change; the others keep what's stored * `clear` — Clear every field for an agent, so it goes back to its own values ## `swarmctl agent inference get` Show what the swarm sets for an agent, naming the fields it doesn't set, and the model and effort the agent runs on, each with where it comes from **Usage:** `swarmctl agent inference get [OPTIONS] ` ###### **Arguments:** * `` — Agent name ###### **Options:** * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl agent inference set` Set fields for an agent. Only the flags given change; the others keep what's stored **Usage:** `swarmctl agent inference set [OPTIONS] ` ###### **Arguments:** * `` — Agent name. A hive must declare it ###### **Options:** * `--model ` — The model its turns run on, as claude's `--model` takes it * `--effort ` — The reasoning effort its turns run at Possible values: `low`, `medium`, `high`, `xhigh`, `max` * `--subagent-models ` — The models it may start subagents on, comma-separated. Stored and shown; the agent doesn't apply it yet * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl agent inference clear` Clear every field for an agent, so it goes back to its own values **Usage:** `swarmctl agent inference clear [OPTIONS] ` ###### **Arguments:** * `` — Agent name ###### **Options:** * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. ## `swarmctl schedule` Manage scheduled prompts. The swarm keeps each prompt, and every agent it names fires it in its own container. Fire times are the schedule's start time plus whole intervals: changing the body never moves them, and an agent that was down fires the latest missed one once. **Usage:** `swarmctl schedule ` ###### **Subcommands:** * `add` — Add a scheduled prompt and print it with its new id * `list` — List scheduled prompts, one row each, with their agents and next fire time * `edit` — Change a scheduled prompt * `pause` — Stop a scheduled prompt firing. Times that pass while it's paused aren't fired when it resumes * `resume` — Let a paused scheduled prompt fire again, from its next time on * `rm` — Remove a scheduled prompt from every agent it names ## `swarmctl schedule add` Add a scheduled prompt and print it with its new id. Without `--every` it fires once. Without `--at` its first fire is now. **Usage:** `swarmctl schedule add [OPTIONS] --name --agent --body ` ###### **Options:** * `--name ` — The prompt's title * `--agent ` — Agent to fire it in. Repeatable; at least one * `--body ` — The prompt, delivered to each agent verbatim * `--at