Conversation
Move the set, run, and rm command examples into sibling .md files and embed them via //go:embed, mirroring the root command. Wrap example shell snippets in fenced console blocks and use inline backticks for flag and value references in Long descriptions.
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR cleanly extracts Cobra CLI examples into embedded .md files — a nice refactor. Two issues were found in the newly-added lines:
- Inconsistent shell prompt prefix in
examples.md— oneconsoleblock is missing the leading$. - Misleading
se://<ID|pattern>inrun.goLong description — wildcards are explicitly rejected at runtime bysecrets.ParseID.
| Create a secret from STDIN: | ||
|
|
||
| ```console | ||
| echo "my_val" | docker pass set GH_TOKEN |
There was a problem hiding this comment.
[MEDIUM] Inconsistent shell prompt prefix in console block
Every other console fenced block in examples.md uses a $ prompt prefix (lines 6, 19, 24–25, 30, 38–39), but the "Create a secret from STDIN" block on line 12 does not:
echo "my_val" | docker pass set GH_TOKENThis makes the line look like output rather than a command to type, which will confuse users reading docker pass --help. It should be:
$ echo "my_val" | docker pass set GH_TOKEN| started and exits non-zero.`, | ||
| 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" + |
There was a problem hiding this comment.
[MEDIUM] se://<ID|pattern> in Long description misrepresents supported syntax
The updated Long description says:
"whose value is exactly
se://<ID|pattern>"
This implies glob/wildcard patterns (e.g. se://myapp/*) are accepted. However, the underlying resolveRef function calls secrets.ParseID(name) first, which validates only [A-Za-z0-9._:-/] — the * wildcard character is explicitly excluded. Any se:// reference containing a wildcard is rejected before pattern resolution is attempted.
The original description said se://NAME, which accurately reflected the supported syntax. Consider reverting to se://<NAME> or se://<ID> to avoid misleading users who will get a cryptic error when they try se://myapp/*.
2 participants
Summary
plugins/pass/command.go,commands/set.go,commands/run.go, andcommands/rm.gointo sibling.mdfiles and load them via//go:embed.consolecode blocks so they render nicely in generated docs.--force,--all,--env-file,se://,se://<ID|pattern>,NAME=VALUE) in commandLongdescriptions.No behavior change — help output and examples are unchanged in content, only relocated and lightly reformatted.