Software & SaaS
Writing a command reference for a core utility
A command reference is the clearest first asset for a tool brand. This guide shows how to document one imagined Unxit command so a stranger can trust it, try it and recover from mistakes.
01
Step one: define the single job
Start with one sentence that names the input, the action and the visible result. Example: the imagined command unxit sessions lists idle terminal sessions and can release one after confirmation. Avoid claiming it solves server management. Then write the synopsis, showing required arguments before optional flags. Keep verbs consistent, because users scan references quickly. If the job needs two sentences, the command probably contains two utilities. Resolving that early keeps the manual page short, the help output consistent and the later marketing description honest about what the tool actually does.
02
Step two: show safe and risky usage
Document a dry run before any destructive action. In the example, unxit sessions --list shows each session, owner and idle time, while unxit sessions --release 4 asks for confirmation. Give each flag one line, a default and a plain warning where data could be lost. Include one failure example, such as a missing permission, with the exact message and next action. Readers trust references that show limits. This section should answer what happens before the command changes anything, and how a person can inspect the outcome.
03
Step three: finish with recovery and examples
End with exit codes, related commands and three realistic examples. For the sample utility, list success, no matching session and permission denied as separate codes. Then provide one beginner example, one scripted example and one cautious review example that pipes output to a file. Add a short note explaining how to undo or re-check a release. A reader should be able to copy an example, understand its result and know where to look next. Review the page by following it on a clean machine.