Skip to content

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