Allow good/warning/error/hint color to be customized

[milesj]

Please complete the following tasks

• [X] I have searched the discussions
• [X] I have searched the existing issues

Clap Version

3.0.0-rc.9

Describe your use case

I would like to use colored help/errors/etc in our CLI, but would like to change the colors to match our "brand".

Describe the solution you'd like

Provide a setting for good/warning/error/hint that allows the ANSI color code to be provided, based on the 256 table (or maybe 16m if you're crazy). https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg

It may be better to name the colors based on their actual usage, like arg/bin/label, etc.

Alternatives, if applicable

No response

Additional Context

No response

[epage]

One challenge with this is the API. We can't accept ANSI escape codes because clap3 intentionally added support for non-ANSI Windows terminals. We could copy the enums for color selections but we'd also need styling and the ability to compose them together. We end up starting to duplicate a decent chunk of a terminal styling API which we are hesitant to do (#1790 is a bit more extreme of an example).

We've been instead preferring for feedback on #2963 for improving our defaults and https://github.com/clap-rs/clap/issues/2914 for allowing people to more thoroughly customize things when those defaults don't work.

It may be better to name the colors based on their actual usage, like arg/bin/label, etc.

We've been moving in that direction. Originally, it was named after the color but the color also implied some other styling with it. The next step is for us to split off --help parts from abusing the existing semantics and giving them their own. Since this is internal, this isn't too much of a priority though will be addressed as part of #2963 and #2389.

would like to change the colors to match our "brand".

Mind elaborating what is "ok" and what runs counter to your "brand"? In what way does it run counter?

[milesj]

@epage That all makes sense. I've had enough experience with ANSI and CLI tools so I totally get it.

As for the branding piece, the colors are shades of purple/blue/teal. Here's an example of the log output.

And this is where the colors are configured if you're curious: https://github.com/milesj/moon/blob/master/crates/logger/src/color.rs

[epage]

If you have any feedback or proposals for https://github.com/clap-rs/clap/issues/2963, could you post it there?

Also, how important are errors or is the main concern the help?

Also, for anyone finding this issue, something that can help for re-evaluating is examples of precedence for this (like dialoguer) and proposals for how this would work either with older Windows support or why we can justify only supporting ANSI escape codes.

Otherwise, at this time I am closing out this issue, since there is no plan to grow the clap API to support this.

[epage]

Since this was closed, I've started work on https://github.com/epage/anstyle which aims to allow color definitions to be used in an API independent of the implementation which will allow users to define their stylesheet.

Blocked on https://github.com/epage/anstyle/issues/14

[epage]

From reddit

My preferred solution would be that, when customization is figured out, have the existing color behavior as some sort of easy to select "preset".

We could include presets for color schemes to help get people going.

[nyurik]

I recently switch to v4, and the lack of help colors is a bit disheartening - I grew fond of seeing colors in all the "cool new Rust-based Linux tools", and that color is what instantly made these tools stand apart from the old GNU tools. Now Clap only uses bold/underline, while continuing to call it "color". I tried to re-enable the legacy colors somehow, but despite searching all the release notes that only mention it in passing, and skimming through a very lengthy discussion on removing colors, I am beginning to suspect it is not (yet) possible.

To avoid breaking existing functionality, I feel v4 should have included the support for existing color styling from the beginning, even if it would require something like #[clap(legacy_color_scheme = true)].

Is this what is planned for the next release? Regardless of the minor grief above, thank you for all the hard work on Clap - it's one of the best crates we have in Rust! :)

[epage]

@nyurik

I tried to re-enable the legacy colors somehow, but despite searching all the release notes that only mention it in passing, and skimming through a very lengthy discussion on removing colors, I am beginning to suspect it is not (yet) possible.

4132 summarizes all of the help changes and includes workarounds, where possible.

For this case, it says

Users can't rollback until theming support is in (https://github.com/clap-rs/clap/issues/3234) though they can just disable the coloring with Command::disable_colored_help(true)

@nyurik

legacy_color_scheme

Such a flag is not going to be supported. Instead, our focus will be to theming

@nyurik

Is this what is planned for the next release

We do not commit to specific features for a "next release" as we we release on almost every PR made.

Addressing color support, in general, is a priority though. The main thing blocking theming support is releasing a 1.0 of https://docs.rs/anstyle/latest/anstyle/ which is blocked on getting more feedback on the API / more runtime to make sure the API is good for a 1.0 release, see https://github.com/epage/anstyle/issues/14, see also my earlier comment

As it becomes a chicken and egg problem, my plan has been to implement styling support in #3108 / #1433 as that will at least give me some experience with anstyle to decide when its ready to go 1.0 and be safe to use in other crate's APIs.

[nyurik]

Thanks @epage for such a great in-depth reply! I think we should modify the CHANGELOG file (and possibly the release v4 comment) -- to make it clearer. I searched for the word "color", and nothing came up. I found this

We've moved to a more neutral palette for highlighting elements (not highlighted above)

which is not a good explanation when a highly visible breaking change is introduced. Perhaps something like this text? I will be happy to make a pull request.

We have removed colored help in favor of bold and underlined text. There is currently no way to re-enable the old color scheme until the styling (#3108 / #1433) is implemented.

[epage]

As I'm trying to focus to get other things done so I can get back to that work, I do not have time to litigate a discussion about how to handle this (sorry, you are partly getting the short end of the stick from some other individuals taking up too much time / attention). As that is the case, we'll leave it as-is for now.

[casey]

Is this the issue to follow for color support? I'd like to upgrade to clap v4, but the lack of colored help is a blocker. I found this issue, but the title is a little ambiguous.

[epage]

Yes, this is the issue in that it will let you color the help as you wish

[ethanmsl]

Same as @casey. A sea of almost identical white text adds a lot of parse work to the user. And drains a lot of joy. A hard no for any app with an ounce of kindness, imo.

I'm glad to see that v3 documentation still exists though!

Is the plan to make color default again with specification possible or only allow color via manual specification? (If the later then that's a level of friction not consistent with my use case [I'm just looking to for very basic, readable user interfaces] and would just like to have a sense of trajectory before I invest in this system. [new to rust and trying to find cli app frameworks that let me focus on non-interface elements -- thanks in advance for any answer] )

[epage]

The plan is to add customization of whats already there. If someone wants to come up with a counter proposal for colors that meets the stated goals, we'll evaluate adopting it. So far, no one has taken up that offer. Once we allow customization, we're hoping people will do that implicitly and we'll watch to see what develops in the community.

As for other Rust CLI parsers, I believe they all have less text styling than clap.

[ethanmsl]

Thanks for the response @epage. I'm not at a place in my journey where I can fruitfully offer help on that issue. (maybe eventually!) I'll look into front-ending my rust code with another language and use one of their frameworks. (which seems funny for a cli, but different eco-systems are in different places)

Thanks for all the work you are doing! I can only imagine being the de facto face of argument parsing for the language is a lot of responsibility and makes decisions that leave any given set-up less supported feel very weighty.

[ethanmsl]

I've noticed that piping the output of clap into bat 🦈 🦇 gives excellent default highlighting. (i.e. easy to scan and parse)

Having only just begun looking at these crates (clap & bat's library) it's not immediately clear how to run the clap output through bat library and gain syntax advantages. (much less apply syntax processing during compilation vs runtime)

But a crate extension that enabled coloring that works on _many/most terminals, but, being an extension, needn't support the same breadth as clap seems to me to be a possible workaround.

Having an extension that deals with colorschemes and plugs into output syntax also seems like it might be a nice decoupling for the project.

Not sure how many suggestions you want from the peanut gallery. 🥜 🎪 But as far as the core code existing (though possibly not cleanly interfaceable ways 🤷) -- this does look like a promising approach from the outside.

Any thoughts? Has this been considered and reject previously? (e.g. due to code being so runtime focused that it couldn't easily get worked into a compile time extension)

---

Below, an example of runtime syntax parsing and highlighting of clap output, using the QuickStart Derive example from current docs (v4.1)

[epage]

Not sure how many suggestions you want from the peanut gallery. 🥜 🎪 But as far as the core code existing (though possibly not cleanly interfaceable ways 🤷) -- this does look like a promising approach from the outside.

Any thoughts? Has this been considered and reject previously? (e.g. due to code being so runtime focused that it couldn't easily get worked into a compile time extension)

This is a fairly complex solution with a large binary size and build-time impact. The proposed solution in this PR is relatively simple and mall; I just need to wrap up another project first.

[epage]

Support for this is now available as Command::styles with v4.2.3 when the unstable-styles feature is enabled.

Note: we are not guaranteeing semver compatibility on this feature until the feature flag is removed.

[dhruvkb]

Thank you @epage! Are there any examples/docs we can refer to? The docs for Command::styles seem to be incorrectly copied from Command::color.

[epage]

clap-rs/clap#4845 is correcting it

[epage]

I guess one question is whether we should re-export anstyle (and how) or require people to depend on it directly.

Re-exports are more convenient (no need for extra dep) and keep things in sync (though anstyle will hopefully never go 2.0 or if it does, we;'ll have a long time inbetween).

My guess is we could expose it as clap::builder::style.

Thoughts?

[dhruvkb]

I like the idea of re-exporting as it prevents the developer from needing to worry about compatibility 👍.

On a side note, I use the, derive notation but have to import Styles from clap::builder.

#[command(styles=clap::builder::Styles::plain())]
pub struct Arguments {
}

[DianaNites]

As a user, I always prefer when a libraries public dependencies are re-exported, the way I see it, its not my dependency, its the libraries, and I don't want to have to manage it in my Cargo.toml

As for how, I think re-exporting from the crate root is the best when its an entire dependency rather than just a type or few.

[epage]

On a side note, I use the, derive notation but have to import Styles from clap::builder.

That is true of a lot of functionality. We onlyh re-export the core types in the root.

[epage]

As for how, I think re-exporting from the crate root is the best when its an entire dependency rather than just a type or few.

(Emphasis mine)

If anstyle wasn't an independent crate, I'd most likely expose it in clap::builder or clap::builder::style.

I feel like a similar approach should be taken with re-exports. I feel like dumping it in the root without taking into account any other considerations can lead to a bloated root, making it harder to find things, and a less cohesive experience.

But getting opinions out like this is why I didn't immediately re-export but brought it up here so I can see what different people's thoughts were.

[bryantbiggs]

any pointers on how to enabled styled output - I've followed @dhruvkb snippet above but the output looks the same as before (and I enabled the colors and unstable-styles features as well)

[epage]

@bryantbiggs can you provide a minimal, complete reproduction case for whats not working for you, with a description of what you'd expect?

[dhruvkb]

I was able to color the section headers and argument names using this snippet (building on the styled_str.rs source file.

pub fn get_styles() -> clap::builder::Styles {
    clap::builder::Styles::styled()
        .header(
            anstyle::Style::new()
                .bold()
                .underline()
                .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Blue))),
        )
        .literal(
            anstyle::Style::new()
                .bold()
                .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Cyan))),
        )
}

#[command(styles=get_styles())]
pub struct Arguments {
    // ...
}

[eatradish]

Doesn't seem to be available in the builder api? (clap 4.2.4 with "cargo", "wrap_help", "unstable-styles", "color" features, rustc 1.68.2)

error[E0603]: struct `Styles` is private
  --> src/args.rs:1:37
   |
1  | use clap::{builder::{PossibleValue, Styles}, command, Arg, ArgAction, Command};
   |                                     ^^^^^^ private struct
   |
note: the struct `Styles` is defined here
  --> /home/saki/.cargo/registry/src/github.com-1ecc6299db9ec823/clap_builder-4.2.4/src/builder/mod.rs:66:16
   |
66 | pub(crate) use styled_str::Styles;
   |                ^^^^^^^^^^^^^^^^^^

error[E0599]: no method named `styles` found for struct `Command` in the current scope
  --> src/args.rs:49:10
   |
49 |         .styles(Styles::styled().usage(Default::default()))
   |          ^^^^^^ help: there is a method with a similar name: `get_styles`

Some errors have detailed explanations: E0599, E0603.
For more information about an error, try `rustc --explain E0599`.

[epage]

@eatradish did you run cargo add clap -F unstable-styles?

I wish rustc would partially parse disabled cfgs so it could tell suggest the feature to you

[eatradish]

@eatradish did you run cargo add clap -F unstable-styles?

I wish rustc would partially parse disabled cfgs so it could tell suggest the feature to you

My fault, I have set this version in Cargo.toml:

clap = { version = "4.2", features = ["cargo", "wrap_help", "color", "unstable-styles"] }

But the right thing to do is:

clap = { version = "4.2.4", features = ["cargo", "wrap_help", "color", "unstable-styles"] }

[dhruvkb]

I cannot find the style to use to change the appearance of the default and possible values. They always appear white. Is that not currently supported?

I understand that this might not be directly related to this issue, so I can open a new one if that's more appropriate.

[epage]

We do not yet have a style set apart for those. Any thoughts on a name? I was originally thinking "hint" though that might be confused the the "tip"s in error messages.

[dhruvkb]

"default" could be a good name for the default value, and "possibilities" for the possible values. That seems the most intuitive to me.

[epage]

I don't want to create a style per one of these bracketed items as that doesn't scale well for us to add more in the future.

Note: there is also one for env variables

[epage]

Besides naming the styling element for defaults, possible values, and env variables, I'm curious on how people think we should style it.

Some options I thought of:

• {spec}[default: true]{reset} (all styled the same)
• {spec}[default: {literal}true{reset}{spec}]{reset} (outer-styled, value stuled)
• [{spec}default:{reset} {literal}true{reset}] (key-styled, values-styled)

[nyurik]

I might be misunderstanding the last post - if {spec}, {literal}, and {reset} are ANSI color escape sequences, why does it say "all styled the same"?

I think the 1st variant is a subset of the 2nd (i.e. if literal style is the same as the spec) - so I would think the 2nd variant is preferred as it offers more flexibility. I also think that by default literal and spec should be the same color (thus producing the 1st variant) - as less color-disruptive (I wouldn't want my help screen to look like the early days of MS Word with word-art, with everyone using every single font available to print a flier). I am not a big fan of the 3rd.

[epage]

I might be misunderstanding the last post - if {spec}, {literal}, and {reset} are ANSI color escape sequences, why does it say "all styled the same"?

Sorry, forgot to go back and fix those

I think the 1st variant is a subset of the 2nd (i.e. if literal style is the same as the spec) - so I would think the 2nd variant is preferred as it offers more flexibility. I also think that by default literal and spec should be the same color (thus producing the 1st variant) - as less color-disruptive (I wouldn't want my help screen to look like the early days of MS Word with word-art, with everyone using every single font available to print a flier). I am not a big fan of the 3rd.

The difference between (1) and (2) is literal is an existing style, used by --flags and acts like backticks in markdown.

[nyurik]

thx, in that case yes, I think the 2nd is the best because it would allow this help screen (from above):

to be consistent for both the default and possible values:

display icons next to node names {spec}[default: true] [possible values: true, false]{reset}

[epage]

To be clear, (2) would cause true, true, and false to be teal like --icons, --align, and --multi-cols.

I hesitate about (2) because we want to draw attention to literals in the first column and in usage but it feels weird to in the help description, it might be too bus.

btw this is the current way we highlight something similar in errors

                        let _ = write!(styled, "\n{TAB}[possible values: ");
                        if let Some((last, elements)) = possible_values.split_last() {
                            for v in elements {
                                let _ = write!(
                                    styled,
                                    "{}{}{}, ",
                                    valid.render(),
                                    Escape(v),
                                    valid.render_reset()
                                );
                            }
                            let _ = write!(
                                styled,
                                "{}{}{}",
                                valid.render(),
                                Escape(last),
                                valid.render_reset()
                            );
                        }
                        styled.push_str("]");

[nyurik]

I think the most ideal for discussion is some real rendering image of all variants, perhaps in a few default variants (console vs markdown)? Kinda tricky to discuss it in a plain text format.

P.S. your code example made me realize it could use some DRY, so I made a https://github.com/clap-rs/clap/pull/4876 PR - hope its ok - deletes 23 lines :)

[AndreasBackx]

I was working on some tooling that makes it easier for people to switch over from x to Rust and came across this Python Click library to add colours to --help. I noticed it allows overriding colours per command as well. I could see it being useful where you colour some subcommands red to showcase they might be destructive or might require you being an admin or something (not referring to OS level root/admin but for whatever tool is being built). https://github.com/click-contrib/click-help-colors

Food for thought, could be something that needs thinking about for this particular issue as well.

[epage]

I think that would be a useful feature and, with the plugin system I've been adding to clap, it should minimize some of the negative effects of adding it.

The question for this thread is if there is anything about that that would require breaking changes to the existing feature before we stabilize it. The rest can be deferred out into its own issue.

Unfortunately, not seeing a quick reference, so from what I gather they allow

• help_headers_color
• help_options_color
• help_options_custom_colors (maps arg or command to color)
• prog_name_color (for --version)
• version_color (for --version)
• message_color (for --version)

All of that can be set on a per-command basis

One problem I see with what we currently do is we copy out styles to subcommand but we overwrite the subcommand, rather than allowing the subcommand to have special behavior.

Our style sheet is more fine grained in areas but doesn't allow controlling prog name and version separately. Our plugin system would offer a better way for coloring most things (color set directly on arg rather than in a map) but it won't let us easily hit things like version but we allow setting the version as styled./

For if/when we support per-arg and per-command styling, we'll need to make sure StyledStr can be sorted agnostic of styling.

[epage]

A new release is out that re-exports anstyle and includes some more examples

[epage]

As for styling of defaults, https://github.com/Canop/clap-help is somewhat similar to one of the options being considered.

[gibfahn]

The default example in https://github.com/Canop/clap-help#with-clap-help seems quite hard to read to me (compared to the current output), it's hard to see which option in the left column maps to which description on the right column, and it's hard to see where one option's help ends and the next one begins in the right column.

This is even more true when you have more detailed help text with examples for the options.

[epage]

I was more wanting to highlight how it styling the text (which ties into this issue) and not the wider formatting change

[epage]

At this point, the remaining open questions are

• How should [default: value] be styled / support styling
  • I'm leaning towards a uniform style for the whole block of text which means we won't use an existing style and can add this later. I'll create an issue for tracking this
  • EDIT: #5093
• Any future extensibility for customization
  • I'm thinking we shouldn't further block on this and create a separaet issue. @AndreasBackx mind creating an issue?

So at this point, I think I'm going to move towards stabilization

[donovanglover]

It took me some time to figure this out, but here's an example of adding color to --help.

use clap::builder::styling::{AnsiColor, Effects, Styles};
use clap::Parser;

fn styles() -> Styles {
    Styles::styled()
        .header(AnsiColor::Red.on_default() | Effects::BOLD)
        .usage(AnsiColor::Red.on_default() | Effects::BOLD)
        .literal(AnsiColor::Blue.on_default() | Effects::BOLD)
        .placeholder(AnsiColor::Green.on_default())
}

#[derive(Parser)]
#[command(author, version, about, styles = styles())]
pub struct Cli {
    // ...
}

[murlakatamenka]

It took me some time to figure this out, but here's an example of adding color to --help.

use clap::builder::styling::{AnsiColor, Effects, Styles};
use clap::Parser;

fn styles() -> Styles {
    Styles::styled()
        .header(AnsiColor::Red.on_default() | Effects::BOLD)
        .usage(AnsiColor::Red.on_default() | Effects::BOLD)
        .literal(AnsiColor::Blue.on_default() | Effects::BOLD)
        .placeholder(AnsiColor::Green.on_default())
}

#[derive(Parser)]
#[command(author, version, about, styles = styles())]
pub struct Cli {
    // ...
}

Piggybacking on this, since Styles::styled is const:

use clap::{
    builder::styling::{AnsiColor as Ansi, Styles},
    Parser,
};

const MY_AWESOME_STYLE: Styles = Styles::styled()
    .header(Ansi::Red.on_default().bold())
    .usage(Ansi::Red.on_default().bold())
    .literal(Ansi::Blue.on_default().bold())
    .placeholder(Ansi::Green.on_default());

#[derive(Parser)]
#[command(styles = MY_AWESOME_STYLE)]
pub struct Cli {
    // ...
}

fn main() {
    let _cli = Cli::parse();
}

Clap v3 Style:

• https://docs.rs/clap/4.5.2/clap/builder/struct.Styles.html#example

rustic's style:

• https://github.com/rustic-rs/rustic/blob/6fffaad1cc1aeebf874063fc62125f4ce3b490b5/src/commands.rs#L143-L149

[MilesCranmer]

Here's an example of manually customizing the colors in the help template:

https://github.com/MilesCranmer/rip2/blob/29b46efbff046515360cf5a16bdbae678db90b37/src/args.rs#L8-L83

Both in the text (with anstyle render) and by letting clap do it.

On white background:

And dark:

(Same color scheme as cargo)