Parsing Arguments with the clap Derive API

18 min read

In Node, you reach for commander or yargs and wire up options with a chain of method calls. In Rust, the idiomatic way to build a command-line interface is clap’s derive API: you describe your arguments as fields on a struct, slap #[derive(Parser)] on it, and the macro generates the parser, the --help text, the validation, and the error messages for you.

Quick Overview

clap is the de-facto standard argument parser in the Rust ecosystem. Its derive API lets you define your CLI as a plain struct whose fields are the arguments — the compiler turns that struct into a fully-featured parser at build time. For a TypeScript/JavaScript developer, this feels like declaring your options with a schema (think zod for process.argv): the struct is the single source of truth for parsing, type conversion, defaults, validation, and the generated help screen.

Note: This page focuses on the derive approach, which is what you should reach for in almost all new code. The sibling page clap-basics.md covers the lower-level builder API (Command::new(...).arg(...)), and subcommands.md covers git-style subcommands with #[derive(Subcommand)].

TypeScript/JavaScript Example

A typical small CLI built with commander (the most popular Node argument parser) looks like this:

1
// cli.ts — run with: npx tsx cli.ts app.log -p ERROR -vv --format json
2
import { Command, Option } from "commander";
3

4
const program = new Command();
5

6
program
7
  .name("loganalyze")
8
  .description("A fast log file analyzer.")
9
  .version("1.2.0")
10
  .argument("<path>", "path to the log file to analyze")
11
  .option("-p, --pattern <pattern>", "filter to lines containing this pattern")
12
  .option("-c, --context <n>", "number of lines of context to show", "3")
13
  .option("-v, --verbose", "increase logging verbosity", (_, prev: number) => prev + 1, 0)
14
  .option("--case-sensitive", "treat the pattern as case-sensitive", false)
15
  .addOption(
16
    new Option("--format <format>", "output format")
17
      .choices(["text", "json", "csv"])
18
      .default("text"),
19
  )
20
  .option("-i, --ignore <file...>", "files to ignore (repeatable)", []);
21

22
program.parse();
23

24
const path = program.args[0];
25
const opts = program.opts();
26

27
// Everything coming back is `any` / `string` — note `context` is the STRING "3":
28
console.log({ path, ...opts });

Key points:

The CLI shape lives in a chain of runtime method calls.
Types are weak: opts.context is the string "3", not a number, unless you pass a custom coercion function. program.opts() returns OptionValues, effectively Record<string, any>.
--help and --version are generated for you, which is the part clap also automates.
Validation (e.g. “this must be a number ≥ 1024”) is on you to write by hand.

Rust Equivalent

The same CLI with clap’s derive API. First add the dependency (the derive feature is not on by default):

1
[dependencies]
2
clap = { version = "4", features = ["derive"] }

Or from the shell — cargo add has been built into Cargo since 1.62, so no extra tooling is needed:

1
cargo add clap --features derive

The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects it automatically. The latest clap at the time of writing is 4.6.

1
use std::path::PathBuf;
2
use clap::Parser;
3

4
/// A fast log file analyzer.
5
#[derive(Parser, Debug)]
6
#[command(name = "loganalyze")]
7
#[command(version, about, long_about = None)]
8
struct Cli {
9
    /// Path to the log file to analyze
10
    path: PathBuf,
11

12
    /// Filter to lines containing this pattern
13
    #[arg(short, long)]
14
    pattern: Option<String>,
15

16
    /// Number of lines of context to show
17
    #[arg(short, long, default_value_t = 3)]
18
    context: usize,
19

20
    /// Increase logging verbosity (-v, -vv, -vvv)
21
    #[arg(short, long, action = clap::ArgAction::Count)]
22
    verbose: u8,
23

24
    /// Treat the pattern as case-sensitive
25
    #[arg(long)]
26
    case_sensitive: bool,
27

28
    /// Output format
29
    #[arg(long, value_enum, default_value_t = Format::Text)]
30
    format: Format,
31

32
    /// Files to ignore (repeatable)
33
    #[arg(short, long)]
34
    ignore: Vec<String>,
35
}
36

37
#[derive(clap::ValueEnum, Clone, Debug)]
38
enum Format {
39
    Text,
40
    Json,
41
    Csv,
42
}
43

44
fn main() {
45
    let cli = Cli::parse();
46
    println!("{cli:#?}");
47
}

Running loganalyze app.log -p ERROR -vv --format json -i a.log -i b.log prints the fully-typed, validated struct (real output):

1
Cli {
2
    path: "app.log",
3
    pattern: Some(
4
        "ERROR",
5
    ),
6
    context: 3,
7
    verbose: 2,
8
    case_sensitive: false,
9
    format: Json,
10
    ignore: [
11
        "a.log",
12
        "b.log",
13
    ],
14
}

Key points:

The struct is the CLI specification. Each field becomes an argument; the field’s type decides parsing and validation.
context is a real usize (not a string), format is a real enum variant, verbose is a u8 count — all checked at parse time.
The doc comments (/// ...) become the help text. There is no separate help-string registry to keep in sync.

Detailed Explanation

The field type drives everything

The single most important idea: in the derive API, the Rust type of the field controls how an argument is parsed, whether it’s required, and how it’s validated. There is no separate “type” parameter as in yargs.

Field type	clap behavior
`String`, `PathBuf`, `u16`, `usize`, …	Required positional or option; the string is parsed into that type.
`Option<T>`	Optional; absent → `None`, present → `Some(parsed_value)`.
`bool`	A flag; present → `true`, absent → `false`.
`Vec<T>`	Repeatable; each occurrence appends one `T`.
`T` with `default_value_t`	Optional with a fallback value.

Compare this to commander, where everything arrives as a string (or true for a bare flag) and you coerce it yourself.

Container attributes vs. field attributes

There are two attribute namespaces:

#[command(...)] configures the whole command (the struct). Common keys: name, version, about, long_about, author.
#[arg(...)] configures a single argument (a field). Common keys: short, long, default_value, default_value_t, value_enum, value_parser, action, env, value_name, required, num_args.

1
#[derive(Parser, Debug)]
2
#[command(name = "loganalyze")]            // container attribute
3
#[command(version, about, long_about = None)]
4
struct Cli {
5
    #[arg(short, long, default_value_t = 3)] // field attribute
6
    context: usize,
7
}

#[command(version, about)] with no value pulls the version and description straight from Cargo.toml (package.version and package.description). Set version = "1.2.0" and description = "..." in Cargo.toml and clap reuses them, so you never duplicate your version string.

`short` and `long`

#[arg(short, long)] derives the short flag from the first letter of the field name (-c) and the long flag from the field name with hyphens (--context).
Field names in snake_case become --kebab-case long flags automatically: case_sensitive → --case-sensitive.
Override either: #[arg(short = 'C', long = "ctx")].

Doc comments become help text

The doc comment on a field is its help string; the doc comment on the struct is the command’s about. This is why the --help output below needs no extra wiring (real output from loganalyze --help):

1
A fast log file analyzer
2

3
Usage: loganalyze [OPTIONS] <PATH>
4

5
Arguments:
6
  <PATH>  Path to the log file to analyze
7

8
Options:
9
  -p, --pattern <PATTERN>  Filter to lines containing this pattern
10
  -c, --context <CONTEXT>  Number of lines of context to show [default: 3]
11
  -v, --verbose...         Increase logging verbosity (-v, -vv, -vvv)
12
      --case-sensitive     Treat the pattern as case-sensitive
13
      --format <FORMAT>    Output format [default: text] [possible values: text, json, csv]
14
  -i, --ignore <IGNORE>    Files to ignore (repeatable)
15
  -h, --help               Print help
16
  -V, --version            Print version

Note: The Usage: line shows the binary name taken from argv[0] at runtime, while --version prints the name you set in #[command(name = ...)]. Don’t be surprised if cargo run shows the project’s binary name in usage but your chosen name in the version string.

Defaults: `default_value_t` vs. `default_value`

This trips up newcomers, so it’s worth being precise:

default_value_t = <expr> — the default is a value of the field’s type. clap formats it via Display. Use it for typed defaults: default_value_t = 3, default_value_t = Format::Text.
default_value = "<string>" — the default is a string that is run through the same parser as user input. Use it when a string literal reads naturally: default_value = "127.0.0.1".

1
#[arg(long, default_value_t = 8080)]        // typed default: the integer 8080
2
port: u16,
3

4
#[arg(long, default_value = "127.0.0.1")]   // string default, parsed like input
5
host: String,

A field with a default is automatically optional — the user can omit it. A field without a default and without Option<T> is required.

Counting flags and other actions

action = clap::ArgAction::Count turns repeated occurrences into a number. -vvv becomes 3. This is the idiomatic Rust replacement for commander’s custom (_, prev) => prev + 1 reducer. Other useful actions include ArgAction::SetTrue / SetFalse (which a bare bool field already implies) and ArgAction::Append (which a Vec<T> field already implies).

Enums via `ValueEnum`

Derive ValueEnum on an enum and clap restricts the argument to the variant names (lowercased, kebab-cased) and lists them in --help as [possible values: text, json, csv]. Reject anything else automatically — no manual .choices([...]) array to maintain.

Key Differences

Concern	commander / yargs (Node)	clap derive (Rust)
Source of truth	Chain of runtime method calls	A `struct` definition
Value types	Mostly `string` / `any`; you coerce	The field’s Rust type; parsed and checked
Required vs optional	`<required>` vs `[optional]` in a string	`T` (required) vs `Option<T>` (optional)
Repeated values	`<x...>` + default `[]`	`Vec<T>`
Enumerated choices	`.choices([...])` (runtime array)	`#[derive(ValueEnum)]` (a real enum)
Counting flags	Custom reducer function	`ArgAction::Count` on a `u8`
Validation	Hand-written in your code	`value_parser` returns `Result`; clap reports the error
Help text	Strings passed to each method	Doc comments on the struct/fields
When errors surface	Runtime	Parse time, before your logic runs

The deeper shift: in Node the parser hands you a loosely-typed bag and your program does the validating. In Rust, by the time Cli::parse() returns, every field is already the correct, validated type — invalid input never reaches your main. This is the same payoff you get from parsing untyped JSON into a typed struct with serde (see Section 15).

Tip: Think of Cli::parse() as “parse, don’t validate” applied to argv. The struct you get back makes illegal states unrepresentable.

Common Pitfalls

Forgetting the `derive` feature

clap’s derive macros live behind a Cargo feature. If you cargo add clap without it, the Parser trait is in scope but the derive macro is not, and you get a real compiler error:

1
error: cannot find derive macro `Parser` in this scope
2
note: `Parser` is imported here, but it is only a trait, without a derive macro
3

4
error[E0599]: no function or associated item named `parse` found for struct `Cli` in the current scope

Fix it by enabling the feature:

1
cargo add clap --features derive

Using `default_value_t` on a `bool`

A bool field is already a flag that defaults to false. Trying to give it default_value_t = false is redundant and confusing — just declare the field:

1
#[arg(long)]
2
case_sensitive: bool,   // absent → false, present → true

If you actually need a flag that defaults to on and can be turned off, use an explicit ArgAction::SetFalse with a --no-... long name, or model it as an Option<bool> / enum.

A field type with no parser

Every non-bool field must know how to turn a string into its type. clap can do this for any type that implements FromStr or ValueEnum, or for which you supply a value_parser. Use a plain custom struct and you get a long but informative error (real output):

1
#[derive(Debug, Clone)]
2
struct Color { r: u8, g: u8, b: u8 }   // does not compile (error[E0599])
3

4
#[derive(clap::Parser, Debug)]
5
struct Cli {
6
    #[arg(long)]
7
    color: Color,   // clap can't parse a string into Color
8
}

1
error[E0599]: the method `value_parser` exists for reference `&&&&&&_infer_ValueParser_for<Color>`, but its trait bounds were not satisfied
2
   |
3
13 |     #[arg(long)]
4
   |     ^ method cannot be called on `&&&&&&_infer_ValueParser_for<Color>` due to unsatisfied trait bounds
5
   |
6
   = note: the following trait bounds were not satisfied:
7
           `Color: ValueEnum`
8
           `Color: ValueParserFactory`
9
           `Color: From<OsString>`
10
           ...

The fix is to either implement FromStr for Color, derive ValueEnum (if it’s a simple enum), or attach a value_parser = my_fn.

Note: That cascade of &&&&&& references is clap’s autoref-based specialization trick for inferring a parser from the field type. It looks alarming, but the note: lines tell you exactly what’s missing: a way to build the type from a string.

Confusing the two default attributes

default_value = 3 (an integer where clap expects a string) won’t compile; default_value_t = "3" (a string where clap wants the field’s type) also won’t. Remember: _t = typed value, plain default_value = string. When in doubt, prefer default_value_t so the default is checked by the type system.

Expecting `Option<T>` and getting a required arg

A field declared as String is required. If the user omits it, clap exits with code 2 before main runs (real output):

1
error: the following required arguments were not provided:
2
  <PATH>
3

4
Usage: probe <PATH>
5

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

If the argument should be optional, make it Option<String> (or give it a default). This is the opposite default from commander, where an option with no value is simply undefined.

Best Practices

Prefer derive over the builder API for new tools. It is less code, harder to get out of sync, and the type system catches mistakes. Drop to the builder only when you need fully dynamic commands decided at runtime (see clap-basics.md).
Pull version/about from Cargo.toml with #[command(version, about)] so your CLI’s version always matches the crate version.
Use precise field types. Make port a u16, a path a PathBuf, a level a ValueEnum. Let clap reject bad input instead of validating later.
Use Option<T> for genuinely optional inputs and a default for “has a sensible fallback.” Don’t reach for String::new() sentinels.
Group reusable arguments with #[derive(Args)] + #[command(flatten)] so several commands can share a block of options:

1
use clap::{Args, Parser};
2

3
/// Options shared across several commands.
4
#[derive(Args, Debug)]
5
struct GlobalOpts {
6
    /// Suppress all non-error output
7
    #[arg(short, long, global = true)]
8
    quiet: bool,
9

10
    /// Path to the config file
11
    #[arg(long, default_value = "config.toml")]
12
    config: String,
13
}
14

15
#[derive(Parser, Debug)]
16
#[command(version, about)]
17
struct Cli {
18
    /// The input file
19
    input: String,
20

21
    #[command(flatten)]
22
    global: GlobalOpts,
23
}
24

25
fn main() {
26
    let cli = Cli::parse();
27
    println!("{cli:#?}");
28
}

Running app data.csv --quiet flattens the shared options into the struct (real output):

1
Cli {
2
    input: "data.csv",
3
    global: GlobalOpts {
4
        quiet: true,
5
        config: "config.toml",
6
    },
7
}

Validate with value_parser functions that return Result<T, String> (or any Display error). The Err string is shown to the user verbatim, prefixed by clap.
Read from the environment with env = "VAR" (needs the env feature: cargo add clap --features derive,env) so flags can fall back to environment variables — handy for secrets you don’t want on the command line. See environment-vars.md.
Use try_parse() instead of parse() when you want to handle parse failures yourself rather than letting clap exit the process:

1
match Cli::try_parse() {
2
    Ok(cli) => run(cli),
3
    Err(e) => e.exit(), // prints help/error and exits with the conventional code
4
}

Real-World Example

A miniature wc (word count) tool: it parses arguments with derive, reads a file, handles I/O errors gracefully, and returns a proper process exit code. This compiles and runs as shown.

1
use std::fs;
2
use std::path::PathBuf;
3
use std::process::ExitCode;
4

5
use clap::Parser;
6

7
/// Count lines, words, and bytes in a file (a tiny `wc`).
8
#[derive(Parser, Debug)]
9
#[command(name = "rwc", version, about)]
10
struct Cli {
11
    /// File to inspect
12
    file: PathBuf,
13

14
    /// Count lines only
15
    #[arg(short, long)]
16
    lines: bool,
17

18
    /// Count words only
19
    #[arg(short, long)]
20
    words: bool,
21
}
22

23
fn main() -> ExitCode {
24
    let cli = Cli::parse();
25

26
    let contents = match fs::read_to_string(&cli.file) {
27
        Ok(c) => c,
28
        Err(err) => {
29
            eprintln!("rwc: {}: {err}", cli.file.display());
30
            return ExitCode::FAILURE;
31
        }
32
    };
33

34
    let line_count = contents.lines().count();
35
    let word_count = contents.split_whitespace().count();
36
    let byte_count = contents.len();
37

38
    // If neither flag is set, show all three (like real `wc`).
39
    let show_all = !cli.lines && !cli.words;
40

41
    if cli.lines || show_all {
42
        print!("{line_count:>8} ");
43
    }
44
    if cli.words || show_all {
45
        print!("{word_count:>8} ");
46
    }
47
    if show_all {
48
        print!("{byte_count:>8} ");
49
    }
50
    println!("{}", cli.file.display());
51

52
    ExitCode::SUCCESS
53
}

Given a file sample.txt containing hello world\nfoo bar baz\n, here is the real output:

1
$ rwc sample.txt
2
       2        5       24 sample.txt
3

4
$ rwc --lines sample.txt
5
       2 sample.txt
6

7
$ rwc /tmp/nope.txt
8
rwc: /tmp/nope.txt: No such file or directory (os error 2)
9
$ echo $?
10
1

Notice how returning ExitCode from main lets the tool report failure to the shell — a script calling rwc can check $? exactly as it would for a C program. For richer error reporting in larger tools, return anyhow::Result<()> from main instead (covered in Section 08). File reading and buffered I/O are explored further in file-io.md, and PathBuf handling in path-handling.md.

Exercises

Exercise 1: A typed greeter

Difficulty: Beginner

Objective: Build the smallest possible derive CLI with a required positional argument and an option that has a typed default.

Instructions: Write a greet tool that takes a required name and an optional --count / -c (default 1) and prints Hello, <name>! that many times.

1
use clap::Parser;
2

3
#[derive(Parser, Debug)]
4
#[command(version, about = "Greets a person")]
5
struct Cli {
6
    // TODO: a required `name`
7
    // TODO: a `--count` / `-c` with a typed default of 1
8
}
9

10
fn main() {
11
    let cli = Cli::parse();
12
    // TODO: print the greeting `cli.count` times
13
}

Solution

1
use clap::Parser;
2

3
#[derive(Parser, Debug)]
4
#[command(version, about = "Greets a person")]
5
struct Cli {
6
    /// Name of the person to greet
7
    name: String,
8

9
    /// Number of times to repeat the greeting
10
    #[arg(short, long, default_value_t = 1)]
11
    count: u8,
12
}
13

14
fn main() {
15
    let cli = Cli::parse();
16
    for _ in 0..cli.count {
17
        println!("Hello, {}!", cli.name);
18
    }
19
}

Running greet Alice -c 3 prints (real output):

1
Hello, Alice!
2
Hello, Alice!
3
Hello, Alice!

Exercise 2: Multiple files, verbosity, and a conflict

Difficulty: Intermediate

Objective: Use a Vec, a counting flag, and a mutual-exclusion rule.

Instructions: Write a tool that accepts one or more file paths as positionals, a -v flag that can repeat to raise verbosity, and a -q / --quiet flag. --verbose and --quiet must not be allowed together. When not quiet, print the verbosity level and each file being processed.

Solution

1
use std::path::PathBuf;
2
use clap::Parser;
3

4
#[derive(Parser, Debug)]
5
#[command(version, about)]
6
struct Cli {
7
    /// Files to process (one or more)
8
    #[arg(required = true, num_args = 1..)]
9
    files: Vec<PathBuf>,
10

11
    /// Increase verbosity (-v, -vv)
12
    #[arg(short, long, action = clap::ArgAction::Count, conflicts_with = "quiet")]
13
    verbose: u8,
14

15
    /// Suppress output
16
    #[arg(short, long)]
17
    quiet: bool,
18
}
19

20
fn main() {
21
    let cli = Cli::parse();
22
    if !cli.quiet {
23
        println!("verbosity={}", cli.verbose);
24
        for f in &cli.files {
25
            println!("processing {}", f.display());
26
        }
27
    }
28
}

Running app a.txt b.txt -vv prints (real output):

1
verbosity=2
2
processing a.txt
3
processing b.txt

Running app -q -v is rejected at parse time:

1
error: the argument '--quiet' cannot be used with '--verbose...'

And running with no files reports the missing required argument:

1
error: the following required arguments were not provided:
2
  <FILES>...

Exercise 3: Enums, custom validation, and environment fallback

Difficulty: Advanced

Objective: Combine ValueEnum, a custom value_parser, and env.

Instructions: Build a server-config CLI with: a --log-level restricted to debug/info/warn/error (default info); a --port (u16, default 8080) that is rejected if below 1024 via a custom parser function returning Result<u16, String>; and an --api-key that falls back to the API_KEY environment variable. (Enable the env feature: cargo add clap --features derive,env.)

Solution

1
use clap::{Parser, ValueEnum};
2

3
#[derive(ValueEnum, Clone, Debug)]
4
enum LogLevel {
5
    Debug,
6
    Info,
7
    Warn,
8
    Error,
9
}
10

11
fn parse_port(s: &str) -> Result<u16, String> {
12
    let port: u16 = s.parse().map_err(|_| format!("`{s}` is not a number"))?;
13
    if port < 1024 {
14
        return Err("port must be >= 1024".to_string());
15
    }
16
    Ok(port)
17
}
18

19
#[derive(Parser, Debug)]
20
#[command(version, about)]
21
struct Cli {
22
    /// Logging level
23
    #[arg(long, value_enum, default_value_t = LogLevel::Info)]
24
    log_level: LogLevel,
25

26
    /// Port to listen on (>= 1024)
27
    #[arg(long, default_value_t = 8080, value_parser = parse_port)]
28
    port: u16,
29

30
    /// API key (falls back to API_KEY env var)
31
    #[arg(long, env = "API_KEY")]
32
    api_key: Option<String>,
33
}
34

35
fn main() {
36
    let cli = Cli::parse();
37
    println!("{cli:#?}");
38
}

Running with API_KEY=abc app --log-level warn --port 9000 prints (real output):

1
Cli {
2
    log_level: Warn,
3
    port: 9000,
4
    api_key: Some(
5
        "abc",
6
    ),
7
}

Running app --port 80 is rejected by the custom parser:

1
error: invalid value '80' for '--port <PORT>': port must be >= 1024
2

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

Parsing Arguments with the clap Derive API

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The field type drives everything

Container attributes vs. field attributes

short and long

Doc comments become help text

Defaults: default_value_t vs. default_value

Counting flags and other actions

Enums via ValueEnum

Key Differences

Common Pitfalls

Forgetting the derive feature

Using default_value_t on a bool

A field type with no parser

Confusing the two default attributes

Expecting Option<T> and getting a required arg

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A typed greeter

Exercise 2: Multiple files, verbosity, and a conflict

Exercise 3: Enums, custom validation, and environment fallback

`short` and `long`

Defaults: `default_value_t` vs. `default_value`

Enums via `ValueEnum`

Forgetting the `derive` feature

Using `default_value_t` on a `bool`

Expecting `Option<T>` and getting a required arg