Skip to content

C0021 cli-help-text

Rule: Every command and argument of a CLI has a help line.

Code C0021 (stable, never reused)
Id cli-help-text
Category cli
Source spirit_level
Fix by hand
Needs cargo installed

Level per tier

Tier Level Reason
small warn -h is the map of a tool; an entry without a line leaves the reader guessing
small-workspace warn -h is the map of a tool; an entry without a line leaves the reader guessing
medium warn -h is the map of a tool; an entry without a line leaves the reader guessing
big warn -h is the map of a tool; an entry without a line leaves the reader guessing
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Why

-h is the map of a tool: one line per command and argument. An entry without a line forces the reader to guess or to open the source, and completion shows the same empty text beside the candidate. A help that exits non-zero, or is not in clap's layout, breaks scripts and the other help lints.

Example

Commands:
  sync   Bring the mirror up to date
  prune                         <- no help line

Options:
  -n, --name <NAME>             <- no help line

How to fix

Give every subcommand and argument a doc comment (or about / help); the tool itself gets an about. clap's own notes ([default: x], [possible values: ...]) do not count as help. A binary that is not a clap CLI is left out with cli = false in the crate map (CLI checks).

Configure

[lints.cli-help-text]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(cli-help-text) <reason> (waivers); the code works there too, as in [lints.C0021].