Available on crate feature unstable-doc only.
Expand description

§Quick Start

You can create an application declaratively with a struct and some attributes.

First, ensure clap is available with the derive feature flag:

$ cargo add clap --features derive
use std::path::PathBuf;

use clap::{Parser, Subcommand};

#[command(version, about, long_about = None)]
struct Cli {
    /// Optional name to operate on
    name: Option<String>,

    /// Sets a custom config file
    #[arg(short, long, value_name = "FILE")]
    config: Option<PathBuf>,

    /// Turn debugging information on
    #[arg(short, long, action = clap::ArgAction::Count)]
    debug: u8,

    command: Option<Commands>,

enum Commands {
    /// does testing things
    Test {
        /// lists test values
        #[arg(short, long)]
        list: bool,

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

    // You can check the value provided by positional arguments, or option arguments
    if let Some(name) = cli.name.as_deref() {
        println!("Value for name: {name}");

    if let Some(config_path) = cli.config.as_deref() {
        println!("Value for config: {}", config_path.display());

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match cli.debug {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        _ => println!("Don't be crazy"),

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level cmd
    match &cli.command {
        Some(Commands::Test { list }) => {
            if *list {
                println!("Printing testing lists...");
            } else {
                println!("Not printing testing lists...");
        None => {}

    // Continued program logic goes here...
$ 01_quick_derive --help
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: 01_quick_derive[EXE] [OPTIONS] [NAME] [COMMAND]

  test  does testing things
  help  Print this message or the help of the given subcommand(s)

  [NAME]  Optional name to operate on

  -c, --config <FILE>  Sets a custom config file
  -d, --debug...       Turn debugging information on
  -h, --help           Print help
  -V, --version        Print version

By default, the program does nothing:

$ 01_quick_derive
Debug mode is off

But you can mix and match the various features

$ 01_quick_derive -dd test
Debug mode is on
Not printing testing lists...

See also