feat(pass): documentation

Signed-off-by: Johannes Großmann <grossmann.johannes@t-online.de>

Author: joe0BAB

plugins/pass/command.go

@@ -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
+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{

plugins/pass/commands/get.go

@@ -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 {

plugins/pass/commands/list.go

@@ -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())

plugins/pass/commands/rm.go

@@ -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 {

plugins/pass/commands/set.go

@@ -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 {