30fa54cbc6
`swarmctl agent create <name> --hive <hive>` POSTs `/api/agents` to swarm-controller over the daemon's unix socket and prints the queued job's node id. It deliberately does not wait. The endpoint queues a DAG whose last node *publishes* a deploy message; the hive's `hive-c0re` then converges on its own clock, out of the controller's sight. So even a fully settled graph would not mean the agent is up, and there is nothing this CLI could wait for that would let it claim otherwise. Printing the id is exactly what the response says and all of what it says. Transport is a bare hyper HTTP/1.1 client handshaked onto a tokio `UnixStream` via `hyper_util::rt::TokioIo` — the same crate family `hivectl/src/watch.rs` and `hive-agent/src/web_ui/proxy.rs` already use, all of it already workspace-pinned. The request/response shapes are a local mirror rather than a shared crate: the controller's own types are private to its binary and this crate does not link it, the same separation `hivectl` keeps from `hive-c0re`. Errors are reduced to one actionable line — the controller answers RFC 9457 problem+json, so an unknown `--hive` reaches the operator as the roster of hives that would have worked rather than a body dump. Response `warnings` are printed when non-empty. The nix module wraps the binary with `SWARM_CONTROLLER_SOCKET`, read from the same `socketPath` the daemon binds. Refs #4399
165 lines
5.6 KiB
Markdown
165 lines
5.6 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 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 <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 anything is queued.
|
||
|
||
###### **Options:**
|
||
|
||
* `--hive <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 <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`
|
||
|
||
|
||
|
||
|
||
<hr/>
|
||
|
||
<small><i>
|
||
This document was generated automatically by
|
||
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
|
||
</i></small>
|