From c4aee8846d124f9c70fac330ef1ff9acde7fee42 Mon Sep 17 00:00:00 2001
From: Ruben Arts <ruben.arts@hotmail.com>
Date: Tue, 11 Mar 2025 16:47:06 +0100
Subject: [PATCH] feat: improve cli help headers and styling (#3329)

---
 Cargo.lock                        |  11 ---
 Cargo.toml                        |   2 -
 crates/pixi_config/src/lib.rs     |  16 ++---
 crates/pixi_consts/src/consts.rs  |   3 +
 docs/reference/cli/pixi.md        |   6 +-
 docs/reference/cli/pixi/add.md    |   4 --
 docs/reference/cli/pixi/remove.md |   4 --
 pixi_docs/Cargo.lock              |  11 ---
 src/cli/cli_config.rs             |  16 ++---
 src/cli/config.rs                 |   6 +-
 src/cli/mod.rs                    | 107 ++++++++++++++++++++++--------
 11 files changed, 105 insertions(+), 81 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 62dd0e42d..4aec0304c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1178,16 +1178,6 @@ dependencies = [
  "clap_derive",
 ]
 
-[[package]]
-name = "clap-verbosity-flag"
-version = "3.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2678fade3b77aa3a8ff3aae87e9c008d3fb00473a41c71fbf74e91c8c7b37e84"
-dependencies = [
- "clap",
- "log",
-]
-
 [[package]]
 name = "clap_builder"
 version = "4.5.31"
@@ -4305,7 +4295,6 @@ dependencies = [
  "base64 0.22.1",
  "chrono",
  "clap",
- "clap-verbosity-flag",
  "clap_complete",
  "clap_complete_nushell",
  "console",
diff --git a/Cargo.toml b/Cargo.toml
index 410623bb4..2b7d37ebc 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -24,7 +24,6 @@ base64 = "0.22.1"
 bytes = "1.10.0"
 chrono = "0.4.40"
 clap = { version = "4.5.31", default-features = false }
-clap-verbosity-flag = "3.0.2"
 clap_complete = "4.5.46"
 clap_complete_nushell = "4.5.5"
 concat-idents = "1.1.5"
@@ -226,7 +225,6 @@ clap = { workspace = true, features = [
   "error-context",
   "env",
 ] }
-clap-verbosity-flag = { workspace = true }
 clap_complete = { workspace = true }
 clap_complete_nushell = { workspace = true }
 console = { workspace = true, features = ["windows-console-colors"] }
diff --git a/crates/pixi_config/src/lib.rs b/crates/pixi_config/src/lib.rs
index aca2be9a3..55b012b1d 100644
--- a/crates/pixi_config/src/lib.rs
+++ b/crates/pixi_config/src/lib.rs
@@ -95,30 +95,30 @@ pub fn get_cache_dir() -> miette::Result<PathBuf> {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct ConfigCli {
     /// Do not verify the TLS certificate of the server.
-    #[arg(long, action = ArgAction::SetTrue)]
+    #[arg(long, action = ArgAction::SetTrue, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     tls_no_verify: bool,
 
     /// Path to the file containing the authentication token.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     auth_file: Option<PathBuf>,
 
     /// Specifies whether to use the keyring to look up credentials for PyPI.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pypi_keyring_provider: Option<KeyringProvider>,
 
     /// Max concurrent solves, default is the number of CPUs
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pub concurrent_solves: Option<usize>,
 
     /// Max concurrent network requests, default is `50`
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pub concurrent_downloads: Option<usize>,
 }
 
 #[derive(Parser, Debug, Clone, Default)]
 pub struct ConfigCliPrompt {
     /// Do not change the PS1 variable when starting a prompt.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     change_ps1: Option<bool>,
 }
 
@@ -183,11 +183,11 @@ impl RepodataConfig {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct ConfigCliActivation {
     /// Do not use the environment activation cache. (default: true except in experimental mode)
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     force_activate: bool,
 
     /// Do not source the autocompletion scripts from the environment.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     no_completion: Option<bool>,
 }
 
diff --git a/crates/pixi_consts/src/consts.rs b/crates/pixi_consts/src/consts.rs
index 122638a32..9393a3de9 100644
--- a/crates/pixi_consts/src/consts.rs
+++ b/crates/pixi_consts/src/consts.rs
@@ -83,6 +83,9 @@ pub const ONE_TIME_MESSAGES_DIR: &str = "one-time-messages";
 pub const ENVIRONMENT_FILE_NAME: &str = "pixi";
 
 pub const RELEASES_URL: &str = "https://github.com/prefix-dev/pixi/releases";
+pub const CLAP_GLOBAL_OPTIONS: &str = "Global Options";
+pub const CLAP_CONFIG_OPTIONS: &str = "Config Options";
+pub const CLAP_GIT_OPTIONS: &str = "Git Options";
 
 pub static TASK_STYLE: LazyLock<Style> = LazyLock::new(|| Style::new().blue());
 pub static PLATFORM_STYLE: LazyLock<Style> = LazyLock::new(|| Style::new().yellow());
diff --git a/docs/reference/cli/pixi.md b/docs/reference/cli/pixi.md
index 9db5ae70d..bc99bb870 100644
--- a/docs/reference/cli/pixi.md
+++ b/docs/reference/cli/pixi.md
@@ -48,13 +48,15 @@ pixi [OPTIONS] <COMMAND>
 <br>**env**: `PIXI_COLOR`
 <br>**default**: `auto`
 <br>**options**: `always`, `never`, `auto`
+- <a id="arg---help" href="#arg---help">`--help (-h)`</a>
+:  Display help information
 - <a id="arg---no-progress" href="#arg---no-progress">`--no-progress`</a>
 :  Hide all progress bars, always turned on if stderr is not a terminal
 <br>**env**: `PIXI_NO_PROGRESS`
 <br>**default**: `false`
 - <a id="arg---quiet" href="#arg---quiet">`--quiet (-q)`</a>
-:  Decrease logging verbosity
+:  Decrease logging verbosity (quiet mode)
 - <a id="arg---verbose" href="#arg---verbose">`--verbose (-v)`</a>
-:  Increase logging verbosity
+:  Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace)
 
 --8<-- "docs/reference/cli/pixi_extender.md:example"
diff --git a/docs/reference/cli/pixi/add.md b/docs/reference/cli/pixi/add.md
index e7718c446..df72ea81e 100644
--- a/docs/reference/cli/pixi/add.md
+++ b/docs/reference/cli/pixi/add.md
@@ -21,8 +21,6 @@ pixi add [OPTIONS] <SPECS>...
 :  Path to the file containing the authentication token
 - <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
 :  The git branch
-- <a id="arg---build" href="#arg---build">`--build`</a>
-:  The specified dependencies are build dependencies. Conflicts with `host` and `pypi`
 - <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
 :  Max concurrent network requests, default is `50`
 - <a id="arg---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
@@ -37,8 +35,6 @@ pixi add [OPTIONS] <SPECS>...
 <br>**env**: `PIXI_FROZEN`
 - <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
 :  The git url to use when adding a git dependency
-- <a id="arg---host" href="#arg---host">`--host`</a>
-:  The specified dependencies are host dependencies. Conflicts with `build` and `pypi`
 - <a id="arg---locked" href="#arg---locked">`--locked`</a>
 :  Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file
 <br>**env**: `PIXI_LOCKED`
diff --git a/docs/reference/cli/pixi/remove.md b/docs/reference/cli/pixi/remove.md
index 563df6723..af1cfbcbb 100644
--- a/docs/reference/cli/pixi/remove.md
+++ b/docs/reference/cli/pixi/remove.md
@@ -21,8 +21,6 @@ pixi remove [OPTIONS] <SPECS>...
 :  Path to the file containing the authentication token
 - <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
 :  The git branch
-- <a id="arg---build" href="#arg---build">`--build`</a>
-:  The specified dependencies are build dependencies. Conflicts with `host` and `pypi`
 - <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
 :  Max concurrent network requests, default is `50`
 - <a id="arg---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
@@ -35,8 +33,6 @@ pixi remove [OPTIONS] <SPECS>...
 <br>**env**: `PIXI_FROZEN`
 - <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
 :  The git url to use when adding a git dependency
-- <a id="arg---host" href="#arg---host">`--host`</a>
-:  The specified dependencies are host dependencies. Conflicts with `build` and `pypi`
 - <a id="arg---locked" href="#arg---locked">`--locked`</a>
 :  Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file
 <br>**env**: `PIXI_LOCKED`
diff --git a/pixi_docs/Cargo.lock b/pixi_docs/Cargo.lock
index 1d759b9dd..8998cb5f5 100644
--- a/pixi_docs/Cargo.lock
+++ b/pixi_docs/Cargo.lock
@@ -1178,16 +1178,6 @@ dependencies = [
  "clap_derive",
 ]
 
-[[package]]
-name = "clap-verbosity-flag"
-version = "3.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2678fade3b77aa3a8ff3aae87e9c008d3fb00473a41c71fbf74e91c8c7b37e84"
-dependencies = [
- "clap",
- "log",
-]
-
 [[package]]
 name = "clap_builder"
 version = "4.5.31"
@@ -4160,7 +4150,6 @@ dependencies = [
  "base64 0.22.1",
  "chrono",
  "clap",
- "clap-verbosity-flag",
  "clap_complete",
  "clap_complete_nushell",
  "console",
diff --git a/src/cli/cli_config.rs b/src/cli/cli_config.rs
index 80ffcaa1c..301c3c84e 100644
--- a/src/cli/cli_config.rs
+++ b/src/cli/cli_config.rs
@@ -28,7 +28,7 @@ use pixi_git::GIT_URL_QUERY_REV_TYPE;
 #[derive(Parser, Debug, Default, Clone)]
 pub struct WorkspaceConfig {
     /// The path to `pixi.toml`, `pyproject.toml`, or the workspace directory
-    #[arg(long, global = true)]
+    #[arg(long, global = true, help_heading = consts::CLAP_GLOBAL_OPTIONS)]
     pub manifest_path: Option<PathBuf>,
 }
 
@@ -151,15 +151,15 @@ impl PrefixUpdateConfig {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct GitRev {
     /// The git branch
-    #[clap(long, requires = "git", conflicts_with_all = ["tag", "rev"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["tag", "rev"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub branch: Option<String>,
 
     /// The git tag
-    #[clap(long, requires = "git", conflicts_with_all = ["branch", "rev"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["branch", "rev"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub tag: Option<String>,
 
     /// The git revision
-    #[clap(long, requires = "git", conflicts_with_all = ["branch", "tag"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["branch", "tag"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub rev: Option<String>,
 }
 
@@ -236,12 +236,12 @@ pub struct DependencyConfig {
 
     /// The specified dependencies are host dependencies. Conflicts with `build`
     /// and `pypi`
-    #[arg(long, conflicts_with_all = ["build", "pypi"])]
+    #[arg(long, conflicts_with_all = ["build", "pypi"], hide = true)]
     pub host: bool,
 
     /// The specified dependencies are build dependencies. Conflicts with `host`
     /// and `pypi`
-    #[arg(long, conflicts_with_all = ["host", "pypi"])]
+    #[arg(long, conflicts_with_all = ["host", "pypi"], hide = true)]
     pub build: bool,
 
     /// The specified dependencies are pypi dependencies. Conflicts with `host`
@@ -258,7 +258,7 @@ pub struct DependencyConfig {
     pub feature: FeatureName,
 
     /// The git url to use when adding a git dependency
-    #[clap(long, short)]
+    #[clap(long, short, help_heading = consts::CLAP_GIT_OPTIONS)]
     pub git: Option<Url>,
 
     #[clap(flatten)]
@@ -266,7 +266,7 @@ pub struct DependencyConfig {
     pub rev: Option<GitRev>,
 
     /// The subdirectory of the git repository to use
-    #[clap(long, short, requires = "git")]
+    #[clap(long, short, requires = "git", help_heading = consts::CLAP_GIT_OPTIONS)]
     pub subdir: Option<String>,
 }
 
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 62f05ff8b..f5950c002 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -45,15 +45,15 @@ enum Subcommand {
 #[derive(Parser, Debug, Clone)]
 struct CommonArgs {
     /// Operation on project-local configuration
-    #[arg(long, short, conflicts_with_all = &["global", "system"])]
+    #[arg(long, short, conflicts_with_all = &["global", "system"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     local: bool,
 
     /// Operation on global configuration
-    #[arg(long, short, conflicts_with_all = &["local", "system"])]
+    #[arg(long, short, conflicts_with_all = &["local", "system"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     global: bool,
 
     /// Operation on system configuration
-    #[arg(long, short, conflicts_with_all = &["local", "global"])]
+    #[arg(long, short, conflicts_with_all = &["local", "global"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     system: bool,
 
     #[clap(flatten)]
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 118c4e287..f63bc8147 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1,5 +1,5 @@
+use clap::builder::styling::{AnsiColor, Color, Style};
 use clap::Parser;
-use clap_verbosity_flag::Verbosity;
 use indicatif::ProgressDrawTarget;
 use miette::IntoDiagnostic;
 use pixi_consts::consts;
@@ -63,17 +63,31 @@ Need Help?
 Ask a question on the Prefix Discord server: https://discord.gg/kKV8ZxyzY4
 
 For more information, see the documentation at: https://pixi.sh
-", consts::PIXI_VERSION)
+", consts::PIXI_VERSION),
 )]
-#[clap(arg_required_else_help = true)]
+#[clap(arg_required_else_help = true, styles=get_styles(), disable_help_flag = true)]
 pub struct Args {
     #[command(subcommand)]
     command: Command,
 
-    /// The verbosity level
-    /// (-v for warning, -vv for info, -vvv for debug, -vvvv for trace, -q for quiet)
-    #[command(flatten)]
-    verbose: Verbosity,
+    #[clap(flatten)]
+    global_options: GlobalOptions,
+}
+
+#[derive(Debug, Parser)]
+#[clap(next_help_heading = consts::CLAP_GLOBAL_OPTIONS)]
+pub struct GlobalOptions {
+    /// Display help information
+    #[clap(long, short, global = true, action = clap::ArgAction::Help)]
+    help: Option<bool>,
+
+    /// Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace)
+    #[clap(short, long, action = clap::ArgAction::Count, global = true)]
+    verbose: u8,
+
+    /// Decrease logging verbosity (quiet mode)
+    #[clap(short, long, action = clap::ArgAction::Count, global = true)]
+    quiet: u8,
 
     /// Whether the log needs to be colored.
     #[clap(long, default_value = "auto", global = true, env = "PIXI_COLOR")]
@@ -83,13 +97,28 @@ pub struct Args {
     #[clap(long, default_value = "false", global = true, env = "PIXI_NO_PROGRESS")]
     no_progress: bool,
 }
+
 impl Args {
     /// Whether to show progress bars or not, based on the terminal and the user's preference.
     fn no_progress(&self) -> bool {
         if !std::io::stderr().is_terminal() {
             true
         } else {
-            self.no_progress
+            self.global_options.no_progress
+        }
+    }
+
+    /// Determine the log level filter based on verbose and quiet counts.
+    fn log_level_filter(&self) -> LevelFilter {
+        match (self.global_options.quiet, self.global_options.verbose) {
+            // Quiet mode overrides verbose
+            (q, _) if q > 0 => LevelFilter::OFF,
+            // Custom verbosity levels
+            (_, 0) => LevelFilter::ERROR, // Default
+            (_, 1) => LevelFilter::WARN,  // -v
+            (_, 2) => LevelFilter::INFO,  // -vv
+            (_, 3) => LevelFilter::DEBUG, // -vvv
+            (_, _) => LevelFilter::TRACE, // -vvvv+
         }
     }
 }
@@ -190,25 +219,13 @@ pub async fn execute() -> miette::Result<()> {
         global_multi_progress().set_draw_target(ProgressDrawTarget::hidden());
     }
 
-    let (low_level_filter, level_filter, pixi_level) = match args.verbose.log_level_filter() {
-        clap_verbosity_flag::log::LevelFilter::Off => {
-            (LevelFilter::OFF, LevelFilter::OFF, LevelFilter::OFF)
-        }
-        clap_verbosity_flag::log::LevelFilter::Error => {
-            (LevelFilter::ERROR, LevelFilter::ERROR, LevelFilter::WARN)
-        }
-        clap_verbosity_flag::log::LevelFilter::Warn => {
-            (LevelFilter::WARN, LevelFilter::WARN, LevelFilter::INFO)
-        }
-        clap_verbosity_flag::log::LevelFilter::Info => {
-            (LevelFilter::WARN, LevelFilter::INFO, LevelFilter::INFO)
-        }
-        clap_verbosity_flag::log::LevelFilter::Debug => {
-            (LevelFilter::INFO, LevelFilter::DEBUG, LevelFilter::DEBUG)
-        }
-        clap_verbosity_flag::log::LevelFilter::Trace => {
-            (LevelFilter::TRACE, LevelFilter::TRACE, LevelFilter::TRACE)
-        }
+    let (low_level_filter, level_filter, pixi_level) = match args.log_level_filter() {
+        LevelFilter::OFF => (LevelFilter::OFF, LevelFilter::OFF, LevelFilter::OFF),
+        LevelFilter::ERROR => (LevelFilter::ERROR, LevelFilter::ERROR, LevelFilter::WARN),
+        LevelFilter::WARN => (LevelFilter::WARN, LevelFilter::WARN, LevelFilter::INFO),
+        LevelFilter::INFO => (LevelFilter::WARN, LevelFilter::INFO, LevelFilter::INFO),
+        LevelFilter::DEBUG => (LevelFilter::INFO, LevelFilter::DEBUG, LevelFilter::DEBUG),
+        LevelFilter::TRACE => (LevelFilter::TRACE, LevelFilter::TRACE, LevelFilter::TRACE),
     };
 
     let env_filter = EnvFilter::builder()
@@ -293,7 +310,7 @@ fn set_console_colors(args: &Args) {
         Ok(_) => &ColorOutput::Always,
         Err(_) => match env::var("NO_COLOR") {
             Ok(_) => &ColorOutput::Never,
-            Err(_) => &args.color,
+            Err(_) => &args.global_options.color,
         },
     };
 
@@ -309,3 +326,37 @@ fn set_console_colors(args: &Args) {
         ColorOutput::Auto => {} // Let `console` detect if colors should be enabled
     };
 }
+
+pub fn get_styles() -> clap::builder::Styles {
+    clap::builder::Styles::styled()
+        .usage(
+            Style::new()
+                .bold()
+                .underline()
+                .fg_color(Some(Color::Ansi(AnsiColor::BrightGreen))),
+        )
+        .header(
+            Style::new()
+                .bold()
+                .underline()
+                .fg_color(Some(Color::Ansi(AnsiColor::BrightGreen))),
+        )
+        .literal(Style::new().fg_color(Some(Color::Ansi(AnsiColor::BrightCyan))))
+        .invalid(
+            Style::new()
+                .bold()
+                .fg_color(Some(Color::Ansi(AnsiColor::Red))),
+        )
+        .error(
+            Style::new()
+                .bold()
+                .fg_color(Some(Color::Ansi(AnsiColor::Red))),
+        )
+        .valid(
+            Style::new()
+                .bold()
+                .underline()
+                .fg_color(Some(Color::Ansi(AnsiColor::Green))),
+        )
+        .placeholder(Style::new().fg_color(Some(Color::Ansi(AnsiColor::BrightCyan))))
+}