1# secret ls
2
3<!---MARKER_GEN_START-->
4List secrets
5
6### Aliases
7
8`docker secret ls`, `docker secret list`
9
10### Options
11
12| Name | Type | Default | Description |
13|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
14| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
15| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
16| `-q`, `--quiet` | | | Only display IDs |
17
18
19<!---MARKER_GEN_END-->
20
21## Description
22
23Run this command on a manager node to list the secrets in the swarm.
24
25For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
26
27> **Note**
28>
29> This is a cluster management command, and must be executed on a swarm
30> manager node. To learn about managers and workers, refer to the
31> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
32> documentation.
33
34## Examples
35
36```console
37$ docker secret ls
38
39ID NAME CREATED UPDATED
406697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago
419u9hk4br2ej0wgngkga6rp4hq my_secret 5 weeks ago 5 weeks ago
42mem02h8n73mybpgqjf0kfi1n0 test_secret 3 seconds ago 3 seconds ago
43```
44
45### <a name="filter"></a> Filtering (--filter)
46
47The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
48than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).
49
50The currently supported filters are:
51
52- [id](#id) (secret's ID)
53- [label](#label) (`label=<key>` or `label=<key>=<value>`)
54- [name](#name) (secret's name)
55
56#### id
57
58The `id` filter matches all or prefix of a secret's id.
59
60```console
61$ docker secret ls -f "id=6697bflskwj1998km1gnnjr38"
62
63ID NAME CREATED UPDATED
646697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago
65```
66
67#### label
68
69The `label` filter matches secrets based on the presence of a `label` alone or
70a `label` and a value.
71
72The following filter matches all secrets with a `project` label regardless of
73its value:
74
75```console
76$ docker secret ls --filter label=project
77
78ID NAME CREATED UPDATED
79mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago
80```
81
82The following filter matches only services with the `project` label with the
83`project-a` value.
84
85```console
86$ docker service ls --filter label=project=test
87
88ID NAME CREATED UPDATED
89mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago
90```
91
92#### name
93
94The `name` filter matches on all or prefix of a secret's name.
95
96The following filter matches secret with a name containing a prefix of `test`.
97
98```console
99$ docker secret ls --filter name=test_secret
100
101ID NAME CREATED UPDATED
102mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago
103```
104
105### <a name="format"></a> Format the output (--format)
106
107The formatting option (`--format`) pretty prints secrets output
108using a Go template.
109
110Valid placeholders for the Go template are listed below:
111
112| Placeholder | Description |
113|--------------|--------------------------------------------------------------------------------------|
114| `.ID` | Secret ID |
115| `.Name` | Secret name |
116| `.CreatedAt` | Time when the secret was created |
117| `.UpdatedAt` | Time when the secret was updated |
118| `.Labels` | All labels assigned to the secret |
119| `.Label` | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` |
120
121When using the `--format` option, the `secret ls` command will either
122output the data exactly as the template declares or, when using the
123`table` directive, will include column headers as well.
124
125The following example uses a template without headers and outputs the
126`ID` and `Name` entries separated by a colon (`:`) for all images:
127
128```console
129$ docker secret ls --format "{{.ID}}: {{.Name}}"
130
13177af4d6b9913: secret-1
132b6fa739cedf5: secret-2
13378a85c484f71: secret-3
134```
135
136To list all secrets with their name and created date in a table format you
137can use:
138
139```console
140$ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}"
141
142ID NAME CREATED
14377af4d6b9913 secret-1 5 minutes ago
144b6fa739cedf5 secret-2 3 hours ago
14578a85c484f71 secret-3 10 days ago
146```
147
148To list all secrets in JSON format, use the `json` directive:
149```console
150$ docker secret ls --format json
151{"CreatedAt":"28 seconds ago","Driver":"","ID":"4y7hvwrt1u8e9uxh5ygqj7mzc","Labels":"","Name":"mysecret","UpdatedAt":"28 seconds ago"}
152```
153
154## Related commands
155
156* [secret create](secret_create.md)
157* [secret inspect](secret_inspect.md)
158* [secret rm](secret_rm.md)
View as plain text