Skip to content

feat(pass): documentation #511

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
Apr 23, 2026
Merged

feat(pass): documentation #511

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
12 changes: 11 additions & 1 deletion plugins/pass/command.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,17 @@ Examples:
// 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 [OPTIONS]",
Use: "pass [OPTIONS]",
Short: "Manage your local OS keychain secrets.",
Long: `Docker Pass is an experimental utility for managing secrets in your

@docker-agent docker-agent Bot Apr 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[MEDIUM] Long descriptions are never rendered — {{.Long}} missing from helpTemplate

The Long descriptions added in this PR (for the root command and all four subcommands: get, set, list, rm) will never appear in CLI help output.

Root cause: The custom helpTemplate defined in command.go (set via cmd.SetHelpTemplate) does not include {{.Long}}. Cobra propagates the parent's help template to all child commands unless they override it, and none of the subcommands set their own template. As a result, running docker pass --help, docker pass get --help, etc. silently drops every Long description.

Impact: All the documentation effort in this PR is functionally dead code — users will never see those detailed descriptions through the CLI.

Fix: Either add {{if .Long}}{{.Long}}\n\n{{end}} to the helpTemplate in command.go, or remove the Long fields if only Short is needed and external doc generation is not planned.

local OS keychain. Secrets are stored using 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.`,
SilenceUsage: true,
TraverseChildren: true,
CompletionOptions: cobra.CompletionOptions{
Expand Down
1 change: 1 addition & 0 deletions plugins/pass/commands/get.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ func GetCommand(kc store.Store) *cobra.Command {
Use: "get",
Args: cobra.ExactArgs(1),
Short: "Get a secret from a keystore.",
Long: "Retrieves a named secret from the local OS keychain. The secret value is masked in output.",
RunE: func(cmd *cobra.Command, args []string) error {
id, err := store.ParseID(args[0])
if err != nil {
Expand Down
1 change: 1 addition & 0 deletions plugins/pass/commands/list.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ func ListCommand(kc store.Store) *cobra.Command {
Use: "ls",
Aliases: []string{"list"},
Short: "List all secrets from local keychain.",
Long: "Lists the names of all secrets stored in the local OS keychain.",
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
l, err := kc.GetAllMetadata(cmd.Context())
Expand Down
9 changes: 9 additions & 0 deletions plugins/pass/commands/rm.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,15 @@ func RmCommand(kc store.Store) *cobra.Command {
Use: "rm name1 name2 ...",
Aliases: []string{"delete", "erase", "remove"},
Short: "Remove secrets from local keychain.",
Long: "Removes one or more named secrets from the local OS keychain.\nUse --all to remove every stored secret at once.",
Example: `# 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`,
RunE: func(cmd *cobra.Command, args []string) error {
idList, err := validateArgs(args, opts)
if err != nil {
Expand Down
2 changes: 2 additions & 0 deletions plugins/pass/commands/set.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ 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.`,
Example: strings.Trim(setExample, "\n"),
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
Expand Down
Loading