C0020 cli-help-examples¶
Rule: --help of a CLI and of each of its leaf commands ends in an Examples block.
| Code | C0020 (stable, never reused) |
| Id | cli-help-examples |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a reader learns a command from its examples first; most existing CLIs lack them on many leaves |
| small-workspace | warn |
a reader learns a command from its examples first; most existing CLIs lack them on many leaves |
| medium | warn |
a reader learns a command from its examples first; most existing CLIs lack them on many leaves |
| big | warn |
a reader learns a command from its examples first; most existing CLIs lack them on many leaves |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
headings |
list of strings | ["Examples:", "Example:"] |
headings that open an examples block, compared without case |
exempt |
list of strings | [] |
subcommand paths without examples, words separated by spaces (* add; * one word, ** any) |
Why¶
People and agents learn a tool from its examples first. A long help that ends in a few real command lines answers "how do I call this" without a trip to a README. The guide asks for an Examples: block in the help of the tool and of every leaf command: a command that does the work, not a group of subcommands.
Example¶
$ tool task add --help
Add a task to a project
...
Examples:
tool task add P1 "Order parts"
tool task add P1 "Fix the build" --due 2026-12-01
How to fix¶
End the long help with Examples: and a few lines (clap: after_long_help, or after_help to show them in -h too). Commands that need none go into the parameter exempt as paths without the binary's name: "completions", "* list". The lint runs --help of the built binary (CLI checks).
Configure¶
[lints.cli-help-examples]
level = "deny"
headings = ["Examples:", "Example:"]
exempt = []
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(cli-help-examples) <reason> (waivers); the code works there too, as in [lints.C0020].