Skip to content

C0025 cli-color-flag

Rule: A CLI takes a global --color flag with auto, always and never.

Code C0025 (stable, never reused)
Id cli-color-flag
Category cli
Source spirit_level
Fix by hand
Needs cargo installed

Level per tier

Tier Level Reason
small warn --color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched
small-workspace warn --color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched
medium warn --color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched
big warn --color settles what automatic colour guesses wrong, the same way in every tool; 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
flag string "--color" the colour flag
values list of strings ["auto", "always", "never"] the values it takes

Why

Automatic colour guesses wrong sometimes: a pager that understands escapes, a CI log that renders them, a terminal a person wants plain. A --color auto|always|never flag settles it the same way in every tool. It is global, so it works after the subcommand too (tool sync --color never).

Example

#[derive(clap::Parser)]
struct Cli {
    #[command(flatten)]
    color: vc_ui::ColorFlag, // --color <WHEN>, global, default auto
    #[command(subcommand)]
    cmd: Cmd,
}

How to fix

Flatten vc_ui::ColorFlag into the root parser and call cli.color.apply() after parsing, or declare --color <WHEN> with the values auto, always and never and global = true. The parameters flag and values name the flag and its values.

Configure

[lints.cli-color-flag]
level = "deny"
flag = "--color"
values = ["auto", "always", "never"]
reason = "why this project wants it at this level"

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