Skip to content

C0026 cli-usage-error

Rule: A CLI answers an unknown flag with exit code 2 and a message on stderr only.

Code C0026 (stable, never reused)
Id cli-usage-error
Category cli
Source spirit_level
Fix by hand
Needs cargo installed

Level per tier

Tier Level Reason
small warn a caller tells a wrong call from a failure by exit code 2
small-workspace warn a caller tells a wrong call from a failure by exit code 2
medium deny a caller tells a wrong call from a failure by exit code 2; clap gives it for free
big deny a caller tells a wrong call from a failure by exit code 2; clap gives it for free
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
code integer 2 the exit code of a usage error

Why

Scripts and agents tell a wrong call from a failed run by the exit code: 2 means "bad arguments, nothing ran", 1 a failure of the work itself. The message goes to stderr, so stdout carries only data and a caller that reads it sees nothing.

Example

$ tool --no-such-flag; echo $?
error: unexpected argument '--no-such-flag' found
...
2

How to fix

Let clap report usage errors: Cli::parse() exits with 2 and writes to stderr. A tool that catches clap's error itself returns ExitCode::from(2) and prints with eprintln!. The lint runs the binary with an unknown flag; the parameter code is the expected exit code.

Configure

[lints.cli-usage-error]
level = "deny"
code = 2
reason = "why this project wants it at this level"

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