From f7dd0086be4a27f5530755154f483514aafa24cd Mon Sep 17 00:00:00 2001
From: Ruben Arts <ruben.arts@hotmail.com>
Date: Tue, 21 May 2024 11:04:46 +0200
Subject: [PATCH] chore: cleanup and improve cli (#1402)

---
 src/cli/completion.rs  | 16 +++++++---
 src/cli/global/mod.rs  |  7 +++--
 src/cli/install.rs     |  1 +
 src/cli/list.rs        |  4 ++-
 src/cli/mod.rs         | 70 +++++++++++++++++++++++++++++-------------
 src/cli/run.rs         |  3 +-
 src/cli/search.rs      |  4 ++-
 src/cli/self_update.rs |  4 ++-
 src/cli/shell.rs       |  1 +
 src/cli/shell_hook.rs  |  4 ++-
 src/cli/task.rs        |  2 +-
 src/cli/upload.rs      |  8 ++++-
 tbump.toml             |  4 +++
 13 files changed, 93 insertions(+), 35 deletions(-)

diff --git a/src/cli/completion.rs b/src/cli/completion.rs
index dbdc27fc8..17e00673f 100644
--- a/src/cli/completion.rs
+++ b/src/cli/completion.rs
@@ -1,12 +1,20 @@
-use crate::cli::{Args, CompletionCommand};
-use clap::CommandFactory;
+use crate::cli::Args as CommandArgs;
+use clap::{CommandFactory, Parser};
 use miette::IntoDiagnostic;
 use regex::Regex;
 use std::borrow::Cow;
 use std::io::Write;
 
+/// Generates a completion script for a shell.
+#[derive(Parser, Debug)]
+pub struct Args {
+    /// The shell to generate a completion script for (defaults to 'bash').
+    #[arg(short, long)]
+    shell: Option<clap_complete::Shell>,
+}
+
 /// Generate completions for the pixi cli, and print those to the stdout
-pub(crate) fn execute(args: CompletionCommand) -> miette::Result<()> {
+pub(crate) fn execute(args: Args) -> miette::Result<()> {
     let clap_shell = args
         .shell
         .or(clap_complete::Shell::from_env())
@@ -33,7 +41,7 @@ pub(crate) fn execute(args: CompletionCommand) -> miette::Result<()> {
 /// Generate the completion script using clap_complete for a specified shell.
 fn get_completion_script(shell: clap_complete::Shell) -> String {
     let mut buf = vec![];
-    clap_complete::generate(shell, &mut Args::command(), "pixi", &mut buf);
+    clap_complete::generate(shell, &mut CommandArgs::command(), "pixi", &mut buf);
     String::from_utf8(buf).expect("clap_complete did not generate a valid UTF8 script")
 }
 
diff --git a/src/cli/global/mod.rs b/src/cli/global/mod.rs
index 2c7028ce2..ea25f654c 100644
--- a/src/cli/global/mod.rs
+++ b/src/cli/global/mod.rs
@@ -23,9 +23,12 @@ pub enum Command {
     UpgradeAll(upgrade_all::Args),
 }
 
-/// Global is the main entry point for the part of pixi that executes on the global(system) level.
+/// Subcommand for global package management actions
 ///
-/// It does not touch your system but in comparison to the normal pixi workflow which focuses on project level actions this will work on your system level.
+/// Install packages on the user level.
+/// Example:
+///    pixi global install my_package
+///    pixi global remove my_package
 #[derive(Debug, Parser)]
 pub struct Args {
     #[command(subcommand)]
diff --git a/src/cli/install.rs b/src/cli/install.rs
index 3210fb64c..6e5cc13e7 100644
--- a/src/cli/install.rs
+++ b/src/cli/install.rs
@@ -14,6 +14,7 @@ pub struct Args {
     #[clap(flatten)]
     pub lock_file_usage: super::LockFileUsageArgs,
 
+    /// The environment to install
     #[arg(long, short)]
     pub environment: Option<String>,
 
diff --git a/src/cli/list.rs b/src/cli/list.rs
index 50c86503e..0ddebe381 100644
--- a/src/cli/list.rs
+++ b/src/cli/list.rs
@@ -27,7 +27,9 @@ pub enum SortBy {
     Kind,
 }
 
-/// List project's packages. Highlighted packages are explicit dependencies.
+/// List project's packages.
+///
+/// Highlighted packages are explicit dependencies.
 #[derive(Debug, Parser)]
 #[clap(arg_required_else_help = false)]
 pub struct Args {
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 0f48ae3cb..c49048101 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -2,7 +2,6 @@ use super::util::IndicatifWriter;
 use crate::progress;
 use crate::progress::global_multi_progress;
 use clap::Parser;
-use clap_complete;
 use clap_verbosity_flag::Verbosity;
 use indicatif::ProgressDrawTarget;
 use miette::IntoDiagnostic;
@@ -31,7 +30,32 @@ pub mod tree;
 pub mod upload;
 
 #[derive(Parser, Debug)]
-#[command(version, about, long_about = None)]
+#[command(
+    version,
+    about = "
+Pixi [version 0.22.0] - Developer Workflow and Environment Management for Multi-Platform, Language-Agnostic Projects.
+
+Pixi is a versatile developer workflow tool designed to streamline the management of your project's dependencies, tasks, and environments.
+Built on top of the Conda ecosystem, Pixi offers seamless integration with the PyPI ecosystem.
+
+Basic Usage:
+    Initialize pixi for a project:
+    $ pixi init
+    $ pixi add python numpy pytest
+
+    Run a task:
+    $ pixi add task test 'pytest -s'
+    $ pixi run test
+
+Found a Bug or Have a Feature Request?
+Open an issue at: https://github.com/prefix-dev/pixi/issues
+
+Need Help?
+Ask a question on the Prefix Discord server: https://discord.gg/kKV8ZxyzY4
+
+For more information, see the documentation at: https://pixi.sh
+"
+)]
 #[clap(arg_required_else_help = true)]
 struct Args {
     #[command(subcommand)]
@@ -51,43 +75,45 @@ struct Args {
     no_progress: bool,
 }
 
-/// Generates a completion script for a shell.
-#[derive(Parser, Debug)]
-pub struct CompletionCommand {
-    /// The shell to generate a completion script for (defaults to 'bash').
-    #[arg(short, long)]
-    shell: Option<clap_complete::Shell>,
-}
-
 #[derive(Parser, Debug)]
 pub enum Command {
-    Completion(CompletionCommand),
-    Config(config::Args),
     Init(init::Args),
+
+    // Installation commands
     #[clap(visible_alias = "a")]
     Add(add::Args),
+    #[clap(visible_alias = "rm")]
+    Remove(remove::Args),
+    #[clap(visible_alias = "i")]
+    Install(install::Args),
+
+    // Execution commands
     #[clap(visible_alias = "r")]
     Run(run::Args),
     #[clap(visible_alias = "s")]
     Shell(shell::Args),
     ShellHook(shell_hook::Args),
+
+    // Project modification commands
+    Project(project::Args),
+    Task(task::Args),
+
+    // Environment inspection
+    #[clap(visible_alias = "ls")]
+    List(list::Args),
+    #[clap(visible_alias = "t")]
+    Tree(tree::Args),
+
+    // Global level commands
     #[clap(visible_alias = "g")]
     Global(global::Args),
     Auth(rattler::cli::auth::Args),
-    #[clap(visible_alias = "i")]
-    Install(install::Args),
-    Task(task::Args),
+    Config(config::Args),
     Info(info::Args),
     Upload(upload::Args),
     Search(search::Args),
-    Project(project::Args),
-    #[clap(visible_alias = "rm")]
-    Remove(remove::Args),
     SelfUpdate(self_update::Args),
-    #[clap(visible_alias = "ls")]
-    List(list::Args),
-    #[clap(visible_alias = "t")]
-    Tree(tree::Args),
+    Completion(completion::Args),
 }
 
 #[derive(Parser, Debug, Default, Copy, Clone)]
diff --git a/src/cli/run.rs b/src/cli/run.rs
index c309f39a1..718492379 100644
--- a/src/cli/run.rs
+++ b/src/cli/run.rs
@@ -33,7 +33,7 @@ use tracing::Level;
 #[derive(Parser, Debug, Default)]
 #[clap(trailing_var_arg = true, arg_required_else_help = true)]
 pub struct Args {
-    /// The pixi task or a deno task shell command you want to run in the project's environment, which can be an executable in the environment's PATH.
+    /// The pixi task or a task shell command you want to run in the project's environment, which can be an executable in the environment's PATH.
     #[arg(required = true)]
     pub task: Vec<String>,
 
@@ -44,6 +44,7 @@ pub struct Args {
     #[clap(flatten)]
     pub lock_file_usage: super::LockFileUsageArgs,
 
+    /// The environment to run the task in.
     #[arg(long, short)]
     pub environment: Option<String>,
 
diff --git a/src/cli/search.rs b/src/cli/search.rs
index 46ff7776b..5d7ede84f 100644
--- a/src/cli/search.rs
+++ b/src/cli/search.rs
@@ -19,7 +19,9 @@ use crate::utils::reqwest::build_reqwest_clients;
 use crate::HasFeatures;
 use crate::{progress::await_in_progress, repodata::fetch_sparse_repodata, Project};
 
-/// Search a package, output will list the latest version of package
+/// Search a conda package
+///
+/// Its output will list the latest version of package.
 #[derive(Debug, Parser)]
 #[clap(arg_required_else_help = true)]
 pub struct Args {
diff --git a/src/cli/self_update.rs b/src/cli/self_update.rs
index d5bf15ff0..edfc26ef5 100644
--- a/src/cli/self_update.rs
+++ b/src/cli/self_update.rs
@@ -10,7 +10,9 @@ use miette::{Context, IntoDiagnostic};
 use reqwest::Client;
 use serde::Deserialize;
 
-/// Update pixi to the latest version or a specific version. If the pixi binary is not found in the default location
+/// Update pixi to the latest version or a specific version.
+///
+/// If the pixi binary is not found in the default location
 /// (e.g. `~/.pixi/bin/pixi`), pixi won't updated to prevent breaking the current installation (Homebrew, etc).
 /// The behaviour can be overridden with the `--force` flag.
 #[derive(Debug, clap::Parser)]
diff --git a/src/cli/shell.rs b/src/cli/shell.rs
index ac4b4e81d..c975da1ce 100644
--- a/src/cli/shell.rs
+++ b/src/cli/shell.rs
@@ -27,6 +27,7 @@ pub struct Args {
     #[clap(flatten)]
     lock_file_usage: LockFileUsageArgs,
 
+    /// The environment to activate in the shell
     #[arg(long, short)]
     environment: Option<String>,
 
diff --git a/src/cli/shell_hook.rs b/src/cli/shell_hook.rs
index 899d40847..27667c385 100644
--- a/src/cli/shell_hook.rs
+++ b/src/cli/shell_hook.rs
@@ -18,7 +18,9 @@ use crate::{
     Project,
 };
 
-/// Print the activation script so users can source it in their shell, without needing the pixi executable.
+/// Print the pixi environment activation script.
+///
+/// You can source the script to activate the environment without needing pixi itself.
 #[derive(Parser, Debug)]
 pub struct Args {
     /// Sets the shell, options: [`bash`,  `zsh`,  `xonsh`,  `cmd`,  `powershell`,  `fish`,  `nushell`]
diff --git a/src/cli/task.rs b/src/cli/task.rs
index 9fc438bc8..b3828d062 100644
--- a/src/cli/task.rs
+++ b/src/cli/task.rs
@@ -169,7 +169,7 @@ impl From<AliasArgs> for Task {
     }
 }
 
-/// Command management in project
+/// Interact with tasks in the project
 #[derive(Parser, Debug)]
 #[clap(trailing_var_arg = true, arg_required_else_help = true)]
 pub struct Args {
diff --git a/src/cli/upload.rs b/src/cli/upload.rs
index ba0429ab4..901e0fb6d 100644
--- a/src/cli/upload.rs
+++ b/src/cli/upload.rs
@@ -14,7 +14,13 @@ use tokio_util::io::ReaderStream;
 
 use crate::progress;
 
-/// Upload a package to a prefix.dev channel
+/// Upload a conda package
+///
+/// With this command, you can upload a conda package to a channel.
+/// Example:
+///     pixi upload repo.prefix.dev/my_channel my_package.conda
+///
+/// Use `pixi auth login` to authenticate with the server.
 #[derive(Parser, Debug)]
 pub struct Args {
     /// The host + channel to upload to
diff --git a/tbump.toml b/tbump.toml
index 34b686a4c..cdf25029e 100644
--- a/tbump.toml
+++ b/tbump.toml
@@ -55,6 +55,10 @@ search = "Version: v{current_version}"
 src = "install/install.ps1"
 search = "Version: v{current_version}"
 
+[[file]]
+src = "src/cli/mod.rs"
+search = "version {current_version}"
+
 [[field]]
 # the name of the field
 name = "candidate"