diff --git a/plugins/pass/command.go b/plugins/pass/command.go index c70241b5..2521555d 100644 --- a/plugins/pass/command.go +++ b/plugins/pass/command.go @@ -53,19 +53,15 @@ Examples: //go:embed examples.md var rootExample string +//go:embed long.md +var rootLong string + // Root returns the root command for the docker-pass CLI plugin func Root(ctx context.Context, s store.Store, info commands.VersionInfo) *cobra.Command { cmd := &cobra.Command{ - Use: "pass set|get|ls|rm|run", - Short: "Manage your local OS keychain secrets.", - Long: "Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed.\n" + - "It 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" + - "\n" + - "Secrets can be injected into running containers at runtime using the `se://` URI scheme.", + Use: "pass set|get|ls|rm|run", + Short: "Manage your local OS keychain secrets.", + Long: strings.TrimSpace(rootLong), Example: strings.TrimSpace(rootExample), SilenceUsage: true, TraverseChildren: true, diff --git a/plugins/pass/commands/run.go b/plugins/pass/commands/run.go index ec615a93..a065048d 100644 --- a/plugins/pass/commands/run.go +++ b/plugins/pass/commands/run.go @@ -52,6 +52,9 @@ func (e *ExitCodeError) Error() string { //go:embed run_example.md var runExample string +//go:embed run_long.md +var runLong string + type runOpts struct { envFiles []string } @@ -59,17 +62,9 @@ type runOpts struct { func RunCommand() *cobra.Command { opts := runOpts{} cmd := &cobra.Command{ - Use: "run -- CMD [ARGS...]", - Short: "Run a command with `se://` environment references resolved.", - Long: "Scans the current environment (plus any `--env-file` inputs) for variables\n" + - "whose value is exactly `se://`. Each reference is resolved through the\n" + - "secrets-engine daemon and the resolved value is passed to the child process.\n" + - "The child inherits stdin, stdout, and stderr.\n" + - "\n" + - "Requires the secrets-engine daemon (Docker Desktop) to be running.\n" + - "\n" + - "If any reference cannot be resolved, the command fails before the child is\n" + - "started and exits non-zero.", + Use: "run -- CMD [ARGS...]", + Short: "Run a command with `se://` environment references resolved.", + Long: strings.Trim(runLong, "\n"), Example: strings.Trim(runExample, "\n"), Args: cobra.MinimumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/plugins/pass/commands/run_long.md b/plugins/pass/commands/run_long.md new file mode 100644 index 00000000..0a38cd68 --- /dev/null +++ b/plugins/pass/commands/run_long.md @@ -0,0 +1,9 @@ +Scans the current environment (plus any `--env-file` inputs) for variables +whose value is exactly `se://`. Each reference is resolved through the +secrets-engine daemon and the resolved value is passed to the child process. +The child inherits stdin, stdout, and stderr. + +Requires the secrets-engine daemon (Docker Desktop) to be running. + +If any reference cannot be resolved, the command fails before the child is +started and exits non-zero. diff --git a/plugins/pass/commands/set.go b/plugins/pass/commands/set.go index 959491bb..fc2b0820 100644 --- a/plugins/pass/commands/set.go +++ b/plugins/pass/commands/set.go @@ -33,6 +33,9 @@ import ( //go:embed set_example.md var setExample string +//go:embed set_long.md +var setLong string + type setOpts struct { metadata []string // raw "key=value" strings from --metadata flag force bool // if true, overwrite existing secret instead of erroring @@ -49,16 +52,7 @@ func SetCommand(kc store.Store) *cobra.Command { Use: "set id[=value]", Aliases: []string{"store", "save"}, 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.\n" + - "\n" + - "Behavior when a secret with the same id already exists is platform-dependent:\n" + - " - macOS (Keychain): the command fails with a duplicate-item error.\n" + - " - Linux (Secret Service) and Windows (Credential Manager): the existing\n" + - " value is silently overwritten.\n" + - "\n" + - "Pass `--force` to overwrite an existing secret. On Linux and Windows the\n" + - "replacement is performed atomically. On macOS the Keychain API requires\n" + - "a delete-then-add sequence.", + Long: strings.Trim(setLong, "\n"), Example: strings.Trim(setExample, "\n"), Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/plugins/pass/commands/set_long.md b/plugins/pass/commands/set_long.md new file mode 100644 index 00000000..7cc4206b --- /dev/null +++ b/plugins/pass/commands/set_long.md @@ -0,0 +1,10 @@ +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. diff --git a/plugins/pass/long.md b/plugins/pass/long.md new file mode 100644 index 00000000..4ff7043d --- /dev/null +++ b/plugins/pass/long.md @@ -0,0 +1,8 @@ +Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed. +It uses platform-specific credential storage: + + - Windows: Windows Credential Manager API + - macOS: Keychain services API + - Linux: `org.freedesktop.secrets` API (requires DBus + `gnome-keyring` or `kdewallet`) + +Secrets can be injected into running containers at runtime using the `se://` URI scheme.