Recipe
CLI reference design
A proven pattern for terminal help output that users actually read. Structure flags, subcommands, and examples so every screenful earns its pixels.
The problem
Most CLI tools dump 200 lines of flags into a wall of text. Users scroll past the one flag they need. Reference pages must guide the eye — hierarchy first, details on demand.
Layout anatomy
USAGE
$ tool <command> [flags]
COMMANDS
initscaffold configbuildcompile projectservestart dev server
GLOBAL FLAGS
--output, -ooutput directory--verbose, -vdebug logging
Rules of thumb
- 1.Group flags by concern — never alphabetically.
- 2.Show the happy path first. Edge cases go last.
- 3.Every example must be copy-paste runnable.
- 4.Long-form flags get short aliases only if used daily.
Real-world reference
Study git, cargo, and docker help output. Notice how each uses consistent indentation, sentence-case descriptions, and never buries the most-used subcommand.