clap

Derive-based argument parsing with validation, help generation, and subcommands.

Recipe

use clap::Parser;
 
#[derive(Parser)]
#[command(name = "greet", version, about = "Greet someone")]
struct Args {
    /// Name to greet
    name: String,
 
    /// Number of times to greet
    #[arg(short, long, default_value_t = 1)]
    count: u8,
}
 
fn main() {
    let args = Args::parse();
    for _ in 0..args.count {
        println!("Hello, {}!", args.name);
    }
}

When to reach for this: Any CLI with more than one or two flags. clap is the de facto standard in the Rust ecosystem.

Working Example

use clap::{Parser, Subcommand, ValueEnum};
use std::path::PathBuf;
 
#[derive(Parser)]
#[command(name = "backup", version, about = "Backup files")]
struct Cli {
    /// Increase verbosity (-v, -vv)
    #[arg(short, long, action = clap::ArgAction::Count)]
    verbose: u8,
 
    /// Config file path
    #[arg(short, long, env = "BACKUP_CONFIG")]
    config: Option<PathBuf>,
 
    #[command(subcommand)]
    command: Command,
}
 
#[derive(Subcommand)]
enum Command {
    /// Create a new backup
    Create {
        #[arg(value_enum)]
        format: Format,
        source: PathBuf,
    },
    /// List existing backups
    List,
}
 
#[derive(Clone, ValueEnum)]
enum Format {
    Tar,
    Zip,
}
 
fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Command::Create { format, source } => {
            println!("backing up {source:?} as {format:?}");
        }
        Command::List => println!("no backups yet"),
    }
    Ok(())
}

What this demonstrates:

• Derive macros generate --help and validation automatically
• env = binds environment variables to flags
• ValueEnum restricts choices to a typed set
• Subcommands organize multi-verb CLIs

Deep Dive

How It Works

• #[derive(Parser)] expands to a parse() implementation at compile time
• Doc comments on fields become help text
• ArgAction::Count implements -v / -vv verbosity patterns
• Errors print usage hints and exit with code 2

Common Attributes

Builder API Alternative

Use the builder API when you need dynamic arguments at runtime.

use clap::{Arg, Command};
 
let cmd = Command::new("dynamic")
    .arg(Arg::new("file").required(true));
let matches = cmd.get_matches();

Gotchas

• Missing derive feature - Add clap = { version = "4", features = ["derive"] }. Fix: Enable the derive feature in Cargo.toml.
• Enum subcommands need Subcommand derive - Plain enums fail to compile. Fix: Add #[derive(Subcommand)].
• default_value vs default_value_t - String defaults need quotes; typed defaults use _t. Fix: Match the attribute to your field type.
• Flattening nested structs - #[command(flatten)] merges args but can cause name collisions. Fix: Use unique field names or explicit id.
• Help version drift - Hardcoded version strings go stale. Fix: Use #[command(version = env!("CARGO_PKG_VERSION"))].

Alternatives

FAQs

Related

• CLI Basics - fundamentals
• Configuration & Env - env var binding
• Shell Completions & Man Pages - completions
• Error Reporting - user-friendly errors

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Y29kZWd1aWRlcy5pb3xjZ2lvMTE5fDIwMjYwNw