command: docker pass set
short: Set a secret
long: |-
    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.
usage: docker pass set id[=value] [flags]
pname: docker pass
plink: docker_pass.yaml
options:
    - option: force
      shorthand: f
      value_type: bool
      default_value: "false"
      description: Overwrite existing secret if it already exists
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: metadata
      value_type: stringArray
      default_value: '[]'
      description: Non-sensitive key=value metadata (repeatable)
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
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
    ```