diff --git a/data/cli/secrets/docker_pass.yaml b/data/cli/secrets/docker_pass.yaml index e45c42963628..be7381bc20bf 100644 --- a/data/cli/secrets/docker_pass.yaml +++ b/data/cli/secrets/docker_pass.yaml @@ -1,64 +1,84 @@ command: docker pass short: Manage your local OS keychain secrets. -long: |- - Docker Pass is a helper that allows you to store secrets securely in your - local OS keychain and inject them into containers later. - - On Windows: Uses the Windows Credential Manager API. - - On macOS: Uses macOS Keychain services API. - - On Linux: `org.freedesktop.secrets` API (requires DBus and `gnome-keyring` or - `kdewallet` to be installed). +long: "Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed. \nIt uses platform-specific credential storage:\n\n - Windows: Windows Credential Manager API\n - macOS: Keychain services API\n - Linux: org.freedesktop.secrets API (requires DBus + gnome-keyring or kdewallet)\n\nSecrets can be injected into running containers at runtime using the se:// URI scheme." usage: docker pass set|get|ls|rm pname: docker plink: docker.yaml cname: - - docker pass set - - docker pass get - - docker pass ls - - docker pass rm + - docker pass get + - docker pass ls + - docker pass rm + - docker pass set clink: - - docker_pass_set.yaml - - docker_pass_get.yaml - - docker_pass_ls.yaml - - docker_pass_rm.yaml + - docker_pass_get.yaml + - docker_pass_ls.yaml + - docker_pass_rm.yaml + - docker_pass_set.yaml deprecated: false +hidden: false experimental: true experimentalcli: true kubernetes: false swarm: false examples: |- - ### Using keychain secrets in containers + ### Using keychain secrets in containers + + Create a secret: + + ```console + $ docker pass set GH_TOKEN=123456789 + ``` + + Create a secret from STDIN: + + ```console + echo "my_val" | docker pass set GH_TOKEN + ``` + + Run a container that uses the secret: + + ```console + $ docker run -e GH_TOKEN= -dt --name demo busybox + ``` - Create a secret: + Inspect the secret from inside the container: - ```console - $ docker pass set GH_TOKEN=123456789 - ``` + ```console + $ docker exec demo sh -c 'echo $GH_TOKEN' + 123456789 + ``` - Creating a secret from STDIN: + Explicitly assign a secret to a different environment variable: - ```console - echo 123456789 > token.txt - cat token.txt | docker pass set GH_TOKEN - ``` + ```console + $ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox + ``` - Run a container that uses the secret: + ### Using keychain secrets in Compose - ```console - $ docker run -e GH_TOKEN= -dt --name demo busybox - ``` + Store the secrets: - Inspect your secret from inside the container + ```console + $ docker pass set myapp/anthropic/api-key=sk-ant-... + $ docker pass set myapp/postgres/password=s3cr3t + ``` - ```console - $ docker exec demo sh -c 'echo $GH_TOKEN' - 123456789 - ``` + ```yaml + services: + api: + image: service1 + environment: + - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key + - POSTGRES_PASSWORD=se://myapp/postgres/password - Explicitly assigning a secret to another environment variable: + worker: + image: service2 + command: worker + environment: + - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key - ```console - $ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox - ``` + db: + image: postgres:17 + environment: + - POSTGRES_PASSWORD=se://myapp/postgres/password + ``` diff --git a/data/cli/secrets/docker_pass_get.yaml b/data/cli/secrets/docker_pass_get.yaml index 6c4bbcc089c5..dee06e69f981 100644 --- a/data/cli/secrets/docker_pass_get.yaml +++ b/data/cli/secrets/docker_pass_get.yaml @@ -1,5 +1,6 @@ command: docker pass get -short: Get a secret +short: Get a secret from a keystore. +long: Retrieves a named secret from the local OS keychain. The secret value is masked in output. usage: docker pass get NAME pname: docker pass plink: docker_pass.yaml diff --git a/data/cli/secrets/docker_pass_ls.yaml b/data/cli/secrets/docker_pass_ls.yaml index 2db3a30d0a78..12c067de1ebf 100644 --- a/data/cli/secrets/docker_pass_ls.yaml +++ b/data/cli/secrets/docker_pass_ls.yaml @@ -1,5 +1,6 @@ command: docker pass ls -short: List secrets +short: List all secrets from local keychain. +long: Lists the names of all secrets stored in the local OS keychain. usage: docker pass ls pname: docker pass plink: docker_pass.yaml diff --git a/data/cli/secrets/docker_pass_rm.yaml b/data/cli/secrets/docker_pass_rm.yaml index b35848bfafe1..588fb1232295 100644 --- a/data/cli/secrets/docker_pass_rm.yaml +++ b/data/cli/secrets/docker_pass_rm.yaml @@ -1,11 +1,34 @@ command: docker pass rm -short: Remove a secret -usage: docker pass rm NAME +short: Remove secrets from local keychain. +long: |- + Removes one or more named secrets from the local OS keychain. + Use --all to remove every stored secret at once. +usage: docker pass rm name1 name2 ... [flags] pname: docker pass plink: docker_pass.yaml +options: + - option: all + value_type: bool + default_value: "false" + description: Remove all secrets + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false hidden: false experimental: true experimentalcli: true kubernetes: false swarm: false +examples: |- + ### Remove a specific secret: + docker pass rm GH_TOKEN + + ### Remove multiple secrets: + docker pass rm GH_TOKEN NPM_TOKEN + + ### Remove all secrets: + docker pass rm --all diff --git a/data/cli/secrets/docker_pass_set.yaml b/data/cli/secrets/docker_pass_set.yaml index 5e2931757bfa..0e831cf54b54 100644 --- a/data/cli/secrets/docker_pass_set.yaml +++ b/data/cli/secrets/docker_pass_set.yaml @@ -1,17 +1,38 @@ command: docker pass set short: Set a secret -usage: docker pass set NAME=VALUE long: |- - Secrets can also be created from STDIN: - - ```console - | docker pass set - ``` + Stores a secret in the local OS keychain. The secret value can be + provided inline (NAME=VALUE) or piped via STDIN. +usage: docker pass set id[=value] [flags] pname: docker pass plink: docker_pass.yaml +options: + - 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: true experimentalcli: true kubernetes: false swarm: false +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