Skip to content

refactor(pass): extract multi-line Long descriptions to embedded mark down #533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joe0BAB merged 1 commit into from
May 28, 2026
Merged

refactor(pass): extract multi-line Long descriptions to embedded mark down #533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 6 additions & 10 deletions plugins/pass/command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
17 changes: 6 additions & 11 deletions plugins/pass/commands/run.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,24 +52,19 @@ 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
}

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://<ID|pattern>`. 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"),
Copy link
Copy Markdown

@docker-agent docker-agent Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOW: Inconsistent whitespace trimming — only newlines stripped, \r and spaces would survive

strings.Trim(runLong, "\n") strips only newline characters from both ends of the embedded string, while command.go uses strings.TrimSpace(rootLong) which also removes carriage-returns, spaces, and tabs.

If run_long.md ever gains a trailing \r (e.g. committed from a Windows editor before git normalises line endings), it will appear verbatim in the Cobra Long help output. Consider using strings.TrimSpace here to match the root command and be robust to accidental whitespace.

Example: strings.Trim(runExample, "\n"),
Args: cobra.MinimumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
Expand Down
9 changes: 9 additions & 0 deletions plugins/pass/commands/run_long.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Scans the current environment (plus any `--env-file` inputs) for variables
whose value is exactly `se://<ID|pattern>`. 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.
14 changes: 4 additions & 10 deletions plugins/pass/commands/set.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"),
Copy link
Copy Markdown

@docker-agent docker-agent Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOW: Inconsistent whitespace trimming — only newlines stripped, \r and spaces would survive

strings.Trim(setLong, "\n") strips only newline characters from both ends of the embedded string, while command.go uses strings.TrimSpace(rootLong).

Same concern as run.go: a trailing carriage-return or a stray space/tab in set_long.md would survive this trim and appear in the Cobra Long help output. Using strings.TrimSpace consistently across all three call sites would eliminate this fragility.

Example: strings.Trim(setExample, "\n"),
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
Expand Down
10 changes: 10 additions & 0 deletions plugins/pass/commands/set_long.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 8 additions & 0 deletions plugins/pass/long.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading