Skip to content

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].