vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
hyperhive/docs/tools/swarmctl-cli.md
atlas f0e3ed04d3 hive-forge, hivectl, swarmctl: fix clap help passive voice, regen docs 
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
2026-09-20 13:49:39 +02:00

5.4 KiB
Raw Blame History

Command-Line Help for swarmctl

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

Command Overview:

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