README.md
1<!-- omit in TOC -->
2# clap
3
4> **Command Line Argument Parser for Rust**
5
6[](https://crates.io/crates/clap)
7[](https://crates.io/crates/clap)
8[](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/LICENSE-APACHE)
9[](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/LICENSE-MIT)
10[](https://github.com/clap-rs/clap/actions/workflows/ci.yml?query=branch%3Astaging)
11[](https://coveralls.io/github/clap-rs/clap?branch=master)
12[](https://github.com/clap-rs/clap/graphs/contributors)
13
14Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).
15
161. [About](#about)
172. Tutorial: [Builder API](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/examples/tutorial_derive/README.md)
183. [Examples](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/examples/README.md)
194. [API Reference](https://docs.rs/clap)
20 - [Derive Reference](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/examples/derive_ref/README.md)
21 - [Feature Flags](#feature-flags)
225. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/CHANGELOG.md)
236. [FAQ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/docs/FAQ.md)
247. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
258. [Contributing](https://github.com/clap-rs/clap/blob/v3.0.0-rc.5/CONTRIBUTING.md)
268. [Sponsors](#sponsors)
27
28## About
29
30Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.
31
32### Example
33
34<!-- Copied from examples/demo.{rs,md} -->
35```rust,no_run
36use clap::Parser;
37
38/// Simple program to greet a person
39#[derive(Parser, Debug)]
40#[clap(about, version, author)]
41struct Args {
42 /// Name of the person to greet
43 #[clap(short, long)]
44 name: String,
45
46 /// Number of times to greet
47 #[clap(short, long, default_value_t = 1)]
48 count: u8,
49}
50
51fn main() {
52 let args = Args::parse();
53
54 for _ in 0..args.count {
55 println!("Hello {}!", args.name)
56 }
57}
58```
59*(note: requires feature `derive`)*
60```bash
61$ demo --help
62clap [..]
63
64A simple to use, efficient, and full-featured Command Line Argument Parser
65
66USAGE:
67 demo[EXE] [OPTIONS] --name <NAME>
68
69OPTIONS:
70 -c, --count <COUNT> Number of times to greet [default: 1]
71 -h, --help Print help information
72 -n, --name <NAME> Name of the person to greet
73 -V, --version Print version information
74```
75*(version number and `.exe` extension on windows replaced by placeholders)*
76
77### Aspirations
78
79- Out of the box, users get a polished CLI experience
80 - Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_generate), etc
81- Flexible enough to port your existing CLI interface
82 - However, we won't necessarily streamline support for each use case
83- Reasonable parse performance
84- Resilient maintainership, including
85 - Willing to break compatibility rather than batching up breaking changes in large releases
86 - Leverage feature flags to keep to one active branch
87 - Being under [WG-CLI](https://github.com/rust-cli/team/) to increase the bus factor
88- We follow semver and will wait about 6-9 months between major breaking changes
89- We will support the last two minor Rust releases (MSRV, currently 1.54.0)
90
91While these aspirations can be at odds with fast build times and low binary
92size, we will still strive to keep these reasonable for the flexibility you
93get. Check out the
94[argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
95CLI parsers optimized for other use cases.
96
97### Related Projects
98
99- [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux
100- [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files)
101- [clap_generate](https://crates.io/crates/clap_generate) for shell completion support
102- [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
103- [clap-cargo](https://crates.io/crates/clap-cargo)
104- [concolor-clap](https://crates.io/crates/concolor-clap)
105- [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book
106- [`trycmd`](https://crates.io/crates/trycmd): Snapshot testing
107 - Or for more control, [`assert_cmd`](https://crates.io/crates/assert_cmd) and [`assert_fs`](https://crates.io/crates/assert_fs)
108
109## Feature Flags
110
111### Default Features
112
113* **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
114* **color**: Turns on colored error messages.
115* **suggestions**: Turns on the `Did you mean '--myoption'?` feature for when users make typos.
116
117#### Optional features
118
119* **derive**: Enables the custom derive (i.e. `#[derive(Parser)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above.
120* **cargo**: Turns on macros that read values from `CARGO_*` environment variables.
121* **env**: Turns on the usage of environment variables during parsing.
122* **regex**: Enables regex validators.
123* **unicode**: Turns on support for unicode characters (including emoji) in arguments and help messages.
124* **wrap_help**: Turns on the help text wrapping feature, based on the terminal size.
125
126#### Experimental features
127
128**Warning:** These may contain breaking changes between minor releases.
129
130* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
131* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861)
132* **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
133
134## Sponsors
135
136<!-- omit in TOC -->
137### Gold
138
139[](https://opencollective.com/clap)
140
141<!-- omit in TOC -->
142### Silver
143
144[](https://opencollective.com/clap)
145
146<!-- omit in TOC -->
147### Bronze
148
149[](https://opencollective.com/clap)
150
151<!-- omit in TOC -->
152### Backer
153
154[](https://opencollective.com/clap)
155
){kind=link}
){kind=link}
){kind=link}
){kind=link}