swarmexec › Docs › CLI reference
CLI reference_
Every command and flag, from the binary's own help.
This page is generated from the command tree of the swarmexec
client, so it says what swarmexec <command> --help says.
The topic pages explain the commands with context and examples; the
parity matrix shows which of them the TUI and the
MCP server offer too.
Commands
- swarmexec
- swarmexec completion
- swarmexec completion bash
- swarmexec completion fish
- swarmexec completion powershell
- swarmexec completion zsh
- swarmexec config
- swarmexec config show
- swarmexec help connection
- swarmexec context
- swarmexec context create
- swarmexec context ls
- swarmexec context rm
- swarmexec context use
- swarmexec cp
- swarmexec doctor
- swarmexec down
- swarmexec exec
- swarmexec init
- swarmexec logs
- swarmexec mcp
- swarmexec node
- swarmexec node ls
- swarmexec node prune
- swarmexec node prune-schedule
- swarmexec node prune-schedule set
- swarmexec node prune-schedule show
- swarmexec node update
- swarmexec port-forward
- swarmexec ps
- swarmexec secret
- swarmexec secret rotate
- swarmexec security
- swarmexec security check
- swarmexec security report
- swarmexec stack
- swarmexec stack check
- swarmexec stack deploy
- swarmexec stack diff
- swarmexec stack export
- swarmexec stack ls
- swarmexec stack rm
- swarmexec stats
- swarmexec status
- swarmexec ui
- swarmexec volume
- swarmexec volume ls
- swarmexec volume rm
- swarmexec wait
- Global flags
- Connection flags
- Renamed names
swarmexec
exec, logs, port-forward and a terminal UI for Docker Swarm — without SSH to the nodes
| Flag | Default | Description |
|---|---|---|
--info | false | show version, license, and contact info |
-v, --version | false | version for swarmexec |
swarmexec completion— Generate the autocompletion script for the specified shellswarmexec config— Inspect the resolved client configurationswarmexec help connection— Flags for reaching the agents: TLS, the agent secret, node addressingswarmexec context— Manage Docker contexts used for the manager APIswarmexec cp— Copy files and directories to, from and between containers in the swarmswarmexec doctor— Diagnose the swarm: manager, agent deployment, and per-node agent healthswarmexec down— Remove the agent service (and secret) provisioned by `init`swarmexec exec— Exec into a container running anywhere in the swarmswarmexec init— Provision the agent on every node of the swarm (self-signed + shared secret)swarmexec logs— Stream logs of one or more containers, services or a stack from anywhere in the swarmswarmexec mcp— Serve the swarm to an AI assistant over MCP (stdio)swarmexec node— List the swarm's nodes, prune them, set availability and labels, schedule prunesswarmexec port-forward— Forward a local port to a port inside a container in the swarmswarmexec ps— List candidate tasks/containers and the node each runs onswarmexec secret— Work with swarm secretsswarmexec security— Security report of the cluster, and checks of stack files before deployingswarmexec stack— Work with deployed stacksswarmexec stats— Show live CPU and memory of each container, measured by the node agentsswarmexec status— Show the cluster at a glance: nodes, services, replicas and healthswarmexec ui— Terminal UI: stacks/services, volumes, forwards, networks, secrets, nodes, configs — several clusters in one sessionswarmexec volume— List and remove volumes across the swarmswarmexec wait— Wait until services have converged — for CI after a deploy
swarmexec completion
Generate the autocompletion script for the specified shell
Generate the autocompletion script for swarmexec for the specified shell. See each sub-command's help for details on how to use the generated script.
swarmexec completion bash— Generate the autocompletion script for bashswarmexec completion fish— Generate the autocompletion script for fishswarmexec completion powershell— Generate the autocompletion script for powershellswarmexec completion zsh— Generate the autocompletion script for zsh
swarmexec completion bash
Generate the autocompletion script for bash
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(swarmexec completion bash)
To load completions for every new session, execute once:
swarmexec completion bash > /etc/bash_completion.d/swarmexec
swarmexec completion bash > $(brew --prefix)/etc/bash_completion.d/swarmexec
You will need to start a new shell for this setup to take effect.
| Flag | Default | Description |
|---|---|---|
--no-descriptions | false | disable completion descriptions |
swarmexec completion fish
Generate the autocompletion script for fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
swarmexec completion fish | source
To load completions for every new session, execute once:
swarmexec completion fish > ~/.config/fish/completions/swarmexec.fish
You will need to start a new shell for this setup to take effect.
| Flag | Default | Description |
|---|---|---|
--no-descriptions | false | disable completion descriptions |
swarmexec completion powershell
Generate the autocompletion script for powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
swarmexec completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command to your powershell profile.
| Flag | Default | Description |
|---|---|---|
--no-descriptions | false | disable completion descriptions |
swarmexec completion zsh
Generate the autocompletion script for zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc
To load completions in your current shell session:
source <(swarmexec completion zsh)
To load completions for every new session, execute once:
swarmexec completion zsh > "${fpath[1]}/_swarmexec"
swarmexec completion zsh > $(brew --prefix)/share/zsh/site-functions/_swarmexec
You will need to start a new shell for this setup to take effect.
| Flag | Default | Description |
|---|---|---|
--no-descriptions | false | disable completion descriptions |
swarmexec config
Inspect the resolved client configuration
swarmexec config show— Print the effective client configuration (secret masked)
swarmexec config show
Print the effective client configuration (secret masked)
| Flag | Default | Description |
|---|---|---|
--json | false | output JSON instead of a table |
swarmexec help connection help topic
Flags for reaching the agents: TLS, the agent secret, node addressing
Connection flags reach the swarmexec agents on the nodes. Every command takes them; they override the matching config file keys and SWARMEXEC_* variables (see "swarmexec config show"). Most setups set them once in the config file and never on the command line.
Connection Flags:
--addr-mode string node dial address: hostname|ip (default hostname) --agent-secret string shared secret for a self-signed agent (Portainer-style auth) --agent-secret-file string file to read the shared secret from --ca string CA certificate to verify the agent (mTLS) --cert string client certificate (mTLS; CN is the operator identity) --insecure skip agent server-certificate verification (self-signed agents) --key string client private key (mTLS) --operator string operator identity reported for audit (default: OS username) --port int agent port (default 9443) --server-name string override TLS server name for agent verification
swarmexec context
Manage Docker contexts used for the manager API
swarmexec context create— Create a Docker context pointing at a manager hostswarmexec context ls— List Docker contextsswarmexec context rm— Remove one or more Docker contextsswarmexec context use— Set the current Docker context
swarmexec context create
Create a Docker context pointing at a manager host
Create a Docker context in docker's own store, so `swarmexec --context <name>` (and the docker CLI) can use it. The host is a docker daemon endpoint — typically an ssh:// bastion to a Swarm manager, or tcp:// / unix://.
| Flag | Default | Description |
|---|---|---|
--description string | — | optional description |
--docker-host string | — | docker daemon endpoint (ssh:// | tcp:// | unix:// | npipe://) |
--ssh-jump string | — | ssh jump host(s) for an ssh:// context, comma-separated (ProxyJump / -J) |
--use | false | also make it the current context |
swarmexec context ls
List Docker contexts
| Flag | Default | Description |
|---|---|---|
--json | false | output JSON instead of a table |
swarmexec context rm
Remove one or more Docker contexts
| Flag | Default | Description |
|---|---|---|
-f, --force | false | remove even if it is the current context (resets selection to default) |
swarmexec context use
Set the current Docker context
swarmexec cp
Copy files and directories to, from and between containers in the swarm
Move files in or out of a container on whatever node of the swarm it runs — and between two containers, which may sit on different nodes.
Either side is a local path or <target>:<path>, where the target is what exec takes: a service, a service.slot, a task id or a container id. One side must name a container; two local paths are a job for cp(1).
Nothing has to exist inside the container — not even tar. The copy goes through the Engine's own archive endpoint on the node, so it works with distroless and scratch images, which is where it is needed most.
The destination rules are docker cp's: a path that is an existing directory receives the source under its own name, any other path IS the name. A copy between two containers never touches this machine's disk, but every byte does travel through it: there is no node-to-node path, by design.
| Flag | Default | Description |
|---|---|---|
-a, --archive | false | keep the owner and group recorded in the archive |
--connect-timeout duration | 10s | timeout for connecting to the agent |
-L, --follow-link | false | copy what a symlinked source points at, not the link |
--max-size string | 1G | refuse a copy larger than this (K/M/G, binary units) |
--node string | — | node hint/override for container-id targets |
-q, --quiet | false | no progress output |
swarmexec doctor
Diagnose the swarm: manager, agent deployment, and per-node agent health
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout |
--json | false | output JSON instead of a table |
swarmexec down
Remove the agent service (and secret) provisioned by `init`
down is the inverse of init: it removes the global agent service and, by default, the shared-secret Docker secret. It does not touch the client config.
| Flag | Default | Description |
|---|---|---|
--keep-secret | false | do not remove the shared-secret Docker secret |
--service-name string | swarmexec_agent | name of the agent service to remove |
-y, --yes | false | do not prompt for confirmation |
swarmexec exec
Exec into a container running anywhere in the swarm
Open a shell, or run a command, in a container on whatever node of the swarm it runs — the docker exec experience, without ssh to that node.
The target is one of:
service the service's running task, e.g. web
service.slot one replica, e.g. web.2
task-id a Swarm task ID
container-id a container ID prefix (--node names its node, or the running
tasks are scanned for it)
A service with several running replicas is ambiguous: on a terminal you are asked to pick one from a numbered list; without one the candidates are printed and nothing runs. Name a slot to skip the question.
With no command it opens /bin/sh, with a TTY when stdin is a terminal. The remote command's exit code is passed through.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | timeout for connecting to the agent |
-e, --env stringArray | — | set environment variables (KEY=VALUE, repeatable) |
--node string | — | node hint/override for container-id targets |
-i, --stdin | true | keep stdin open |
-t, --tty | false | allocate a TTY (default: auto — true iff stdin is a terminal and no command) |
-u, --user string | — | username or UID (e.g. 1000:1000) |
-w, --workdir string | — | working directory inside the container |
swarmexec init
Provision the agent on every node of the swarm (self-signed + shared secret)
init deploys the swarmexec agent as a global Swarm service via the manager API: it creates a shared-secret Docker secret, runs the agent in self-signed mode on every node (host port 9443), and writes the matching client config so exec/logs/volume work immediately.
| Flag | Default | Description |
|---|---|---|
--allow-legacy-secret | true | accept the raw shared secret from clients predating connection-bound auth; pass=false once all clients are upgraded |
--force | false | update the service if it already exists |
--image string | docker.io/logleio/swarmexec-agent:latest | agent image to deploy |
--metrics-port int | 0 | publish the agent's Prometheus metrics on this host port (0 = off); plain HTTP, counts only |
--policy-file string | — | authorization rule file for the agents (YAML, checked before deploying); without it every authenticated request is allowed |
--port int | 9443 | host port the agent publishes |
--registry-auth | true | pass local registry credentials so nodes can pull a private image |
--rollout-timeout duration | 1m30s | how long to wait for agents to start |
--save-config | true | write the client config (~/.config/swarmexec/config.yaml) |
--secret string | — | shared secret to use (default: generate a random one) |
--service-name string | swarmexec_agent | name for the agent service |
--wait | true | wait for the agents to come up and report progress |
swarmexec logs
Stream logs of one or more containers, services or a stack from anywhere in the swarm
Stream logs from anywhere in the swarm.
One target that is one container streams exactly as before. Several targets, a service with several replicas, or --stack follow every source at once: each line is prefixed with where it came from (svc.slot, svc@node for a global service), each source reconnects across its own container replacements, and each has its own format detection.
A service (or service.slot) with no running container — crash-looping, failing its health check — shows the newest exited container of each slot instead, so the logs that say why it fails are one command away.
--min-level filters the log output shown here; swarmexec's own logging is the global --client-log-level.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | timeout for connecting to the agent |
-f, --follow | false | keep streaming new log lines |
--grep string | — | only show lines whose message matches this regexp |
--log-format string | — | parse lines as: auto | classic | json | logfmt | gelf | raw (auto detects it from the lines themselves; default from config, else classic) |
--min-level string | — | only show this level and above: trace|debug|info|warn|error|fatal |
--node string | — | node hint/override for container-id targets |
--since duration | 0s | only logs newer than this (e.g. 10m, 1h; 0 = no limit) |
--stack string | — | follow every service of this stack (in addition to any targets) |
--tail uint32 | 0 | number of lines from the end to start with (0 = all) |
-t, --timestamps | false | prefix each line with a timestamp |
swarmexec mcp
Serve the swarm to an AI assistant over MCP (stdio)
Run a Model Context Protocol server on stdin/stdout, so an AI assistant can inspect the swarm: services, tasks, logs, stats, stack diffs. Register it with
claude mcp add swarmexec -- swarmexec mcp
A service is visible only with the service label swarmexec.mcp.enable=true (compose: deploy.labels). swarmexec.mcp.logs=true allows its logs, swarmexec.mcp.exec=true a non-interactive command in its containers. An explicit "false" always wins. --default list makes unlabelled services visible (listed, inspected, their stats read), never their logs or exec.
The labels themselves are never shown to the assistant, and no tool changes a service, stack or label; the one tool that is not read-only is exec_run, which runs a command in a service that has swarmexec.mcp.exec=true. A service that mounts the Docker socket is never exec'd into, whatever its labels say.
ssh cannot prompt here: stdin and stdout are the protocol. Load the key for an ssh:// context into ssh-agent first. Logging goes to the log file.
Only the docker context the server starts with (--context, $DOCKER_CONTEXT, $DOCKER_HOST or docker's current one) is reachable, plus those named with --contexts. Every other context does not exist as far as the assistant can tell: it is not listed, and asking for it is "unknown docker context".
Masking secrets in env and inspect output is cosmetic once exec is granted: a command run in the container can print its environment.
| Flag | Default | Description |
|---|---|---|
--allow strings | — | enable optional tools: report (security_report) |
--connect-timeout duration | 10s | timeout for connecting to an agent |
--contexts strings | — | further docker contexts the assistant may use, besides the one the server starts with (comma list or repeated) |
--default string | none | access for services without swarmexec.mcp.enable: none | list ("read" is accepted for list) |
swarmexec node
List the swarm's nodes, prune them, set availability and labels, schedule prunes
swarmexec node ls— List the nodes: role, availability, state, engine, running tasks, volumes, labelsswarmexec node prune— Free disk on one node: stopped containers, untagged images, build cache, unused networks (images and volumes only when named)swarmexec node prune-schedule— Show or set the cluster-wide prune schedule the agents runswarmexec node update— Set a node's availability (active, pause, drain) or its labels
swarmexec node ls
List the nodes: role, availability, state, engine, running tasks, volumes, labels
The Nodes tab as a table. TASKS counts the running tasks the manager placed on the node; VOLS is the node's volume count, asked of its agent ("-" when the agent did not answer, or with --skip-agents); LABELS is the number of node labels (--json lists them).
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout |
--json | false | output JSON instead of a table |
--skip-agents | false | do not ask the agents for volume counts (faster) |
swarmexec node prune
Free disk on one node: stopped containers, untagged images, build cache, unused networks (images and volumes only when named)
Prune one node through its agent, the TUI's node prune. Without --categories it sweeps the safe ones: stopped containers, untagged images, build cache and unused local networks. "images" (every unused image, including those of services scaled to zero) and "volumes" (DATA, named volumes included) are only ever pruned when named.
Before pruning it shows what each category would free, as the agent last measured it, and asks; --yes answers in advance. Without a terminal and without --yes nothing is pruned.
| Flag | Default | Description |
|---|---|---|
--categories string | — | comma-separated: containers, images, dangling-images, buildcache, networks, volumes (default containers,dangling-images,buildcache,networks) |
--connect-timeout duration | 10s | per-node connect timeout |
--containers-until string | — | keep stopped containers this long after they stop (default 24h; 0 keeps none) |
-y, --yes | false | do not prompt for confirmation |
swarmexec node prune-schedule
Show or set the cluster-wide prune schedule the agents run
The agents can prune their node on a schedule: stopped containers, unused images, build cache and unused local networks by default; volumes only when added explicitly. The schedule is stored as container labels on the agent service (swarmexec.prune.*), so setting it restarts the agents one by one.
swarmexec node prune-schedule set— Set (and enable) the schedule; flags not given keep their current valueswarmexec node prune-schedule show— Show the schedule as the agent service carries it
swarmexec node prune-schedule set
Set (and enable) the schedule; flags not given keep their current value
| Flag | Default | Description |
|---|---|---|
--categories string | — | comma-separated: containers, images, dangling-images, buildcache, networks, volumes |
--containers-until string | — | keep stopped containers this long after they stop (default 24h; 0 keeps none) |
--days string | — | days to run: mon,tue,… or ranges like mon-fri (default every day) |
--disable | false | turn the schedule off (keeps the other settings) |
--label-filter string | — | only prune objects with these labels (key or key=value, comma-separated); "-" clears |
--start string | — | first run of the day, HH:MM (default 00:00) |
--times int | 0 | runs per day, the day split evenly from --start (1-24) |
--tz string | — | IANA time zone for --days and --start (default UTC) |
-y, --yes | false | do not prompt before restarting the agents |
swarmexec node prune-schedule show
Show the schedule as the agent service carries it
swarmexec node update
Set a node's availability (active, pause, drain) or its labels
Change a node the way the TUI's Nodes tab does. Applies at once: a node has no rolling update. Draining moves every task off the node, so it asks first (--yes answers in advance); active and pause apply directly — pause only stops new placements.
| Flag | Default | Description |
|---|---|---|
--availability string | — | active | pause | drain |
--label-add stringArray | — | add or change a node label, key=value (repeatable) |
--label-rm stringArray | — | remove a node label by key (repeatable) |
-y, --yes | false | do not prompt before draining |
swarmexec port-forward
Forward a local port to a port inside a container in the swarm
Forward a local TCP port to a port inside a container anywhere in the swarm, without publishing that port on the cluster.
The local port defaults to the remote one, so `port-forward api 8080` listens on 127.0.0.1:8080 and forwards to port 8080 in the container.
Targeting a service forwards to exactly ONE of its tasks (the one the target resolves to), not across all replicas — a forward that silently load-balanced would make debugging misleading.
| Flag | Default | Description |
|---|---|---|
--address string | 127.0.0.1 | local address to bind; loopback by default so the forwarded port is not exposed to your network |
--connect-timeout duration | 10s | timeout for connecting to the agent |
--node string | — | node hint/override for container-id targets |
swarmexec ps
List candidate tasks/containers and the node each runs on
| Flag | Default | Description |
|---|---|---|
--json | false | output JSON instead of a table |
swarmexec secret
Work with swarm secrets
swarmexec secret rotate— Replace a secret's content, keeping its name
swarmexec secret rotate
Replace a secret's content, keeping its name
Give a secret new content without renaming it, so stack files that name it stay valid. Swarm secrets are immutable and cannot be removed while in use, so every service using it is parked on a temporary secret meanwhile:
1 create <name>_rotating with the new content (same labels + a marker) 2 switch every service to <name>_rotating (rolling update) 3 remove the old <name> 4 create <name> again: new content, original labels 5 switch every service back to <name> (rolling update) 6 remove <name>_rotating
Only the secret behind each mount changes: target path, uid, gid and mode stay. Every service using the secret restarts twice. There is no rollback to the old content — the old secret object is deleted.
The value is sent byte for byte (nothing trimmed or added), must not be empty and is limited to 500 KB. It is never printed.
If a run stops half-way, the services keep running on <name>_rotating, which holds the new content. Run the same command again to finish: it reads where the last run stopped and continues there.
If the secret came from a stack file with `file:`, put the new content in that file too, or the next `docker stack deploy` fails on the changed data.
Without --yes, the services that will restart are listed and a y/N answer is read from the terminal; without a terminal, --yes is required.
Exit code 0 means rotated, 1 a failure (the message names the step and, when there is something to resume, how), 2 a usage error, 125 an unreachable manager.
| Flag | Default | Description |
|---|---|---|
--from-file string | — | read the new value from this file |
--from-stdin | false | read the new value from stdin |
--timeout duration | 5m0s | how long to wait for each service's rolling update |
-y, --yes | false | do not ask for confirmation |
swarmexec security
Security report of the cluster, and checks of stack files before deploying
swarmexec security check— Check a stack file for security antipatterns without deploying itswarmexec security report— Write a Markdown security report for the whole cluster
swarmexec security check
Check a stack file for security antipatterns without deploying it
Load a stack file, run the security checks `stack deploy` runs over what it would actually deploy, and print the findings. Never deploys. The stack name defaults to the file's base name.
Exit code 0 means nothing above informational, 1 a finding a deploy would stop at — so it can gate a pipeline. Same as `stack deploy --check`, and the MCP tool stack_check.
swarmexec security report
Write a Markdown security report for the whole cluster
Scan every service, network, secret, config and node in the cluster and write the findings as Markdown. Writes to stdout unless -o is given, so it can be piped as well as saved.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout when checking agents |
-o, --output string | — | write to this file instead of stdout |
--skip-agents | false | do not contact the node agents (faster; agent version skew is then reported as not covered) |
swarmexec stack
Work with deployed stacks
swarmexec stack check— Check a stack file for security antipatterns without deploying itswarmexec stack deploy— Deploy a stack file, after checking it for security antipatternsswarmexec stack diff— Compare a stack file against the deployed stackswarmexec stack export— Write a deployed stack out as a compose fileswarmexec stack ls— List the stacks deployed on the clusterswarmexec stack rm— Remove a stack: its services, secrets, configs and networks
swarmexec stack check
Check a stack file for security antipatterns without deploying it
Load a stack file, run the security checks `stack deploy` runs over what it would actually deploy, and print the findings. Never deploys. The stack name defaults to the file's base name.
Exit code 0 means nothing above informational, 1 a finding a deploy would stop at — so it can gate a pipeline. Same as `stack deploy --check`, and the MCP tool stack_check.
swarmexec stack deploy
Deploy a stack file, after checking it for security antipatterns
Load a stack file, run the security checks over what it would actually deploy, and apply it. The stack name defaults to the file's base name.
If anything above informational is found the deploy STOPS and asks. Use --yes to answer in advance (for CI), or --check to look without deploying. --despite-findings deploys anyway without asking — say it deliberately.
| Flag | Default | Description |
|---|---|---|
--check | false | only run the checks, never deploy |
--despite-findings | false | deploy even though the check found something, without asking |
--prune | false | remove services of the stack the file no longer declares |
--with-registry-auth | false | send local registry credentials to the swarm, so nodes can pull private images |
-y, --yes | false | do not ask; deploy if the check found nothing actionable |
swarmexec stack diff
Compare a stack file against the deployed stack
Show what deploying <file> would change. The stack name defaults to the file's base name, the same default `docker stack deploy` does not have — give it explicitly when the file is not named after the stack.
A "+" line is something deploying the file would add, a "-" is something it would remove. Both sides are normalised the same way, so an unchanged stack produces an empty diff rather than pages of daemon defaults.
Exit code 0 means no difference, 1 a difference, 2 a usage error and 125 an unreachable manager — so it can gate a pipeline. --ignore leaves a field out of both sides ("services.*.deploy.replicas" for an autoscaled count) and is reported under "Not compared"; --json is the machine form.
| Flag | Default | Description |
|---|---|---|
--ignore strings | — | leave this field path out of both sides, e.g. services.*.deploy.replicas (repeatable) |
--json | false | output JSON instead of text |
--stack string | — | stack name to compare against (default: the file's base name) |
swarmexec stack export
Write a deployed stack out as a compose file
Read a deployed stack back from the cluster and write it as compose-shaped YAML. Writes to stdout unless -o is given.
This is a description of the stack, not a backup of it: a secret's value is write-only in the engine API and a volume's contents live on the nodes, so both are declared external. The file says so in its own header.
| Flag | Default | Description |
|---|---|---|
-o, --output string | — | write to this file instead of stdout |
swarmexec stack ls
List the stacks deployed on the cluster
swarmexec stack rm
Remove a stack: its services, secrets, configs and networks
Remove everything `docker stack rm` would: the services, secrets, configs and networks labelled com.docker.stack.namespace=<stack>. It lists them and asks first; --yes answers in advance, and without a terminal and without --yes nothing is removed.
Unlike docker it waits a few seconds for a network whose endpoints are still draining, and when something will not go it removes the rest and names exactly what is left behind (exit 125).
| Flag | Default | Description |
|---|---|---|
-y, --yes | false | do not prompt for confirmation |
swarmexec stats
Show live CPU and memory of each container, measured by the node agents
One reading of every running container of the named services (all services when none is named): CPU, memory against its limit, and health. The agents measure on the nodes; the manager API only knows what was reserved.
An agent samples only while someone asks, so a first reading can take a few seconds — stats waits up to --wait for CPU (a delta of two samples) and then prints what it has: "warming up" for a container still without a reading, "unavailable" where the node's agent did not answer. Same data as the MCP tool stats. When no agent answered at all, stats exits 125 and prints no table: an empty reading is not a measurement.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout |
--json | false | output JSON instead of a table |
--wait duration | 12s | how long to wait for agents still warming up (0: ask once) |
swarmexec status
Show the cluster at a glance: nodes, services, replicas and health
One screen of the whole cluster: every node with its role, state and availability, every service with its replicas and the health of its containers, and a summary line counting the degraded ones (running short, or with an unhealthy container). Health comes from the node agents and is best effort: without them the services are listed without it, and a note says so. Same data as the MCP tool cluster_overview.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout |
--json | false | output JSON instead of tables |
swarmexec ui
Terminal UI: stacks/services, volumes, forwards, networks, secrets, nodes, configs — several clusters in one session
A terminal UI over the swarm: stacks, services and their containers, volumes, port-forwards, networks, secrets, nodes and configs, one tab each, with exec, logs and port-forwarding built in. The docker contexts are a sidebar (c), and switching between them keeps your place in each cluster. Needs an interactive terminal; ? inside lists every key.
With a service argument the UI opens with the Stacks/Services tree already filtered to it, as if you had typed it into the / search.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | timeout for connecting to an agent |
swarmexec volume
List and remove volumes across the swarm
swarmexec volume ls— List volumes across all nodes and which nodes hold eachswarmexec volume rm— Remove a volume on all nodes (--all) or specific nodes (--node)
swarmexec volume ls
List volumes across all nodes and which nodes hold each
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | per-node connect timeout |
--json | false | output JSON instead of a table |
--reverse | false | reverse the sort direction |
--size | false | also compute each volume's on-disk size (slower: du per volume) |
--sort string | name | sort by: name|nodes|used|age|size (size implies --size) |
swarmexec volume rm
Remove a volume on all nodes (--all) or specific nodes (--node)
| Flag | Default | Description |
|---|---|---|
--all | false | remove on every node that holds the volume |
--connect-timeout duration | 10s | per-node connect timeout |
--force | false | pass docker's force flag |
--node stringArray | — | remove only on these nodes (repeatable) |
-y, --yes | false | do not prompt for confirmation |
swarmexec wait
Wait until services have converged — for CI after a deploy
Block until every named service (or every service of --stack) has converged, then exit 0. Exit 1 with the reason when one does not converge in time, when its update paused, or when it was rolled back during the wait.
Converged means: no update in flight, as many running tasks as desired (for a job: its completions reached), held for two polls in a row. With --healthy every container that has a healthcheck must also report healthy; a node whose agent cannot report health counts as "not yet", never as healthy.
| Flag | Default | Description |
|---|---|---|
--connect-timeout duration | 10s | timeout for connecting to an agent (--healthy) |
--healthy | false | also require every container with a healthcheck to be healthy (asks the agents) |
--stack string | — | wait for every service of this stack (in addition to any named) |
--timeout duration | 5m0s | give up after this long (exit 1) |
Global flags
Every command takes these.
| Flag | Default | Description |
|---|---|---|
--client-log-file string | — | swarmexec's own log file (default swarmexec.log next to config; the TUI also has a live viewer) |
--client-log-level string | info | swarmexec's own log verbosity: debug|info|warn|error|off |
--config string | — | config file path (default ~/.config/swarmexec/config.yaml) |
--context string | — | docker context for the manager API; supports ssh:// (also $DOCKER_CONTEXT) |
Connection flags
Every command takes these too; they reach the agents on the nodes. Most setups
set them once in the config file and never on
the command line. swarmexec help connection prints them.
| Flag | Default | Description |
|---|---|---|
--addr-mode string | — | node dial address: hostname|ip (default hostname) |
--agent-secret string | — | shared secret for a self-signed agent (Portainer-style auth) |
--agent-secret-file string | — | file to read the shared secret from |
--ca string | — | CA certificate to verify the agent (mTLS) |
--cert string | — | client certificate (mTLS; CN is the operator identity) |
--insecure | false | skip agent server-certificate verification (self-signed agents) |
--key string | — | client private key (mTLS) |
--operator string | — | operator identity reported for audit (default: OS username) |
--port int | 0 | agent port (default 9443) |
--server-name string | — | override TLS server name for agent verification |
Renamed names
These old names still work, unchanged, and are left out of the help. Prefer the new name in new scripts.
| Old | Now |
|---|---|
swarmexec --log-file | --client-log-file |
swarmexec --log-level | --client-log-level |
swarmexec prune-schedule | swarmexec node prune-schedule |
swarmexec stack deploy --force | --despite-findings |
swarmexec stack diff --format | --json (--format json) |