List Swarm Configs with docker config ls

You need to know what configs a Swarm is holding, and you would rather not spill their contents to find out. docker config ls gives you the inventory without printing the secret or configuration data stored in each config. You will finish with a safe way to list configs, narrow the list by name or label, and produce output that scripts can consume.

Allow about ten minutes. You need Docker CLI 29.8.1 from docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, access to a Docker context connected to a Swarm manager, and permission to inspect that cluster. The examples are read-only. They do not initialise Swarm, create configs, remove configs or change services.

1. Confirm the installed command

Check the binary and package before relying on option details. These are ordinary, read-only commands and do not need elevated privileges:

$ docker --version
Docker version 29.8.1, build 4a63305
$ dpkg-query -W -f='\${Package} \${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble
$ docker config ls --help

The installed syntax is docker config ls [OPTIONS]. The command also accepts the alias docker config list. The available options are:

--filter (-f). Narrow the list.
--format. Choose the output shape.
--quiet (-q). Print IDs only.

Checkpoint: if the help output is different, follow the installed output for this host. Do not paste options from a different Docker release into an unattended script without testing them.

2. Check that the context is a Swarm manager

docker config ls is a cluster-management command. It works against the Swarm controlled by the current Docker context and must run on a manager node. Check the context without changing it:

$ docker context show
default
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'
active true

The exact docker info values depend on the host. You want an active Swarm and manager control available. If you are on a worker, ask a cluster administrator to run the inventory on a manager or provide an appropriate context.

Warning: do not run docker swarm init or docker swarm join just to make this listing work. Those commands change cluster membership and are outside this guide.

Now test the connection with the harmless listing command:

$ docker config ls
ID                          NAME            CREATED         UPDATED
9z7...                      app-settings    3 days ago      3 days ago

IDs, names and relative times vary. A failure such as This node is not a Swarm manager means the command reached Docker but the node cannot perform this manager-only operation. It is not fixed by sudo.

3. List only the configs you need

Use the name filter when you know a config name or a distinctive prefix. The filter matches a complete name or prefix, so keep the value narrow:

$ docker config ls --filter 'name=app-'
ID                          NAME            CREATED         UPDATED
9z7...                      app-settings    3 days ago      3 days ago

Use an ID or ID prefix when an automation run has already recorded one:

$ docker config ls --filter 'id=9z7'
ID                          NAME            CREATED         UPDATED
9z7...                      app-settings    3 days ago      3 days ago

Labels are useful for ownership and deployment grouping. A key-only filter selects configs carrying that label, while a key and value selects a particular value:

$ docker config ls --filter 'label=project=payments'
ID                          NAME            CREATED         UPDATED
9z7...                      app-settings    3 days ago      3 days ago

These filters affect the list, not the contents of a config. Multiple --filter options can be supplied when you need more than one condition. Confirm the result against the expected name or ID before passing it to a later command.

4. Produce stable fields for scripts

Use --quiet when a later command needs only IDs:

$ docker config ls --quiet --filter 'name=app-'
9z7...

For an explicit pair of fields, use a Go template. This output has no table header, which makes it easier to read line by line:

$ docker config ls --format '{{.ID}}: {{.Name}}'
9z7...: app-settings

The documented placeholders include .ID, .Name, .CreatedAt, .UpdatedAt, .Labels and .Label. To keep a header while choosing columns, use the table directive:

$ docker config ls --format 'table {{.ID}}\t{{.Name}}\t{{.UpdatedAt}}'
ID                          NAME            UPDATED
9z7...                      app-settings    3 days ago

The installed help also advertises --format json. Prefer that form when your local Docker version emits the JSON shape your parser expects, and inspect one real result before building a pipeline around it:

$ docker config ls --format json
[{"ID":"9z7...","Name":"app-settings"}]

Warning: do not treat the displayed ID as the config data. Listing metadata is not a way to audit the contents of a configuration file, and a config may contain sensitive values even though this command does not show them.

5. Diagnose empty and failed listings

An empty table can be correct. It may mean the manager has no configs, your filter matched nothing, or the current context points at a different Swarm. Remove filters for one comparison:

$ docker config ls
$ docker config ls --filter 'name=the-prefix-you-expect'

Unfiltered command fails. Check docker context show, the Docker endpoint selected by that context, and the manager status.
Unfiltered works, filtered is empty. Check the exact name or label spelling. Name filtering is prefix-oriented, and labels are matched by key and, when supplied, value.
Access denied. If the Docker socket or remote endpoint refuses you, fix the context or membership through your normal administration process.

Warning: adding a user to the docker group grants broad control over the Docker host and is a security-sensitive change. Do not make that change merely to avoid diagnosing the endpoint permissions.

Done means

Version confirmed. You checked the local Docker CLI and package version.
Manager reached. The current context reaches an active Swarm manager.
Lists narrowed. You can list all configs or narrow the result by ID, name or label.
Output chosen. You can pick IDs, table columns or template output for the next tool.
Metadata only. The command shows metadata, not config contents.
Nothing changed. You have not initialised, joined, changed or removed a Swarm resource.