Command-Line Help for swarmctl

This document contains the help content for the swarmctl command-line program.

Command Overview:

• swarmctl↴
• swarmctl agent↴
• swarmctl agent create↴
• swarmctl agent mint-forge-token↴
• swarmctl agent inference↴
• swarmctl agent inference get↴
• swarmctl agent inference set↴
• swarmctl agent inference clear↴
• swarmctl agent permissions↴
• swarmctl agent permissions get↴
• swarmctl agent permissions set↴
• swarmctl agent permissions clear↴
• swarmctl agent agents-md↴
• swarmctl agent agents-md get↴
• swarmctl agent agents-md apply↴
• swarmctl schedule↴
• swarmctl schedule add↴
• swarmctl schedule list↴
• swarmctl schedule edit↴
• swarmctl schedule pause↴
• swarmctl schedule resume↴
• swarmctl schedule rm↴
• swarmctl user↴
• swarmctl user add↴
• swarmctl user reset-password↴
• swarmctl user update↴
• swarmctl user list↴
• swarmctl forge↴
• swarmctl forge make-admin↴
• swarmctl login↴
• swarmctl completions↴

swarmctl

swarm-level operator CLI

Usage: swarmctl [OPTIONS] <COMMAND>

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
• login — Log in to the swarm named by --swarm as your own SSO account
• completions — Generate a shell completion script for swarmctl and print it to stdout

Options:

• --authelia-bin <PATH> — 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 <PATH> — 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.

• --swarm <URL> — The swarm's domain, as https://<domain> or the bare domain. Given, the agent, schedule and forge verbs go through its gateway as the account swarmctl login logged in, instead of over the controller's socket. Falls back to SWARMCTL_SWARM; login then falls back to SWARMCTL_LOGIN_DEFAULT_SWARM, which the swarm-controller nix module sets to its host's own swarm

• --ca-file <PATH> — A PEM CA certificate to trust beside the system roots, for a swarm whose gateway serves a certificate from the swarm's own CA. Falls back to SWARMCTL_CA_FILE

swarmctl agent

Manage agents across the swarm

Usage: swarmctl agent <COMMAND>

Subcommands:

• create — Queue creation of a new agent on a hive in this swarm
• mint-forge-token — Check one agent's forge token, and mint it if it's missing or stale
• inference — Show the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models
• permissions — Show or change the permissions the swarm grants an agent
• agents-md — Show an agent's AGENTS.md, or edit it with a diff

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: the caller is root on the controller's host, or logged in through the swarm domain's SSO gate.

Usage: swarmctl agent create [OPTIONS] --hive <HIVE> <NAME>

Arguments:

• <NAME> — 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> — 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.

• --agents-md <FILE> — A text file the agent's AGENTS.md starts with.

  The agent writes it on its first start, and only when it has no AGENTS.md yet: re-creating an agent never replaces an existing file. The controller refuses a file over 64 KiB.

• --controller-socket <PATH> — 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] <NAME>

Arguments:

• <NAME> — Name of an agent that already exists

Options:

• --controller-socket <PATH> — 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 the model, effort, subagent models and subagent cap the swarm sets for an agent, or change the model, effort and subagent models.

get prints the subagent cap (max_subagents); set has no flag for it and keeps a stored one. Only swarm-ui sets it.

A field the swarm sets wins over the agent's own value (its agent.nix or a hyperhive-model/hyperhive-effort 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 <COMMAND>

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] <AGENT>

Arguments:

• <AGENT> — Agent name

Options:

• --controller-socket <PATH> — 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] <AGENT>

Arguments:

• <AGENT> — Agent name. A hive must declare it

Options:

• --model <MODEL> — The model its turns run on, as claude's --model takes it

• --effort <LEVEL> — The reasoning effort its turns run at

  Possible values: low, medium, high, xhigh, max

• --subagent-models <MODELS> — The models it may start subagents on, comma-separated. Stored and shown; the agent doesn't apply it yet

• --controller-socket <PATH> — 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] <AGENT>

Arguments:

• <AGENT> — Agent name

Options:

• --controller-socket <PATH> — 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 permissions

Show or change the permissions the swarm grants an agent.

The agent applies its tool permissions at its next turn; the hive running it restarts it, after its current turn, when manage_root_agent changes. Unset leaves the agent on the default: messaging, meta, inbox, execution, whatever its name.

Usage: swarmctl agent permissions <COMMAND>

Subcommands:

• get — Show the permissions the swarm grants an agent, or that it sets none
• set — Replace the permissions the swarm grants an agent
• clear — Clear the agent's permissions, so the default applies again

swarmctl agent permissions get

Show the permissions the swarm grants an agent, or that it sets none

Usage: swarmctl agent permissions get [OPTIONS] <AGENT>

Arguments:

• <AGENT> — Agent name

Options:

• --controller-socket <PATH> — 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 permissions set

Replace the permissions the swarm grants an agent

Usage: swarmctl agent permissions set [OPTIONS] --permissions <PERMISSIONS> <AGENT>

Arguments:

• <AGENT> — Agent name. A hive must declare it

Options:

• --permissions <PERMISSIONS> — The permissions to grant, comma-separated: any of messaging, meta, inbox, execution, web_tools, manage_root_agent. --permissions '' grants none

• --controller-socket <PATH> — 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 permissions clear

Clear the agent's permissions, so the default applies again

Usage: swarmctl agent permissions clear [OPTIONS] <AGENT>

Arguments:

• <AGENT> — Agent name

Options:

• --controller-socket <PATH> — 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 agents-md

Show an agent's AGENTS.md, or edit it with a diff.

get shows the copy the agent last published, so it works while the agent isn't running. apply hands the diff to the agent, which applies it to the file with git apply; it needs the agent running.

Usage: swarmctl agent agents-md <COMMAND>

Subcommands:

• get — Print an agent's AGENTS.md on stdout, and its revision on stderr
• apply — Apply a unified diff to an agent's AGENTS.md

swarmctl agent agents-md get

Print an agent's AGENTS.md on stdout, and its revision on stderr

Usage: swarmctl agent agents-md get [OPTIONS] <AGENT>

Arguments:

• <AGENT> — Agent name

Options:

• --controller-socket <PATH> — 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 agents-md apply

Apply a unified diff to an agent's AGENTS.md.

The diff names a/AGENTS.md and b/AGENTS.md, as diff -u a/AGENTS.md b/AGENTS.md writes it. The agent refuses it when the file is no longer at --base, or when it doesn't apply, and leaves the file as it was.

Usage: swarmctl agent agents-md apply [OPTIONS] --base <REVISION> <AGENT> <DIFF_FILE>

Arguments:

• <AGENT> — Agent name
• <DIFF_FILE> — The file holding the diff

Options:

• --base <REVISION> — The revision you made the diff against, as get printed it. It's the git blob id of that text, so git hash-object of the unedited file prints it too

• --controller-socket <PATH> — 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 <COMMAND>

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 <TEXT> --agent <AGENT> --body <TEXT>

Options:

• --name <TEXT> — The prompt's title

• --agent <AGENT> — Agent to fire it in. Repeatable; at least one

• --body <TEXT> — The prompt, delivered to each agent verbatim

• --at <TIME> — First fire time: an RFC 3339 time with its offset, such as 2026-10-05T09:00:00+02:00, or unix seconds. Defaults to now

• --every <DURATION> — Time between fires: a count with a unit of s, m, h or d, such as 1h or 7d. Leave out for a one-shot

• --paused — Add it paused

• --controller-socket <PATH> — 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 list

List scheduled prompts, one row each, with their agents and next fire time

Usage: swarmctl schedule list [OPTIONS]

Options:

• --agent <AGENT> — Show only the prompts that fire in this agent

• --controller-socket <PATH> — 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 edit

Change a scheduled prompt.

Only the flags given change, and the id stays. --at and --every move the fire times; --name, --body and the agent flags don't.

Usage: swarmctl schedule edit [OPTIONS] <ID>

Arguments:

• <ID> — The prompt's id, as schedule list shows it

Options:

• --name <TEXT> — New title

• --body <TEXT> — New prompt text

• --at <TIME> — New first fire time, in the form schedule add --at takes

• --every <DURATION> — New time between fires, in the form schedule add --every takes

• --once — Make it a one-shot

• --add-agent <AGENT> — Agent to start firing it in. Repeatable

• --remove-agent <AGENT> — Agent to stop firing it in. Repeatable. Fails if the agent isn't a target, or if no agent would remain

• --controller-socket <PATH> — 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 pause

Stop a scheduled prompt firing. Times that pass while it's paused aren't fired when it resumes

Usage: swarmctl schedule pause [OPTIONS] <ID>

Arguments:

• <ID> — The prompt's id, as schedule list shows it

Options:

• --controller-socket <PATH> — 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 resume

Let a paused scheduled prompt fire again, from its next time on

Usage: swarmctl schedule resume [OPTIONS] <ID>

Arguments:

• <ID> — The prompt's id, as schedule list shows it

Options:

• --controller-socket <PATH> — 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 rm

Remove a scheduled prompt from every agent it names

Usage: swarmctl schedule rm [OPTIONS] <ID>

Arguments:

• <ID> — The prompt's id, as schedule list shows it

Options:

• --controller-socket <PATH> — 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 user

Manage subjects in the swarm's SSO provider

Usage: swarmctl user <COMMAND>

Subcommands:

• add — Add a user, generating a password for them
• reset-password — Set a new password for an existing user, generating it the same way user add does
• update — Change an existing user's attributes
• list — List every user in authelia's users database

swarmctl user add

Add a user, generating a password for them

Usage: swarmctl user add [OPTIONS] <USERNAME>

Arguments:

• <USERNAME> — Login name. Conservative ASCII only — it's a YAML map key and reaches access-control rules and logs

Options:

• --display-name <TEXT> — Name shown in the SSO UI. Defaults to the username
• --email <ADDRESS>
• --group <GROUP> — Repeatable

swarmctl user reset-password

Set a new password for an existing user, generating it the same way user add does.

authelia's file store has no self-service reset (no SMTP notifier), so this is the only way a human account gets a new password once an operator forgets the old one. Refuses if the user doesn't exist — there's no separate "create" path here.

Usage: swarmctl user reset-password <USERNAME>

Arguments:

• <USERNAME> — Login name of an existing user

swarmctl user update

Change an existing user's attributes.

Every flag is optional and they compose, so one call can set multiple things at once. Deliberately doesn't touch the password: regenerating a credential is a different intent from editing an attribute, and folded together an attribute edit can invalidate a login by accident.

Usage: swarmctl user update [OPTIONS] <USERNAME>

Arguments:

• <USERNAME> — Login name of an existing user

Options:

• --display-name <TEXT> — Name shown in the SSO UI
• --email <ADDRESS>
• --add-group <GROUP> — Repeatable. Adding a group the user is already in isn't an error
• --remove-group <GROUP> — Repeatable. Fails if the user isn't in the group — a revocation that reports success without revoking is the failure nobody re-checks

swarmctl user list

List every user in authelia's users database.

Read-only: it never writes the file. Shows every subject in it, including agent identities swarm-authelia-bridge created — one line per user: username, display name, email (if set), groups (if any).

Usage: swarmctl user list

swarmctl forge

Manage human accounts on the swarm's forge

Usage: swarmctl forge <COMMAND>

Subcommands:

• make-admin — Make an existing forge user a site admin

swarmctl forge make-admin

Make an existing forge user a site admin.

The forge creates a human's account on their first SSO login, and this fails until that login has happened. Running it on a site admin changes nothing. Refused for an agent.

Usage: swarmctl forge make-admin [OPTIONS] <NAME>

Arguments:

• <NAME> — Forge username, the same as the user's SSO username

Options:

• --controller-socket <PATH> — 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 login

Log in to the swarm named by --swarm as your own SSO account.

With no --swarm or SWARMCTL_SWARM, logs in to SWARMCTL_LOGIN_DEFAULT_SWARM: on a swarm-controller host, the swarm that host belongs to.

Opens the swarm's SSO login in your browser (and prints the URL) and receives the answer on a loopback port, so run it where that browser runs. swarmctl keeps the login, mode 0600, under $XDG_STATE_HOME/swarmctl/ and refreshes it as it's used. To log out, delete that file.

Usage: swarmctl login

swarmctl completions

Generate a shell completion script for swarmctl and print it to stdout.

Supports bash, zsh, fish, elvish and powershell. The nix package already installs bash/zsh/fish system-wide; this is for ad-hoc or other-shell use.

Dispatched before PathArgs::resolve() for the same reason as markdown-docs: emitting a completion script needs none of the SWARMCTL_AUTHELIA_* deployment env vars, and requiring them would make the package's own build-time invocation fail.

Usage: swarmctl completions <SHELL>

Arguments:

• <SHELL> — Shell to emit completions for

  Possible values: bash, elvish, fish, powershell, zsh