# 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:

```console
$ docker pass set POSTGRES_PASSWORD=my-secret-password
```

### Or pass the secret via STDIN:

```console
$ echo my-secret-password > pwd.txt
$ cat pwd.txt | docker pass set POSTGRES_PASSWORD
```

### Set a secret with metadata:

```console
$ 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:

```console
$ echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES_PASSWORD
```

### Overwrite an existing secret:

```console
$ docker pass set POSTGRES_PASSWORD=new-secret-password --force
```