# 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 user`↴](#swarmctl-user) * [`swarmctl user add`↴](#swarmctl-user-add) * [`swarmctl user update`↴](#swarmctl-user-update) * [`swarmctl user list`↴](#swarmctl-user-list) * [`swarmctl completions`↴](#swarmctl-completions) ## `swarmctl` swarm-level operator CLI **Usage:** `swarmctl [OPTIONS] ` ###### **Subcommands:** * `agent` — Manage agents across the swarm * `user` — Manage subjects in the swarm's SSO provider * `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 ## `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 the work is queued.** 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 anything is queued. ###### **Options:** * `--hive ` — Hive in this swarm to deploy the agent to. Required, and deliberately not defaulted: it's an *address* — the hive a deploy message is sent to — 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 user` Manage subjects in the swarm's SSO provider **Usage:** `swarmctl user ` ###### **Subcommands:** * `add` — Add a user, generating a password for them * `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] ` ###### **Arguments:** * `` — Login name. Conservative ASCII only — it's a YAML map key and reaches access-control rules and logs ###### **Options:** * `--display-name ` — Name shown in the SSO UI. Defaults to the username * `--email
` * `--group ` — Repeatable ## `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] ` ###### **Arguments:** * `` — Login name of an existing user ###### **Options:** * `--display-name ` — Name shown in the SSO UI * `--email
` * `--add-group ` — Repeatable. Adding a group the user is already in isn't an error * `--remove-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 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 ` ###### **Arguments:** * `` — Shell to emit completions for Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`
This document was generated automatically by clap-markdown.