f0e3ed04d3
Rewrites every write-good.Passive hit in the hive-forge clap help text
into terse, imperative, active voice (meaning unchanged) and drops
clap-markdown's own fixed footer ('This document was generated
automatically by...') via MarkdownOptions::show_footer(false), since
that string isn't ours to reword and vale flagged it too.
docs/tools/{hivectl,swarmctl,forge}-cli.md are generated from each
crate's clap tree (see hive-forge/src/main.rs's MarkdownDocs verb) —
regenerated here from the fixed source, not hand-edited.
Refs #4549
159 lines
5.4 KiB
Markdown
159 lines
5.4 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 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] <COMMAND>`
|
||
|
||
###### **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 <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.
|
||
|
||
|
||
|
||
## `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
|
||
|
||
|
||
|
||
## `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 <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.
|
||
|
||
###### **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.
|
||
* `--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
|
||
* `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 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 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`
|
||
|
||
|
||
|
||
|