Git-like Subcommands with clap

20 min read

Many serious command-line tools are not a single command but a family of commands sharing one binary: git commit, git remote add, cargo build, docker container ls. In Rust, clap’s #[derive(Subcommand)] turns a plain enum into exactly this kind of dispatch tree — with help, validation, and nesting generated for you.

Quick Overview

A subcommand is a verb that selects one branch of your program (add, commit, remote). With clap’s derive API you model each verb as a variant of an enum, attach #[derive(Subcommand)], and embed that enum in your top-level #[derive(Parser)] struct. clap then parses mytool <verb> <args…>, generates per-command --help, and lets you match on a strongly-typed value — no string switching, no manual process.argv slicing.

For a TypeScript/JavaScript developer this is the same job that commander’s program.command("add") or yargs’s .command() does, but the result is an exhaustive enum the compiler forces you to handle completely.

Note: This page assumes you already know clap’s derive basics. If #[derive(Parser)], #[arg(...)], and default values are new to you, read clap-derive.md first; for the lower-level builder API see clap-basics.md.

TypeScript/JavaScript Example

A typical Node CLI with commander defines each verb with a callback. Here is a small git-like tool with a nested remote command group:

1
// cli.mts — run with: node cli.mts <args>
2
// Requires: npm install commander
3
import { Command } from "commander";
4

5
const program = new Command();
6
program
7
  .name("rgit")
8
  .description("A tiny git-like CLI")
9
  .version("1.0.0");
10

11
program
12
  .command("init")
13
  .description("Create an empty repository")
14
  .argument("[path]", "where to create the repository", ".") // optional, default "."
15
  .action((path: string) => {
16
    console.log(`Initialized empty repository in ${path}`);
17
  });
18

19
program
20
  .command("add")
21
  .description("Add file contents to the staging area")
22
  .argument("<files...>", "files to stage") // 1 or more
23
  .option("-a, --all", "stage every tracked file")
24
  .action((files: string[], opts: { all?: boolean }) => {
25
    if (opts.all) console.log("Staging all tracked files");
26
    else console.log(`Staging ${files.length} file(s): ${files.join(", ")}`);
27
  });
28

29
// A nested command group: `rgit remote add <name> <url>`
30
const remote = program
31
  .command("remote")
32
  .description("Manage the set of tracked repositories");
33

34
remote
35
  .command("add")
36
  .argument("<name>")
37
  .argument("<url>")
38
  .action((name: string, url: string) => {
39
    console.log(`Added remote '${name}' -> ${url}`);
40
  });
41

42
program.parse();

Key points about the commander version:

Each command() registers a verb; action() receives positional arguments and a parsed-options object.
Argument syntax is encoded in strings: "<files...>" means “required, variadic”; "[path]" means “optional”.
The opts object is typed only because you wrote the { all?: boolean } annotation — commander itself returns any. A typo like opts.al compiles and silently reads undefined.
Nesting is done by calling .command() on a sub-Command instance.

Rust Equivalent

In clap, the verbs become an enum, each variant carrying its own typed arguments. The compiler — not a hand-written annotation — guarantees the types:

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3

4
/// A tiny git-like version control tool.
5
#[derive(Parser)]
6
#[command(name = "rgit", version, about = "A tiny git-like CLI")]
7
struct Cli {
8
    /// Enable verbose output across all commands
9
    #[arg(short, long, global = true)]
10
    verbose: bool,
11

12
    #[command(subcommand)]
13
    command: Commands,
14
}
15

16
#[derive(Subcommand)]
17
enum Commands {
18
    /// Create an empty repository
19
    Init {
20
        /// Where to create the repository
21
        #[arg(default_value = ".")]
22
        path: String,
23
    },
24
    /// Add file contents to the staging area
25
    Add {
26
        /// Files to stage
27
        #[arg(required = true)]
28
        files: Vec<String>,
29
        /// Stage every tracked file
30
        #[arg(short, long)]
31
        all: bool,
32
    },
33
    /// Record staged changes to the repository
34
    Commit {
35
        /// The commit message
36
        #[arg(short, long)]
37
        message: String,
38
    },
39
}
40

41
fn main() {
42
    let cli = Cli::parse();
43

44
    if cli.verbose {
45
        eprintln!("[verbose mode on]");
46
    }
47

48
    match cli.command {
49
        Commands::Init { path } => {
50
            println!("Initialized empty repository in {path}");
51
        }
52
        Commands::Add { files, all } => {
53
            if all {
54
                println!("Staging all tracked files");
55
            } else {
56
                println!("Staging {} file(s): {}", files.len(), files.join(", "));
57
            }
58
        }
59
        Commands::Commit { message } => {
60
            println!("Committed with message: {message}");
61
        }
62
    }
63
}

Running it (here the binary is named rgit; with cargo run you would write cargo run -- init myrepo):

1
$ rgit init myrepo
2
Initialized empty repository in myrepo
3

4
$ rgit add src/main.rs Cargo.toml
5
Staging 2 file(s): src/main.rs, Cargo.toml
6

7
$ rgit commit -m "first commit"
8
Committed with message: first commit

If you run it with no subcommand, clap prints the auto-generated help and exits with status 2:

1
$ rgit
2
A tiny git-like CLI
3

4
Usage: rgit [OPTIONS] <COMMAND>
5

6
Commands:
7
  init    Create an empty repository
8
  add     Add file contents to the staging area
9
  commit  Record staged changes to the repository
10
  help    Print this message or the help of the given subcommand(s)
11

12
Options:
13
  -v, --verbose  Enable verbose output across all commands
14
  -h, --help     Print help
15
  -V, --version  Print version

All of this output is generated by clap from the enum and its doc comments — you wrote zero help text by hand.

Detailed Explanation

The two derives work together

1
#[derive(Parser)]          // the top-level container
2
struct Cli {
3
    #[command(subcommand)] // "the chosen verb lives here"
4
    command: Commands,
5
}
6

7
#[derive(Subcommand)]      // marks an enum as a set of verbs
8
enum Commands { /* ... */ }

#[derive(Parser)] implements Cli::parse(), which reads std::env::args_os(), parses it, and on any error prints a message and exits.
#[command(subcommand)] on a field tells clap “the user picks exactly one variant of this enum, by name.” Each variant becomes a verb; its name is the lowercase/kebab-case version of the variant identifier (Commit → commit).
#[derive(Subcommand)] on the enum is what makes that legal. The two attributes are a pair: the field attribute references an enum that carries the enum derive.

Note: clap derives Subcommand and requires the enum to be Clone-able internally. If you forget #[command(subcommand)], clap instead tries to treat the field as a single positional value of type Commands, which fails to compile — see Common Pitfalls.

Variants carry their own arguments

Each variant is either a unit variant (Status) or a struct-like variant whose named fields become that verb’s arguments:

1
Commit {
2
    #[arg(short, long)]   // -m / --message
3
    message: String,      // required (not Option<_>) → clap demands it
4
},

The field-level rules are identical to a normal #[derive(Parser)] struct (covered in clap-derive.md):

A plain String/number field is a required positional or option.
Option<T> makes it optional; bool makes it a flag; Vec<T> makes it variadic.
#[arg(short, long)] turns a positional into a named option; #[arg(default_value = "…")] supplies a fallback.

Matching is exhaustive

1
match cli.command {
2
    Commands::Init { path } => { /* ... */ }
3
    Commands::Add { files, all } => { /* ... */ }
4
    Commands::Commit { message } => { /* ... */ }
5
}

Because command is an enum, the match must cover every variant. Add a new verb later and the compiler refuses to build until you handle it. In commander/yargs nothing reminds you that a new command needs wiring — a forgotten .action() is silently a no-op.

Global flags

1
#[arg(short, long, global = true)]
2
verbose: bool,

global = true means --verbose is accepted after any subcommand too — rgit add -a --verbose and rgit --verbose add -a both set it. Without global, the flag would only be valid before the verb. This mirrors how git --no-pager log vs git log behaves.

The program name vs. the binary name

#[command(name = "rgit")] sets the name used in --version output and as the program’s logical name. The name shown in usage strings, however, defaults to the actual file name of the running binary (argv[0]). Under cargo run that file is named after your package; once installed as rgit the usage line reads Usage: rgit …. To force a fixed display name regardless of how the binary is invoked, add #[command(bin_name = "rgit")].

Nested Subcommands

Real tools nest verbs: git remote add, docker image prune, cargo install. You nest by giving a variant its own #[command(subcommand)] field pointing at a second Subcommand enum:

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3

4
#[derive(Parser)]
5
#[command(name = "rgit", version, about = "A tiny git-like CLI")]
6
struct Cli {
7
    #[command(subcommand)]
8
    command: Commands,
9
}
10

11
#[derive(Subcommand)]
12
enum Commands {
13
    /// Manage the set of tracked repositories
14
    Remote {
15
        #[command(subcommand)]
16
        action: RemoteAction,
17
    },
18
    /// Show the working tree status
19
    Status,
20
}
21

22
#[derive(Subcommand)]
23
enum RemoteAction {
24
    /// Add a new remote
25
    Add {
26
        /// Short name for the remote, e.g. "origin"
27
        name: String,
28
        /// The remote URL
29
        url: String,
30
    },
31
    /// Remove an existing remote
32
    Remove {
33
        /// The remote to remove
34
        name: String,
35
    },
36
    /// List configured remotes
37
    List,
38
}
39

40
fn main() {
41
    let cli = Cli::parse();
42
    match cli.command {
43
        Commands::Status => println!("On branch main, nothing to commit"),
44
        Commands::Remote { action } => match action {
45
            RemoteAction::Add { name, url } => println!("Added remote '{name}' -> {url}"),
46
            RemoteAction::Remove { name } => println!("Removed remote '{name}'"),
47
            RemoteAction::List => println!("origin"),
48
        },
49
    }
50
}

1
$ rgit remote add origin https://example.com/repo.git
2
Added remote 'origin' -> https://example.com/repo.git
3

4
$ rgit remote list
5
origin

Each level gets its own help page automatically:

1
$ rgit remote --help
2
Manage the set of tracked repositories
3

4
Usage: rgit remote <COMMAND>
5

6
Commands:
7
  add     Add a new remote
8
  remove  Remove an existing remote
9
  list    List configured remotes
10
  help    Print this message or the help of the given subcommand(s)
11

12
Options:
13
  -h, --help  Print help

The nesting is just enums-within-enums, and the matching is just match-within-match. There is no depth limit; docker-style three-level trees (tool group sub action) compose the same way.

Key Differences

Concept	TypeScript (`commander`/`yargs`)	Rust (`clap` derive)
How a verb is declared	`program.command("add")` + `.action(cb)`	An `enum` variant `Add { … }`
Argument arity	Encoded in strings: `"<x>"`, `"[x]"`, `"<x...>"`	Encoded in the type: `String`, `Option<T>`, `Vec<T>`
Argument types	Strings by default; you cast/validate manually	Parsed into real types (`u16`, `PathBuf`, enums)
Dispatch	Each command has a callback closure	One value you `match` on
Forgetting to handle a command	Silent no-op at runtime	Compile error (non-exhaustive `match`)
Help / usage / version	Mostly automatic, some manual `.description()`	Fully automatic from doc comments + attributes
Nesting	`.command()` on a sub-`Command`	A nested `#[command(subcommand)]` enum
Unknown subcommand	You handle it (or it errors)	clap errors with exit code `2` by default

The deepest difference is where the contract lives. In commander, the shape of a command is data assembled at runtime; mistakes surface when a user runs the wrong path. In clap, the shape is the type system: an unhandled verb or a misread field is a build failure. For a TypeScript developer, think of it as the difference between validating with a hand-written if (typeof x === "string") and having a discriminated union the compiler checks for you — except clap also parses the input into that union.

Tip: The clap enum is a discriminated union, exactly like a TypeScript type Cmd = { kind: "add"; … } | { kind: "commit"; … }. The match is your exhaustive switch (cmd.kind), and Rust enforces the default-is-not-needed exhaustiveness that TypeScript only gives you with never tricks.

Common Pitfalls

Forgetting `#[command(subcommand)]`

If you embed the enum but omit the attribute, clap does not see “a set of verbs” — it tries to parse the field as one positional value, which the enum cannot satisfy. The error is about missing trait bounds, not a friendly “you forgot an attribute”:

1
// does not compile (error[E0277]/error[E0599])
2
use clap::{Parser, Subcommand};
3

4
#[derive(Parser)]
5
struct Cli {
6
    command: Commands, // missing #[command(subcommand)] !
7
}
8

9
#[derive(Subcommand)]
10
enum Commands {
11
    Status,
12
}
13

14
fn main() {
15
    let _ = Cli::parse();
16
}

Real compiler output:

1
error[E0277]: the trait bound `Commands: Clone` is not satisfied
2
 --> src/main.rs:6:14
3
  |
4
6 |     command: Commands,
5
  |              ^^^^^^^^ the trait `Clone` is not implemented for `Commands`
6
  |
7
note: required by a bound in `ArgMatches::remove_one`
8
help: consider annotating `Commands` with `#[derive(Clone)]`

The fix is to add the attribute — #[command(subcommand)] command: Commands — not to chase the Clone suggestion. The misleading hint is exactly why this trips up newcomers.

Making the subcommand optional by accident — or on purpose

A bare Commands field means a subcommand is required; run the tool with none and clap errors. Sometimes you want a default action (like cargo running cargo build-ish behavior, or a tool that prints status when invoked alone). Use Option<Commands>:

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3

4
#[derive(Parser)]
5
#[command(name = "rgit", version = "1.0.0", about = "A tiny git-like CLI")]
6
#[command(arg_required_else_help = true)]
7
struct Cli {
8
    #[command(subcommand)]
9
    command: Option<Commands>,
10
}
11

12
#[derive(Subcommand)]
13
enum Commands {
14
    /// Show the working tree status (the default action)
15
    Status,
16
    /// Record staged changes
17
    Commit {
18
        #[arg(short, long)]
19
        message: String,
20
    },
21
}
22

23
fn main() {
24
    let cli = Cli::parse();
25
    match cli.command {
26
        Some(Commands::Status) | None => println!("On branch main, working tree clean"),
27
        Some(Commands::Commit { message }) => println!("Committed: {message}"),
28
    }
29
}

Here None is treated the same as status. Note #[command(arg_required_else_help = true)]: with an Option subcommand, clap would otherwise accept “no arguments” silently; this attribute makes a bare invocation print help instead. Verified output:

1
$ rgit --version
2
rgit 1.0.0
3

4
$ rgit              # arg_required_else_help → prints help, exits 2
5
A tiny git-like CLI
6

7
Usage: rgit [COMMAND]
8

9
Commands:
10
  status  Show the working tree status (the default action)
11
  commit  Record staged changes
12
  help    Print this message or the help of the given subcommand(s)
13

14
Options:
15
  -h, --help     Print help
16
  -V, --version  Print version

Expecting `--version`/`--help` to print the `name`, not the binary name

As noted earlier, --version uses #[command(name = "rgit")] (it printed rgit 1.0.0 above), but the usage line uses the binary’s real argv[0]. Under cargo run you will see your package name in usage strings; that is not a bug. Set #[command(bin_name = "rgit")] if you need it pinned.

Required positional after an optional one

Within a single variant, the same ordering rules as any clap struct apply: a required positional cannot follow an optional/variadic one, or clap will reject the definition at parse-setup time. Keep Vec<T> and Option<T> positionals last. (See clap-derive.md for the full ordering rules.)

Verbose-flag placement

Without global = true, a top-level flag is only accepted before the subcommand. Users will naturally type rgit add file --verbose; if --verbose is not global, that errors with “unexpected argument.” Mark cross-cutting flags global = true.

Best Practices

One enum variant per verb; nest with sub-enums. Keep each Subcommand enum focused; deep trees read better as several small enums than one giant one.
Document with doc comments, not help =. clap turns /// Add a new remote into the command’s help text. This keeps the source self-documenting and the --help output in sync.
Put shared arguments in a #[derive(Args)] struct and embed it with #[command(flatten)], so several verbs can reuse the same option set without duplication (shown in the real-world example below).
Use Option<Commands> + arg_required_else_help = true when a no-subcommand invocation should show help rather than error opaquely.
Add visible_alias/alias for ergonomic shortcuts (rgit a for add) when it matches user expectations from the tool you are emulating.
Keep the match exhaustive and let the compiler guard new verbs — resist a catch-all _ => arm so adding a command forces you to wire it.
Validate values with types and value_enum, not hand-written checks: a Priority enum gives free [possible values: …] help and rejects bad input for you.

Real-World Example

A small project task runner, devctl, combining everything: a top-level verb (add) with a ValueEnum option, a nested config command group, a shared #[derive(Args)] struct flattened into one variant, and a visible_alias.

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Args, Parser, Subcommand, ValueEnum};
3

4
/// devctl — a project task runner.
5
#[derive(Parser)]
6
#[command(name = "devctl", version, about = "Manage project tasks and config")]
7
struct Cli {
8
    #[command(subcommand)]
9
    command: Commands,
10
}
11

12
#[derive(Subcommand)]
13
enum Commands {
14
    /// Add a new task
15
    #[command(visible_alias = "a")]
16
    Add {
17
        /// What needs doing
18
        title: String,
19
        /// Task priority
20
        #[arg(short, long, value_enum, default_value_t = Priority::Medium)]
21
        priority: Priority,
22
    },
23
    /// Operate on project configuration
24
    Config {
25
        #[command(subcommand)]
26
        action: ConfigAction,
27
    },
28
}
29

30
#[derive(Subcommand)]
31
enum ConfigAction {
32
    /// Read a config value
33
    Get { key: String },
34
    /// Write a config value
35
    Set(SetArgs), // a tuple variant holding a flattened Args struct
36
}
37

38
/// Reusable argument set for the `config set` command.
39
#[derive(Args)]
40
struct SetArgs {
41
    key: String,
42
    value: String,
43
    /// Apply to the global config instead of the project
44
    #[arg(long)]
45
    global: bool,
46
}
47

48
#[derive(Copy, Clone, PartialEq, Eq, Debug, ValueEnum)]
49
enum Priority {
50
    Low,
51
    Medium,
52
    High,
53
}
54

55
fn main() {
56
    let cli = Cli::parse();
57
    match cli.command {
58
        Commands::Add { title, priority } => {
59
            println!("Added task {title:?} with {priority:?} priority");
60
        }
61
        Commands::Config { action } => match action {
62
            ConfigAction::Get { key } => println!("config get {key}"),
63
            ConfigAction::Set(SetArgs { key, value, global }) => {
64
                let scope = if global { "global" } else { "project" };
65
                println!("config set {key}={value} ({scope})");
66
            }
67
        },
68
    }
69
}

Verified runs (with #[derive(Debug)] on Priority, clap’s default Debug prints the variant name like High):

1
$ devctl a "write the docs" --priority high     # 'a' is the alias for 'add'
2
Added task "write the docs" with High priority
3

4
$ devctl add "review PR"                          # uses default_value_t
5
Added task "review PR" with Medium priority
6

7
$ devctl config set editor vim --global
8
config set editor=vim (global)
9

10
$ devctl config get editor
11
config get editor

The ValueEnum gives the priority option self-validating help and rejects bad input automatically:

1
$ devctl add --help
2
Add a new task
3

4
Usage: devctl add [OPTIONS] <TITLE>
5

6
Arguments:
7
  <TITLE>  What needs doing
8

9
Options:
10
  -p, --priority <PRIORITY>  Task priority [default: medium] [possible values: low, medium, high]
11
  -h, --help                 Print help
12

13
$ devctl add x -p urgent
14
error: invalid value 'urgent' for '--priority <PRIORITY>'
15
  [possible values: low, medium, high]
16

17
For more information, try '--help'.

The tuple variant Set(SetArgs) shows the #[command(flatten)]-by-construction pattern: a #[derive(Args)] struct can be reused across multiple commands, and the variant simply holds it. You destructure it in the match arm exactly like any struct.

Tip: For tools that pair subcommands with progress feedback or colored status lines, combine this dispatch with progress-bars.md and colored-output.md. For reading the files a verb operates on, see file-io.md and path-handling.md.

Exercises

Exercise 1: Add a `log` subcommand

Difficulty: Beginner

Objective: Extend the first git-like CLI with a new verb and feel the exhaustiveness check.

Instructions: Starting from the Commands enum in the Rust Equivalent section, add a Log variant that takes an optional --max-count/-n numeric option (default 10). Build before adding the match arm and observe the compiler complaining about the missing case, then handle it by printing Showing up to N commits.

Solution

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3

4
#[derive(Parser)]
5
#[command(name = "rgit", version, about = "A tiny git-like CLI")]
6
struct Cli {
7
    #[command(subcommand)]
8
    command: Commands,
9
}
10

11
#[derive(Subcommand)]
12
enum Commands {
13
    /// Record staged changes
14
    Commit {
15
        #[arg(short, long)]
16
        message: String,
17
    },
18
    /// Show commit history
19
    Log {
20
        /// Limit the number of commits shown
21
        #[arg(short = 'n', long = "max-count", default_value_t = 10)]
22
        max_count: u32,
23
    },
24
}
25

26
fn main() {
27
    let cli = Cli::parse();
28
    match cli.command {
29
        Commands::Commit { message } => println!("Committed: {message}"),
30
        Commands::Log { max_count } => println!("Showing up to {max_count} commits"),
31
    }
32
}

Verified runs:

1
$ rgit log
2
Showing up to 10 commits
3

4
$ rgit log -n 3
5
Showing up to 3 commits

If you skip the Commands::Log arm, the build fails with error[E0004]: non-exhaustive patterns: Commands::Log { .. } not covered — the compiler will not let you forget the new verb.

Exercise 2: A nested key-value store with a missing-key exit code

Difficulty: Intermediate

Objective: Build a tool with set/get/keys verbs and return a non-zero exit status when a key is missing — the Rust equivalent of process.exit(1).

Instructions: Create a kv CLI with three subcommands: set <key> <value>, get <key>, and keys. Seed an in-memory HashMap with one entry. On get of a missing key, print an error to stderr and exit with status 1. (You will not persist between runs — that is fine for the exercise.)

Solution

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3
use std::collections::HashMap;
4

5
#[derive(Parser)]
6
#[command(name = "kv", version, about = "A toy key-value store CLI")]
7
struct Cli {
8
    #[command(subcommand)]
9
    command: Command,
10
}
11

12
#[derive(Subcommand)]
13
enum Command {
14
    /// Store a value under a key
15
    Set { key: String, value: String },
16
    /// Retrieve a value by key
17
    Get { key: String },
18
    /// List all keys
19
    Keys,
20
}
21

22
fn main() {
23
    // A real tool would persist this; we hard-code a store for the demo.
24
    let mut store: HashMap<String, String> = HashMap::new();
25
    store.insert("name".into(), "ada".into());
26

27
    let cli = Cli::parse();
28
    match cli.command {
29
        Command::Set { key, value } => {
30
            store.insert(key.clone(), value.clone());
31
            println!("set {key} = {value}");
32
        }
33
        Command::Get { key } => match store.get(&key) {
34
            Some(v) => println!("{v}"),
35
            None => {
36
                eprintln!("error: key {key:?} not found");
37
                std::process::exit(1);
38
            }
39
        },
40
        Command::Keys => {
41
            let mut keys: Vec<_> = store.keys().cloned().collect();
42
            keys.sort();
43
            for k in keys {
44
                println!("{k}");
45
            }
46
        }
47
    }
48
}

Verified runs:

1
$ kv get name
2
ada
3

4
$ kv get missing ; echo "exit=$?"
5
error: key "missing" not found
6
exit=1
7

8
$ kv keys
9
name

Exercise 3: External (plugin-style) subcommands

Difficulty: Advanced

Objective: Let unknown verbs be captured instead of rejected, so your tool can dispatch to tool-<name> plugins the way git calls git-<name> and cargo calls cargo-<name>.

Instructions: Define a CLI with one built-in hello command and a catch-all variant marked #[command(external_subcommand)] that captures the verb plus its remaining arguments as a Vec<OsString>. When an external subcommand is matched, print what you would dispatch to. (Actually std::process::Command::new-ing the plugin is optional bonus work.)

Solution

1
// Cargo.toml: clap = { version = "4", features = ["derive"] }
2
use clap::{Parser, Subcommand};
3
use std::ffi::OsString;
4

5
#[derive(Parser)]
6
#[command(name = "tool", version)]
7
struct Cli {
8
    #[command(subcommand)]
9
    command: Commands,
10
}
11

12
#[derive(Subcommand)]
13
enum Commands {
14
    /// A built-in command
15
    Hello,
16
    /// Anything else is forwarded to an external `tool-<name>` binary
17
    #[command(external_subcommand)]
18
    External(Vec<OsString>),
19
}
20

21
fn main() {
22
    let cli = Cli::parse();
23
    match cli.command {
24
        Commands::Hello => println!("hello from the built-in"),
25
        Commands::External(args) => {
26
            // args[0] is the unknown verb, the rest are its arguments.
27
            println!("would dispatch to tool-{:?}", args);
28
            // Bonus: actually run it, e.g.
29
            // let (verb, rest) = args.split_first().unwrap();
30
            // std::process::Command::new(format!("tool-{}", verb.to_string_lossy()))
31
            //     .args(rest).status().ok();
32
        }
33
    }
34
}

Verified runs:

1
$ tool hello
2
hello from the built-in
3

4
$ tool frobnicate --flag x
5
would dispatch to tool-["frobnicate", "--flag", "x"]

The external_subcommand variant must hold a Vec<OsString> (or Vec<String>); clap funnels the unrecognized verb and everything after it into that vector instead of erroring.

Git-like Subcommands with clap

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The two derives work together

Variants carry their own arguments

Matching is exhaustive

Global flags

The program name vs. the binary name

Nested Subcommands

Key Differences

Common Pitfalls

Forgetting #[command(subcommand)]

Making the subcommand optional by accident — or on purpose

Expecting --version/--help to print the name, not the binary name

Required positional after an optional one

Verbose-flag placement

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Add a log subcommand

Exercise 2: A nested key-value store with a missing-key exit code

Exercise 3: External (plugin-style) subcommands

Forgetting `#[command(subcommand)]`

Expecting `--version`/`--help` to print the `name`, not the binary name

Exercise 1: Add a `log` subcommand