C0023 cli-completion¶
Rule: A CLI prints its shell completion registration for bash, zsh and fish.
| Code | C0023 (stable, never reused) |
| Id | cli-completion |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
completion makes a tool discoverable at the prompt; older CLIs add it when touched |
| small-workspace | warn |
completion makes a tool discoverable at the prompt; older CLIs add it when touched |
| medium | warn |
completion makes a tool discoverable at the prompt; older CLIs add it when touched |
| big | warn |
completion makes a tool discoverable at the prompt; older CLIs add it when touched |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
shells |
list of strings | ["bash", "zsh", "fish"] |
the shells a registration is asked for |
env |
string | "COMPLETE" |
the variable that asks the binary for its registration (clap_complete's CompleteEnv) |
Why¶
Completion makes a tool discoverable at the prompt: subcommands, flags and live values with their help. Dynamic completion asks the installed binary itself, so it never drifts from the version on PATH. The registration comes from the binary (source <(COMPLETE=bash tool)), so this lint asks for it the same way. A bash registration with -o bashdefault falls back to file names when completion fails, which offers wrong candidates instead of none.
Example¶
fn main() -> std::process::ExitCode {
clap_complete::CompleteEnv::with_factory(Cli::command).complete();
// or, with vhrd_cli: vc_complete::complete(Cli::command);
let cli = Cli::parse();
// ...
}
How to fix¶
Call CompleteEnv (clap_complete's unstable-dynamic feature) or vc_complete::complete first in main. Give arguments with live values an ArgValueCompleter. The parameter shells lists the shells asked for and env the variable; the lint runs COMPLETE=<shell> tool --help, which prints the registration in a CLI with completion and the help in one without.
Configure¶
[lints.cli-completion]
level = "deny"
shells = ["bash", "zsh", "fish"]
env = "COMPLETE"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(cli-completion) <reason> (waivers); the code works there too, as in [lints.C0023].