gh-vanman2024-cli-builder-plugins-cli-builder/skills/clap-patterns/examples/quick-start.md

Clap Quick Start Guide

This guide will help you build your first Clap CLI application in minutes.

Prerequisites

• Rust installed (1.70.0 or newer)
• Cargo (comes with Rust)

Step 1: Create a New Project

cargo new my-cli
cd my-cli

Step 2: Add Clap Dependency

Edit Cargo.toml:

[dependencies]
clap = { version = "4.5", features = ["derive"] }

Step 3: Write Your First CLI

Replace src/main.rs with:

use clap::Parser;

/// Simple program to greet a person
#[derive(Parser)]
#[command(author, version, about, long_about = None)]
struct Args {
    /// Name of the person to greet
    #[arg(short, long)]
    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)
    }
}

Step 4: Build and Run

# Build the project
cargo build --release

# Run with arguments
./target/release/my-cli --name Alice --count 3

# Check help output
./target/release/my-cli --help

Expected Output

$ ./target/release/my-cli --name Alice --count 3
Hello Alice!
Hello Alice!
Hello Alice!

Help Output

$ ./target/release/my-cli --help
Simple program to greet a person

Usage: my-cli --name <NAME> [--count <COUNT>]

Options:
  -n, --name <NAME>     Name of the person to greet
  -c, --count <COUNT>   Number of times to greet [default: 1]
  -h, --help            Print help
  -V, --version         Print version

Next Steps

1. Add Subcommands: See subcommands.rs template
2. Add Validation: See value-parser.rs template
3. Environment Variables: See env-variables.rs template
4. Type-Safe Options: See value-enum.rs template

Common Patterns

Optional Arguments

#[arg(short, long)]
output: Option<String>,

Multiple Values

#[arg(short, long, num_args = 1..)]
files: Vec<PathBuf>,

Boolean Flags

#[arg(short, long)]
verbose: bool,

With Default Value

#[arg(short, long, default_value = "config.toml")]
config: String,

Required Unless Present

#[arg(long, required_unless_present = "config")]
database_url: Option<String>,

Troubleshooting

"Parser trait not found"

Add the import:

use clap::Parser;

"derive feature not enabled"

Update Cargo.toml:

clap = { version = "4.5", features = ["derive"] }

Help text not showing

Add doc comments above fields:

/// This shows up in --help output
#[arg(short, long)]

Resources

• Full templates: skills/clap-patterns/templates/
• Helper scripts: skills/clap-patterns/scripts/
• Official docs: https://docs.rs/clap/latest/clap/