// Review or write CLI documentation. Enforces progressive disclosure, logical command ordering, and plain-language explanations. Use when asked to "write CLI docs", "document commands", "review CLI reference", or "update command docs".
| name | cli-docs-guidelines |
| description | Review or write CLI documentation. Enforces progressive disclosure, logical command ordering, and plain-language explanations. Use when asked to "write CLI docs", "document commands", "review CLI reference", or "update command docs". |
| argument-hint | <file-or-section> |
| metadata | {"author":"Celesto Team","version":"1.0.0"} |
Review or write CLI docs following these principles. CLI docs serve two audiences: newcomers running their first command, and experienced users scanning for flags.
All README Guidelines apply here. In addition:
Commands must appear in the order a user would run them. A command should never reference output or state from a command that appears later in the docs.
Wrong — stop appears before the user knows how to list:
smolvm stop <vm_id>
smolvm list
Right — create, inspect, then destroy:
smolvm create --name my-sandbox
smolvm list
smolvm stop my-sandbox
Show the base command before showing any flags or subcommands. Each flag is a new concept — don't introduce two flags in the same example unless they always go together.
Wrong — --os and --name are both new:
smolvm create --os debian --name my-debian-sandbox
Right — --name first, then a separate example for --os:
# Create a sandbox with a name
smolvm create --name my-sandbox
# Use a different OS image
smolvm create --os debian --name my-debian-sandbox
When a command prints a value the user needs (an ID, a URL, a status), show it. The reader should never have to run the command to find out what it returns.
smolvm browser start --live
# Session: sess_a1b2c3
# Live view: http://localhost:6080
Don't mix sandbox lifecycle commands with browser session commands in the same section. Each distinct workflow gets its own heading.
Never lead with a flags table. Explain what the command does in plain language first, then list flags for readers who want to go deeper.
<vm_id>, <session_id>) is introduced by a prior command or clearly labelled as "output from the previous step"For each violation found, output:
Line <N>: [rule violated]
Current: <quote the problematic text>
Fix: <suggested rewrite>
Then provide a revised version of any section that has more than one violation.