What Should a CLI Help Page Explain?
From the earlier reference collection. Read the current software blog.
A useful help page explains the command’s inputs, outputs, defaults, exit behavior, and a realistic example that users can adapt.
Describe the task and its inputs
Begin with a plain sentence about what the command does and the kinds of input it accepts. Name required arguments, optional files, and whether input can come from standard input. If a tool reads CSV, a schedule archive, or a date range, describe the expected format or point to a fuller reference.
Users should not have to run the program against real data to discover whether a positional argument is a file, an identifier, or a mode. A concise synopsis can show the shape: feed-check [OPTIONS] [FILE]. Then explain each element in familiar terms.
Explain outputs and defaults
State where successful results go: standard output, a named output path, or both. Explain defaults that affect interpretation, such as a time zone, date range, output format, or whether an existing file may be replaced. Defaults should be concrete. “Uses local time” is weaker than stating which zone is selected or how it is determined.
List options with their accepted values and indicate which ones can be combined. If an option requires a value, show the expected form, such as --from YYYY-MM-DD. Mention constraints that commonly cause confusion, including whether a range's ending date is inclusive.
Document failure behavior
Explain how the command signals errors and warnings. Users writing scripts need to know that a nonzero status means the requested operation failed, and whether warnings can accompany a successful result. If there is a machine-readable mode, note its format and the stream on which it appears.
A help page does not need to reproduce every internal error. It should give enough information to distinguish bad arguments from invalid input, and tell users where diagnostics appear. If a command can overwrite data, make that behavior conspicuous near the relevant option.
Show a representative example
Include an example that demonstrates a common path from input to result. For instance: feed-check --input daily-feed.zip --format summary can show how a named archive is selected and a summary requested. If standard input is supported, a second example can show a pipe. Use examples that match the actual interface and avoid placeholder URLs that look real unless clearly marked.
A good help page lets someone predict what will happen before running the command. Clear inputs, outputs, defaults, exit behavior, and one practical example make the interface easier to learn and safer to automate.