norrietaylor · Jul 20, 2026 · Jul 20, 2026
@@ -28,7 +28,7 @@ pub struct DiagPaths {
     pub state: PathBuf,
     /// `<cache>/minimal`.
     pub cache: PathBuf,
-    /// Where `minimal mesh join` writes its enrolment file.
+    /// Where `min mesh join` writes its enrolment file.
     pub mesh_enrolment: PathBuf,
     /// The invoking directory (disk-full there breaks the bundle write).
     pub cwd: PathBuf,

@@ -53,7 +53,7 @@ struct DirsLookup {
     /// `<config>/minimal` — root for `config.toml`, `loadouts/`,
     /// mTLS certs.
     config: PathBuf,
-    /// The specific path `minimal mesh join` writes to. Kept separate
+    /// The specific path `min mesh join` writes to. Kept separate
     /// so a `--minimal-dir` override that redirects the mesh file
     /// (but not the loadouts subsystem) still shows up correctly.
     mesh_enrolment: PathBuf,

@@ -21,7 +21,9 @@ pub mod prompt;
 
 #[derive(Parser)]
 #[command(name = "min", version = version::VERSION, long_version = version::LONG_VERSION)]
-#[command(about = "The Minimal CLI")]
+#[command(
+    about = "min, the Minimal session CLI — create, attach to, and manage sandboxed development sessions"
+)]
 pub struct Cli {
     #[command(subcommand)]
     pub command: Command,
@@ -74,29 +76,30 @@ pub enum Command {
     /// Examples:
     ///
     ///   # Forward host port 18080 to the webserver inside the "dev" session:
-    ///   minimal ssh-forward dev 18080:127.0.0.1:80
+    ///   min ssh-forward dev 18080:127.0.0.1:80
     ///
     ///   # Then access it from the host:
     ///   curl http://localhost:18080/
     #[cfg(feature = "remote-access")]
     #[command(name = "ssh-forward", visible_alias = "forward")]
     SshForward(SshForwardArgs),
-    /// Obtain an mTLS client certificate from minimald for use with the HTTPS
-    /// reverse proxy (R4.4, R4.5).
+    /// Obtain an mTLS client certificate for the HTTPS reverse proxy
     ///
     /// Connects to minimald, generates a fresh client certificate signed by
-    /// the daemon's internal CA, and saves the certificate and private key to
-    /// `~/.config/minimal/client.pem` / `~/.config/minimal/client.key`. Also
-    /// saves the CA certificate to `~/.config/minimal/ca.pem` so tools like
-    /// `curl` can trust the HTTPS proxy.
+    /// the daemon's internal CA (R4.4, R4.5), and saves the certificate and
+    /// private key to `~/.config/minimal/client.pem` /
+    /// `~/.config/minimal/client.key`. Also saves the CA certificate to
+    /// `~/.config/minimal/ca.pem` so tools like `curl` can trust the HTTPS
+    /// proxy.
     ///
     /// Example:
     ///
-    ///   minimal login
+    ///   min login
     ///   curl --cacert ~/.config/minimal/ca.pem \
     ///        --cert ~/.config/minimal/client.pem \
     ///        --key  ~/.config/minimal/client.key \
     ///        https://localhost:7655/
+    #[command(verbatim_doc_comment)]
     Login(LoginArgs),
     /// Rename an existing session
     Rename(RenameArgs),
@@ -110,7 +113,7 @@ pub enum Command {
     Version,
     /// Generate shell completion script
     #[command(
-        long_about = "Generate a shell tab-completion script for the minimal CLI.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(min completions bash)"
+        long_about = "Generate a shell tab-completion script for the min CLI.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(min completions bash)"
     )]
     Completions(CompletionsArgs),
 }
@@ -175,17 +178,17 @@ pub enum MeshCommand {
     ///
     /// Example:
     ///
-    ///   minimal mesh join mesh.example.com:51820
+    ///   min mesh join mesh.example.com:51820
     #[command(verbatim_doc_comment)]
     Join(MeshJoinArgs),
     /// Leave the WireGuard mesh and drop this machine's local enrolment
     ///
-    /// Removes the local enrolment record written by `minimal mesh join`.
+    /// Removes the local enrolment record written by `min mesh join`.
     /// Peer entries on the remote minimald must be removed there (manual v1).
     ///
     /// Example:
     ///
-    ///   minimal mesh leave
+    ///   min mesh leave
     #[command(verbatim_doc_comment)]
     Leave,
     /// Show this minimald's mesh status: public key, advertised subnets, peers
@@ -195,7 +198,7 @@ pub enum MeshCommand {
     ///
     /// Example:
     ///
-    ///   minimal mesh status
+    ///   min mesh status
     #[command(verbatim_doc_comment)]
     Status,
 }
@@ -207,12 +210,16 @@ pub struct MeshJoinArgs {
     pub address: String,
 }
 
-/// Shared arguments all subcommands
-///
-/// The `Default` value is the no-flags invocation (no overrides, native
-/// backend) — what a bare `min <cmd>` resolves to, and what indirect
-/// entrypoints like the `git-remote-min` helper mode (which git invokes
-/// without any of our flags) use.
+// Shared arguments for all subcommands.
+//
+// The `Default` value is the no-flags invocation (no overrides, native
+// backend) — what a bare `min <cmd>` resolves to, and what indirect
+// entrypoints like the `git-remote-min` helper mode (which git invokes
+// without any of our flags) use.
+//
+// Deliberately NOT a doc comment: clap propagates a flattened struct's doc
+// comment into the parent command's long_about, which would replace the
+// top-level `min --help` description with this text.
 #[derive(Debug, Default, Args)]
 pub struct GlobalArgs {
     /// Use the given directory as the repository root, instead of the current
@@ -260,8 +267,8 @@ pub struct ActivateArgs {
     /// `[loadouts].default_loadouts` in the client config are ignored.
     #[arg(long = "loadout", value_name = "NAME")]
     pub loadout: Vec<String>,
-    /// Apply no loadouts at all — overrides both `--loadout` and the
-    /// config's `default_loadouts`.
+    /// Apply no loadouts at all (also skips the config's
+    /// `default_loadouts`). Conflicts with `--loadout`.
     #[arg(long, conflicts_with = "loadout")]
     pub no_loadouts: bool,
     /// Fail instead of prompting when the daemon returns items the
@@ -427,7 +434,7 @@ pub struct ProxyArgs {
     pub socket: Option<String>,
 }
 
-/// Arguments for `minimal ssh-forward`.
+/// Arguments for `min ssh-forward`.
 #[cfg(feature = "remote-access")]
 #[derive(Debug, Args)]
 pub struct SshForwardArgs {
@@ -441,7 +448,7 @@ pub struct SshForwardArgs {
     pub forward: String,
 }
 
-/// Arguments for `minimal login`.
+/// Arguments for `min login`.
 #[derive(Debug, Args)]
 pub struct LoginArgs {
     /// Override the directory where client cert files are written
@@ -911,7 +918,7 @@ fn offer_mfile_scaffold(
     if !std::io::stdin().is_terminal() || !confirm("Would you like to create one?", true)? {
         eprintln!(
             "Continuing without one; the session gets a default environment. \
-             Run 'minimal init' to give the project its own config."
+             Run 'min init' to give the project its own config."
         );
         return Ok(());
     }
@@ -1374,7 +1381,7 @@ pub fn cmd_mesh_join(global: &GlobalArgs, args: MeshJoinArgs) -> Result<(), anyh
     );
     println!();
     println!("v1 uses manual key exchange. To complete the join:");
-    println!("  1. Run `minimal mesh status` on the remote host to read its public key.");
+    println!("  1. Run `min mesh status` on the remote host to read its public key.");
     println!("  2. Add this machine's WireGuard public key to the remote minimald's peers.");
     println!("  3. Add the remote's public key and endpoint to this machine's mesh config.");
    Ok(())

@@ -1,4 +1,4 @@
-//! Interactive policy prompts for `minimal activate`.
+//! Interactive policy prompts for `min activate`.
 //!
 //! When the daemon returns a pending item (a Project or Package
 //! contribution the user's [`UserPolicy`] can't auto-decide), the

@@ -114,7 +114,7 @@ impl Cli {
 enum Command {
     /// Generate shell completion script
     #[command(
-        long_about = "Generate a shell tab-completion script for the minimal daemon.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(minimal completions bash)"
+        long_about = "Generate a shell tab-completion script for the minimal daemon.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(minimald completions bash)"
     )]
     Completions(CompletionsArgs),
     /// Runs the minimald server in the foreground.
@@ -187,13 +187,13 @@ pub struct ListenArgs {
 
     /// Daemonize: spawn minimald in a new session (setsid) and return once the
     /// SSH socket accepts connections, or an 8s timeout elapses. Used by the
-    /// `minimal` CLI to auto-start a native (DM2) daemon on Linux.
+    /// `min` CLI to auto-start a native daemon on Linux.
     #[arg(long, default_value_t = false)]
     detach: bool,
 
     /// Path to the gvproxy ("gvisor-tap-vsock") binary backing the per-host
     /// `OwnIp` switch. Defaults to the fixed system install path when unset;
-    /// point it at a local build to run own-IP (DM2) without a system install.
+    /// point it at a local build to run own-IP without a system install.
     #[arg(long)]
     gvproxy_bin: Option<std::path::PathBuf>,
 }

@@ -9,7 +9,17 @@ use crate::{Context, Error};
 
 #[derive(Debug, clap::Subcommand)]
 pub enum CacheArgs {
+    /// Remove stale entries from the local cache
+    ///
+    /// Deletes cached build artifacts whose last recorded use is older than
+    /// `--older-than`, or that have no recorded use at all. Packages needed
+    /// by the current project's tasks and stack are always kept. Also removes
+    /// sandbox, task, and temporary build directories whose owning process is
+    /// no longer running.
     Clean {
+        /// Only delete cache entries last used at least this long ago.
+        /// Takes a whole number of days, hours, or minutes: e.g. `30d`,
+        /// `12h`, `45m`
         #[arg(long, value_parser = parse_duration, default_value = "14d")]
         older_than: Duration,
     },

@@ -51,10 +51,10 @@ pub async fn cmd_init(args: InitArgs, config: Config) -> Result<(), Error> {
     eprintln!("Created {}", plan.toml_path.display());
     eprintln!();
     eprintln!("Next steps:");
-    eprintln!("  minimal update      # pin package versions");
-    eprintln!("  minimal run shell   # enter development shell");
+    eprintln!("  mip update      # pin package versions");
+    eprintln!("  mip run shell   # enter development shell");
     if plan.matched {
-        eprintln!("  minimal build       # build the project");
+        eprintln!("  mip build       # build the project");
     }
 
     Ok(())

@@ -87,8 +87,8 @@ impl clap::Args for RunArgs {
     fn augment_args(cmd: clap::Command) -> clap::Command {
         cmd.trailing_var_arg(true)
             .override_usage(
-                "minimal run [OPTIONS] <task_name> [task_args]...\n       \
-                 minimal run [OPTIONS] --upstream <upstream> --task-spec <task_spec> [task_args]...",
+                "mip run [OPTIONS] <task_name> [task_args]...\n       \
+                 mip run [OPTIONS] --upstream <upstream> --task-spec <task_spec> [task_args]...",
             )
             .arg(
                 clap::Arg::new("task_name")
@@ -148,7 +148,7 @@ pub async fn cmd_run(args: RunArgs, ctx: &mut Context) -> Result<(), Error> {
             let parsed_args = if !task.args.is_empty() {
                 Some(
                     task.args
-                        .parse_argv_named(&format!("minimal run {}", task_name), &args.task_args)
+                        .parse_argv_named(&format!("mip run {task_name}"), &args.task_args)
                         .map_err(|e| {
                             e.print().unwrap();
                             Error::Other(anyhow!(
@@ -169,7 +169,7 @@ pub async fn cmd_run(args: RunArgs, ctx: &mut Context) -> Result<(), Error> {
     }
 }
 
-/// Handles `minimal run --upstream ... --task-spec ...` without requiring a minimal.toml.
+/// Handles `mip run --upstream ... --task-spec ...` without requiring a minimal.toml.
 /// Called before Context::new in main, similar to how `cmd_init` is handled.
 pub async fn cmd_run_by_spec(
     mut upstream: mfile::LinkConfig,
@@ -222,7 +222,7 @@ pub async fn cmd_run_by_spec(
     let parsed_args = if !task.args.is_empty() {
         Some(
             task.args
-                .parse_argv_named("minimal run --task-spec ... ", &task_args)
+                .parse_argv_named("mip run --task-spec ... ", &task_args)
                 .map_err(|e| {
                     e.print().unwrap();
                     Error::Other(anyhow!("task called with invalid arguments",))

@@ -44,8 +44,8 @@ mod cmd_remote_build;
 use cmd_remote_build::{RemoteBuildArgs, cmd_remote_build};
 
 #[derive(Parser)]
-#[command(name = "minimal", version = version::VERSION, long_version = version::LONG_VERSION)]
-#[command(about = "The Minimal CLI")]
+#[command(name = "mip", version = version::VERSION, long_version = version::LONG_VERSION)]
+#[command(about = "mip, the Minimal package/build CLI")]
 struct Cli {
     #[command(subcommand)]
     command: Command,
@@ -67,11 +67,11 @@ enum Command {
     Init(InitArgs),
     /// Shows the status of Minimal in this codebase.
     Status(StatusArgs),
-    /// Launches a development shell. Shorthand for `minimal run shell`.
+    /// Launches a development shell. Shorthand for `mip run shell`.
     Shell,
-    /// Runs the build task. Shorthand for `minimal run build`.
+    /// Runs the build task. Shorthand for `mip run build`.
     Build,
-    /// Runs the test task. Shorthand for `minimal run test`.
+    /// Runs the test task. Shorthand for `mip run test`.
     Test,
     /// Materializes an output specified in `minimal.toml`.
     Materialize(MaterializeArgs),
@@ -104,13 +104,13 @@ enum Command {
     Dump(DumpArgs),
     /// Generates Graphviz source code of the dependency graph
     #[command(
-        long_about = "Generate an image of the dependency graph using graphviz's \"dot\" program.\n\n  minimal dep --input_deps_depth=0 -p file | dot -Tpng > deps.png"
+        long_about = "Generate an image of the dependency graph using graphviz's \"dot\" program.\n\n  mip dep --input-deps-depth=0 | dot -Tpng > deps.png"
     )]
     Dep(DepArgs),
 
     /// Generate shell completion script
     #[command(
-        long_about = "Generate a shell tab-completion script for the minimal CLI for your shell.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(minimal completions bash)"
+        long_about = "Generate a shell tab-completion script for the mip CLI for your shell.\nSupported shells include bash, zsh, elvish and fish.\n\n   source <(mip completions bash)"
     )]
     Completions(CompletionsArgs),
 }