docker pass set
| Description | Set a secret |
|---|---|
| Usage | docker pass set id[=value] [flags] |
Description
Stores a secret in the local OS keychain. The secret value can be provided inline (NAME=VALUE) or piped via STDIN.
Behavior when a secret with the same id already exists is platform-dependent:
- macOS (Keychain): the command fails with a duplicate-item error.
- Linux (Secret Service) and Windows (Credential Manager): the existing value is silently overwritten.
Pass --force to overwrite an existing secret. On Linux and Windows the
replacement is performed atomically. On macOS the Keychain API requires
a delete-then-add sequence.
Options
| Option | Default | Description |
|---|---|---|
-f, --force | Overwrite existing secret if it already exists | |
--metadata | Non-sensitive key=value metadata (repeatable) |
Examples
Set a secret:
$ docker pass set POSTGRES_PASSWORD=my-secret-password
Or pass the secret via STDIN:
$ echo my-secret-password > pwd.txt
$ cat pwd.txt | docker pass set POSTGRES_PASSWORD
Set a secret with metadata:
$ docker pass set POSTGRES_PASSWORD=my-secret-password --metadata owner=alice --metadata expiry=2027-03-01
Or pass a JSON payload with secret and metadata via STDIN:
$ echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES_PASSWORD
Overwrite an existing secret:
$ docker pass set POSTGRES_PASSWORD=new-secret-password --force