616 lines
22 KiB
Markdown
616 lines
22 KiB
Markdown
# 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-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 agent permissions`↴](#swarmctl-agent-permissions)
|
||
* [`swarmctl agent permissions get`↴](#swarmctl-agent-permissions-get)
|
||
* [`swarmctl agent permissions set`↴](#swarmctl-agent-permissions-set)
|
||
* [`swarmctl agent permissions clear`↴](#swarmctl-agent-permissions-clear)
|
||
* [`swarmctl agent agents-md`↴](#swarmctl-agent-agents-md)
|
||
* [`swarmctl agent agents-md get`↴](#swarmctl-agent-agents-md-get)
|
||
* [`swarmctl agent agents-md apply`↴](#swarmctl-agent-agents-md-apply)
|
||
* [`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 login`↴](#swarmctl-login)
|
||
* [`swarmctl completions`↴](#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`
|
||
|
||
|
||
|
||
|