swarmexec

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.

swarmexec

exec, logs, port-forward and a terminal UI for Docker Swarm — without SSH to the nodes

swarmexec [flags] swarmexec [command]
FlagDefaultDescription
--infofalseshow version, license, and contact info
-v, --versionfalseversion for swarmexec

Subcommands

swarmexec completion

Generate the autocompletion script for the specified shell

swarmexec completion [command]

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.

Subcommands

Also takes the global flags and the connection flags.

swarmexec completion bash

Generate the autocompletion script for bash

swarmexec completion 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:

Linux:

swarmexec completion bash > /etc/bash_completion.d/swarmexec

macOS:

swarmexec completion bash > $(brew --prefix)/etc/bash_completion.d/swarmexec

You will need to start a new shell for this setup to take effect.

FlagDefaultDescription
--no-descriptionsfalsedisable completion descriptions

Also takes the global flags and the connection flags.

swarmexec completion fish

Generate the autocompletion script for fish

swarmexec completion fish [flags]

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.

FlagDefaultDescription
--no-descriptionsfalsedisable completion descriptions

Also takes the global flags and the connection flags.

swarmexec completion powershell

Generate the autocompletion script for powershell

swarmexec completion powershell [flags]

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.

FlagDefaultDescription
--no-descriptionsfalsedisable completion descriptions

Also takes the global flags and the connection flags.

swarmexec completion zsh

Generate the autocompletion script for zsh

swarmexec completion zsh [flags]

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:

Linux:

swarmexec completion zsh > "${fpath[1]}/_swarmexec"

macOS:

swarmexec completion zsh > $(brew --prefix)/share/zsh/site-functions/_swarmexec

You will need to start a new shell for this setup to take effect.

FlagDefaultDescription
--no-descriptionsfalsedisable completion descriptions

Also takes the global flags and the connection flags.

swarmexec config

Inspect the resolved client configuration

swarmexec config [flags] swarmexec config [command]

Subcommands

Also takes the global flags and the connection flags.

swarmexec config show

Print the effective client configuration (secret masked)

swarmexec config show [flags]
FlagDefaultDescription
--jsonfalseoutput JSON instead of a table

Also takes the global flags and the connection flags.

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 [flags] swarmexec context [command]

Aliases: ctx

Subcommands

Also takes the global flags and the connection flags.

swarmexec context create

Create a Docker context pointing at a manager host

swarmexec context create <name> [flags]

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://.

FlagDefaultDescription
--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)
--usefalsealso make it the current context

Also takes the global flags and the connection flags.

swarmexec context ls

List Docker contexts

swarmexec context ls [flags]

Aliases: list

FlagDefaultDescription
--jsonfalseoutput JSON instead of a table

Also takes the global flags and the connection flags.

swarmexec context rm

Remove one or more Docker contexts

swarmexec context rm <name> [name...] [flags]

Aliases: remove

FlagDefaultDescription
-f, --forcefalseremove even if it is the current context (resets selection to default)

Also takes the global flags and the connection flags.

swarmexec context use

Set the current Docker context

swarmexec context use <name> [flags]

Also takes the global flags and the connection flags.

swarmexec cp

Copy files and directories to, from and between containers in the swarm

swarmexec cp [flags] <src> <dst>

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.

Examples

swarmexec cp ./patch.sql db:/tmp/ swarmexec cp web.1:/var/log/app.log ./app.log swarmexec cp web.1:/etc/nginx.conf db.2:/tmp/
FlagDefaultDescription
-a, --archivefalsekeep the owner and group recorded in the archive
--connect-timeout duration10stimeout for connecting to the agent
-L, --follow-linkfalsecopy what a symlinked source points at, not the link
--max-size string1Grefuse a copy larger than this (K/M/G, binary units)
--node string—node hint/override for container-id targets
-q, --quietfalseno progress output

Also takes the global flags and the connection flags.

swarmexec doctor

Diagnose the swarm: manager, agent deployment, and per-node agent health

swarmexec doctor [flags]
FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout
--jsonfalseoutput JSON instead of a table

Also takes the global flags and the connection flags.

swarmexec down

Remove the agent service (and secret) provisioned by `init`

swarmexec down [flags]

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.

FlagDefaultDescription
--keep-secretfalsedo not remove the shared-secret Docker secret
--service-name stringswarmexec_agentname of the agent service to remove
-y, --yesfalsedo not prompt for confirmation

Also takes the global flags and the connection flags.

swarmexec exec

Exec into a container running anywhere in the swarm

swarmexec exec [flags] <service|service.slot|task-id|container-id> [-- <cmd> [args...]]

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.

Examples

swarmexec exec web -- sh swarmexec exec web.2 -- cat /etc/hostname swarmexec exec -u root -w /app web -- ls -la
FlagDefaultDescription
--connect-timeout duration10stimeout for connecting to the agent
-e, --env stringArray—set environment variables (KEY=VALUE, repeatable)
--node string—node hint/override for container-id targets
-i, --stdintruekeep stdin open
-t, --ttyfalseallocate 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

Also takes the global flags and the connection flags.

swarmexec init

Provision the agent on every node of the swarm (self-signed + shared secret)

swarmexec init [flags]

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.

FlagDefaultDescription
--allow-legacy-secrettrueaccept the raw shared secret from clients predating connection-bound auth; pass=false once all clients are upgraded
--forcefalseupdate the service if it already exists
--image stringdocker.io/logleio/swarmexec-agent:latestagent image to deploy
--metrics-port int0publish 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 int9443host port the agent publishes
--registry-authtruepass local registry credentials so nodes can pull a private image
--rollout-timeout duration1m30show long to wait for agents to start
--save-configtruewrite the client config (~/.config/swarmexec/config.yaml)
--secret string—shared secret to use (default: generate a random one)
--service-name stringswarmexec_agentname for the agent service
--waittruewait for the agents to come up and report progress

Also takes the global flags and the connection flags.

swarmexec logs

Stream logs of one or more containers, services or a stack from anywhere in the swarm

swarmexec logs [flags] <service|service.slot|task-id|container-id>...

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.

Examples

swarmexec logs -f --tail 100 web swarmexec logs --grep 'timeout|refused' -f web swarmexec logs -f --tail 20 --stack shop
FlagDefaultDescription
--connect-timeout duration10stimeout for connecting to the agent
-f, --followfalsekeep 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 duration0sonly 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 uint320number of lines from the end to start with (0 = all)
-t, --timestampsfalseprefix each line with a timestamp

Also takes the global flags and the connection flags.

swarmexec mcp

Serve the swarm to an AI assistant over MCP (stdio)

swarmexec mcp [flags]

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.

FlagDefaultDescription
--allow strings—enable optional tools: report (security_report)
--connect-timeout duration10stimeout 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 stringnoneaccess for services without swarmexec.mcp.enable: none | list ("read" is accepted for list)

Also takes the global flags and the connection flags.

swarmexec node

List the swarm's nodes, prune them, set availability and labels, schedule prunes

swarmexec node [flags] swarmexec node [command]

Aliases: nodes

Subcommands

Also takes the global flags and the connection flags.

swarmexec node ls

List the nodes: role, availability, state, engine, running tasks, volumes, labels

swarmexec node ls [flags]

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).

FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout
--jsonfalseoutput JSON instead of a table
--skip-agentsfalsedo not ask the agents for volume counts (faster)

Also takes the global flags and the connection flags.

swarmexec node prune

Free disk on one node: stopped containers, untagged images, build cache, unused networks (images and volumes only when named)

swarmexec node prune <node> [flags]

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.

Examples

swarmexec node prune worker-1 swarmexec node prune worker-1 --categories containers,images --yes swarmexec node prune worker-1 --containers-until 2h
FlagDefaultDescription
--categories string—comma-separated: containers, images, dangling-images, buildcache, networks, volumes (default containers,dangling-images,buildcache,networks)
--connect-timeout duration10sper-node connect timeout
--containers-until string—keep stopped containers this long after they stop (default 24h; 0 keeps none)
-y, --yesfalsedo not prompt for confirmation

Also takes the global flags and the connection flags.

swarmexec node prune-schedule

Show or set the cluster-wide prune schedule the agents run

swarmexec node prune-schedule [flags] swarmexec node prune-schedule [command]

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.

Subcommands

Also takes the global flags and the connection flags.

swarmexec node prune-schedule set

Set (and enable) the schedule; flags not given keep their current value

swarmexec node prune-schedule set [flags]

Examples

swarmexec node prune-schedule set --days mon-fri --start 03:00 --times 2 --tz Europe/Berlin swarmexec node prune-schedule set --categories containers,images,buildcache,networks,volumes swarmexec node prune-schedule set --disable
FlagDefaultDescription
--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)
--disablefalseturn 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 int0runs per day, the day split evenly from --start (1-24)
--tz string—IANA time zone for --days and --start (default UTC)
-y, --yesfalsedo not prompt before restarting the agents

Also takes the global flags and the connection flags.

swarmexec node prune-schedule show

Show the schedule as the agent service carries it

swarmexec node prune-schedule show [flags]

Also takes the global flags and the connection flags.

swarmexec node update

Set a node's availability (active, pause, drain) or its labels

swarmexec node update <node> [flags]

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.

Examples

swarmexec node update worker-1 --availability drain --yes swarmexec node update worker-1 --label-add zone=b --label-rm old
FlagDefaultDescription
--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, --yesfalsedo not prompt before draining

Also takes the global flags and the connection flags.

swarmexec port-forward

Forward a local port to a port inside a container in the swarm

swarmexec port-forward [flags] <service|service.slot|task-id|container-id> [local:]remote

Aliases: pf

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.

Examples

swarmexec port-forward db 5432 swarmexec pf web 9090:8080 swarmexec port-forward web.2 8080
FlagDefaultDescription
--address string127.0.0.1local address to bind; loopback by default so the forwarded port is not exposed to your network
--connect-timeout duration10stimeout for connecting to the agent
--node string—node hint/override for container-id targets

Also takes the global flags and the connection flags.

swarmexec ps

List candidate tasks/containers and the node each runs on

swarmexec ps [service] [flags]

Examples

swarmexec ps swarmexec ps web swarmexec ps --json web
FlagDefaultDescription
--jsonfalseoutput JSON instead of a table

Also takes the global flags and the connection flags.

swarmexec secret

Work with swarm secrets

swarmexec secret [flags] swarmexec secret [command]

Aliases: secrets

Subcommands

Also takes the global flags and the connection flags.

swarmexec secret rotate

Replace a secret's content, keeping its name

swarmexec secret rotate <name> (--from-file FILE | --from-stdin) [flags]

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.

Examples

swarmexec secret rotate db_password --from-file ./db_password.txt printf %s "$NEW" | swarmexec secret rotate api_token --from-stdin --yes
FlagDefaultDescription
--from-file string—read the new value from this file
--from-stdinfalseread the new value from stdin
--timeout duration5m0show long to wait for each service's rolling update
-y, --yesfalsedo not ask for confirmation

Also takes the global flags and the connection flags.

swarmexec security

Security report of the cluster, and checks of stack files before deploying

swarmexec security [flags] swarmexec security [command]

Subcommands

Also takes the global flags and the connection flags.

swarmexec security check

Check a stack file for security antipatterns without deploying it

swarmexec security check <file> [stack] [flags]

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.

Also takes the global flags and the connection flags.

swarmexec security report

Write a Markdown security report for the whole cluster

swarmexec security report [flags]

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.

FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout when checking agents
-o, --output string—write to this file instead of stdout
--skip-agentsfalsedo not contact the node agents (faster; agent version skew is then reported as not covered)

Also takes the global flags and the connection flags.

swarmexec stack

Work with deployed stacks

swarmexec stack [flags] swarmexec stack [command]

Subcommands

Also takes the global flags and the connection flags.

swarmexec stack check

Check a stack file for security antipatterns without deploying it

swarmexec stack check <file> [stack] [flags]

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.

Also takes the global flags and the connection flags.

swarmexec stack deploy

Deploy a stack file, after checking it for security antipatterns

swarmexec stack deploy <file> [stack] [flags]

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.

FlagDefaultDescription
--checkfalseonly run the checks, never deploy
--despite-findingsfalsedeploy even though the check found something, without asking
--prunefalseremove services of the stack the file no longer declares
--with-registry-authfalsesend local registry credentials to the swarm, so nodes can pull private images
-y, --yesfalsedo not ask; deploy if the check found nothing actionable

Also takes the global flags and the connection flags.

swarmexec stack diff

Compare a stack file against the deployed stack

swarmexec stack diff <file> [stack] [flags]

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.

FlagDefaultDescription
--ignore strings—leave this field path out of both sides, e.g. services.*.deploy.replicas (repeatable)
--jsonfalseoutput JSON instead of text
--stack string—stack name to compare against (default: the file's base name)

Also takes the global flags and the connection flags.

swarmexec stack export

Write a deployed stack out as a compose file

swarmexec stack export <stack> [flags]

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.

FlagDefaultDescription
-o, --output string—write to this file instead of stdout

Also takes the global flags and the connection flags.

swarmexec stack ls

List the stacks deployed on the cluster

swarmexec stack ls [flags]

Also takes the global flags and the connection flags.

swarmexec stack rm

Remove a stack: its services, secrets, configs and networks

swarmexec stack rm <stack> [flags]

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).

FlagDefaultDescription
-y, --yesfalsedo not prompt for confirmation

Also takes the global flags and the connection flags.

swarmexec stats

Show live CPU and memory of each container, measured by the node agents

swarmexec stats [service...] [flags]

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.

Examples

swarmexec stats swarmexec stats web api swarmexec stats --json web
FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout
--jsonfalseoutput JSON instead of a table
--wait duration12show long to wait for agents still warming up (0: ask once)

Also takes the global flags and the connection flags.

swarmexec status

Show the cluster at a glance: nodes, services, replicas and health

swarmexec status [flags]

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.

FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout
--jsonfalseoutput JSON instead of tables

Also takes the global flags and the connection flags.

swarmexec ui

Terminal UI: stacks/services, volumes, forwards, networks, secrets, nodes, configs — several clusters in one session

swarmexec ui [service] [flags]

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.

Examples

swarmexec ui swarmexec ui web swarmexec --context prod ui
FlagDefaultDescription
--connect-timeout duration10stimeout for connecting to an agent

Also takes the global flags and the connection flags.

swarmexec volume

List and remove volumes across the swarm

swarmexec volume [flags] swarmexec volume [command]

Aliases: volumes

Subcommands

Also takes the global flags and the connection flags.

swarmexec volume ls

List volumes across all nodes and which nodes hold each

swarmexec volume ls [name-filter] [flags]
FlagDefaultDescription
--connect-timeout duration10sper-node connect timeout
--jsonfalseoutput JSON instead of a table
--reversefalsereverse the sort direction
--sizefalsealso compute each volume's on-disk size (slower: du per volume)
--sort stringnamesort by: name|nodes|used|age|size (size implies --size)

Also takes the global flags and the connection flags.

swarmexec volume rm

Remove a volume on all nodes (--all) or specific nodes (--node)

swarmexec volume rm <name> [flags]
FlagDefaultDescription
--allfalseremove on every node that holds the volume
--connect-timeout duration10sper-node connect timeout
--forcefalsepass docker's force flag
--node stringArray—remove only on these nodes (repeatable)
-y, --yesfalsedo not prompt for confirmation

Also takes the global flags and the connection flags.

swarmexec wait

Wait until services have converged — for CI after a deploy

swarmexec wait [flags] <service>...

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.

FlagDefaultDescription
--connect-timeout duration10stimeout for connecting to an agent (--healthy)
--healthyfalsealso 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 duration5m0sgive up after this long (exit 1)

Also takes the global flags and the connection flags.

Global flags

Every command takes these.

FlagDefaultDescription
--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 stringinfoswarmexec'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.

FlagDefaultDescription
--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)
--insecurefalseskip agent server-certificate verification (self-signed agents)
--key string—client private key (mTLS)
--operator string—operator identity reported for audit (default: OS username)
--port int0agent 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.

OldNow
swarmexec --log-file--client-log-file
swarmexec --log-level--client-log-level
swarmexec prune-scheduleswarmexec node prune-schedule
swarmexec stack deploy --force--despite-findings
swarmexec stack diff --format--json (--format json)