## File: README.md

# clap

> **Command Line Argument Parser for Rust**

[](https://crates.io/crates/clap)
[](https://crates.io/crates/clap)
[](LICENSE-APACHE)
[](LICENSE-MIT)
[](https://github.com/clap-rs/clap/actions/workflows/ci.yml?query=branch%3Amaster)
[](https://coveralls.io/github/clap-rs/clap?branch=master)
[](https://github.com/clap-rs/clap/graphs/contributors)

Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).

## Get Started

```console
$ cargo add clap
```

## About

Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.

For more details, see:
- [docs.rs](https://docs.rs/clap/latest/clap/)
- [examples](examples/)

## Sponsors


### Gold

[](https://opencollective.com/clap)


### Silver

[](https://opencollective.com/clap)


### Bronze

[](https://opencollective.com/clap)


### Backer

[](https://opencollective.com/clap)

---

## File: clap_builder/README.md

# `clap_builder`

Builder implementation for clap.

[docs.rs](https://docs.rs/clap)
- [Derive Tutorial](https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html)
- [Derive Reference](https://docs.rs/clap/latest/clap/_derive/index.html)

## License

Licensed under either of

* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/license/mit>)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual-licensed as above, without any additional terms or
conditions.

See [CONTRIBUTING](CONTRIBUTING.md) for more details.

---

## File: clap_complete/README.md

# clap_complete

> **Shell completion generation for `clap`**

[](https://crates.io/crates/clap_complete)
[](https://crates.io/crates/clap_complete)
[](https://github.com/clap-rs/clap/blob/clap_complete-v4.6.9/LICENSE-APACHE)
[](https://github.com/clap-rs/clap/blob/clap_complete-v4.6.9/LICENSE-MIT)

Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).

1. [About](#about)
2. [API Reference](https://docs.rs/clap_complete)
3. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
4. [CONTRIBUTING](https://github.com/clap-rs/clap/blob/clap_complete-v4.6.9/clap_complete/CONTRIBUTING.md)
5. [Sponsors](https://github.com/clap-rs/clap/blob/clap_complete-v4.6.9/README.md#sponsors)

## About

### Related Projects

- [clap_complete_nushell](https://crates.io/crates/clap_complete_nushell) for [nushell](https://www.nushell.sh/) shell completion support

---

## File: clap_complete_nushell/README.md

# clap_complete_nushell

Generates [Nushell](https://github.com/nushell/nushell) completions for [`clap`](https://github.com/clap-rs/clap) based CLIs

[](https://crates.io/crates/clap_complete_nushell)
[](https://crates.io/crates/clap_complete_nushell)
[](LICENSE-APACHE)
[](LICENSE-MIT)
[](https://docs.rs/clap_complete_nushell)

- [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
- [CONTRIBUTING](../CONTRIBUTING.md)

## Examples

### myapp.rs

```rust
use clap::{builder::PossibleValue, Arg, ArgAction, Command, ValueHint};
use clap_complete::generate;
use clap_complete_nushell::Nushell;
use std::io;

fn main() {
    let mut cmd = Command::new("myapp")
        .version("3.0")
        .propagate_version(true)
        .about("Tests completions")
        .arg(
            Arg::new("file")
                .value_hint(ValueHint::FilePath)
                .help("some input file"),
        )
        .arg(
            Arg::new("config")
                .action(ArgAction::Count)
                .help("some config file")
                .short('c')
                .visible_short_alias('C')
                .long("config")
                .visible_alias("conf"),
        )
        .arg(Arg::new("choice").value_parser(["first", "second"]))
        .subcommand(
            Command::new("test").about("tests things").arg(
                Arg::new("case")
                    .long("case")
                    .action(ArgAction::Set)
                    .help("the case to test"),
            ),
        )
        .subcommand(
            Command::new("some_cmd")
                .about("top level subcommand")
                .subcommand(
                    Command::new("sub_cmd").about("sub-subcommand").arg(
                        Arg::new("config")
                            .long("config")
                            .action(ArgAction::Set)
                            .value_parser([PossibleValue::new("Lest quotes aren't escaped.")])
                            .help("the other case to test"),
                    ),
                ),
        );

    generate(Nushell, &mut cmd, "myapp", &mut io::stdout());
}

```

### myapp.nu

```nu
module completions {

  def "nu-complete myapp choice" [] {
    [ "first" "second" ]
  }

  # Tests completions
  export extern myapp [
    file?: string             # some input file
    --config(-c)              # some config file
    --conf                    # some config file
    -C                        # some config file
    choice?: string@"nu-complete myapp choice"
    --version(-V)             # Print version
  ]

  # tests things
  export extern "myapp test" [
    --case: string            # the case to test
    --version(-V)             # Print version
  ]

  # top level subcommand
  export extern "myapp some_cmd" [
    --version(-V)             # Print version
  ]

  def "nu-complete myapp some_cmd sub_cmd config" [] {
    [ "\"Lest quotes aren't escaped.\"" ]
  }

  # sub-subcommand
  export extern "myapp some_cmd sub_cmd" [
    --config: string@"nu-complete myapp some_cmd sub_cmd config" # the other case to test
    --version(-V)             # Print version
  ]

}

use completions *
```

---

## File: clap_derive/README.md

# `clap_derive`

Macro implementation for clap's derives.

[docs.rs](https://docs.rs/clap)
- [Derive Tutorial](https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html)
- [Derive Reference](https://docs.rs/clap/latest/clap/_derive/index.html)

## License

Licensed under either of

* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/license/mit>)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual-licensed as above, without any additional terms or
conditions.

See [CONTRIBUTING](CONTRIBUTING.md) for more details.

---

## File: clap_lex/README.md

# clap_lex

> **Minimal, flexible command line parser**

[](https://crates.io/crates/clap_lex)
[](https://crates.io/crates/clap_lex)
[](https://github.com/clap-rs/clap/blob/clap_lex-v1.1.0/LICENSE-APACHE)
[](https://github.com/clap-rs/clap/blob/clap_lex-v1.1.0/LICENSE-MIT)

Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).

1. [About](#about)
2. [API Reference](https://docs.rs/clap_lex)
3. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
4. [CONTRIBUTING](https://github.com/clap-rs/clap/blob/clap_lex-v1.1.0/clap_lex/CONTRIBUTING.md)
5. [Sponsors](https://github.com/clap-rs/clap/blob/clap_lex-v1.1.0/README.md#sponsors)

## About

---

## File: clap_mangen/README.md

# `clap_mangen`

> **Manpage generation for `clap`**

[](https://crates.io/crates/clap_mangen)
[](https://crates.io/crates/clap_mangen)
[](https://github.com/clap-rs/clap/blob/clap_mangen-v0.3.3/LICENSE-APACHE)
[](https://github.com/clap-rs/clap/blob/clap_mangen-v0.3.3/LICENSE-MIT)

Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).

1. [About](#about)
2. [API Reference](https://docs.rs/clap_mangen)
3. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
4. [CONTRIBUTING](https://github.com/clap-rs/clap/blob/clap_mangen-v0.3.3/clap_mangen/CONTRIBUTING.md)
5. [Sponsors](https://github.com/clap-rs/clap/blob/clap_mangen-v0.3.3/README.md#sponsors)

## About

Generate [ROFF](https://en.wikipedia.org/wiki/Roff_(software)) from a `clap::Command`.

### Example

We're going to assume you want to generate your man page as part of your
development rather than your shipped program having a flag to generate it.

Run
```console
$ cargo add --build clap_mangen
```

In your `build.rs`:
```rust,no_run
fn main() -> std::io::Result<()> {
    let out_dir = std::path::PathBuf::from(std::env::var_os("OUT_DIR").ok_or(std::io::ErrorKind::NotFound)?);

    let cmd = clap::Command::new("mybin")
        .arg(clap::arg!(-n --name <NAME>))
        .arg(clap::arg!(-c --count <NUM>));

    let man = clap_mangen::Man::new(cmd);
    let mut buffer: Vec = Default::default();
    man.render(&mut buffer)?;

    std::fs::write(out_dir.join("mybin.1"), buffer)?;

    Ok(())
}
```

Tip: Consider a [cargo xtask](https://github.com/matklad/cargo-xtask) instead of a `build.rs` to reduce build costs.

---

## File: examples/README.md

# Examples

We try to focus our documentation on the [four types of
documentation](https://documentation.divio.com/).  Examples fit into this by
providing:
- [Cookbook / How-To Guides](https://docs.rs/clap/latest/clap/_cookbook/index.html)
- Tutorials ([derive](https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html), [builder](https://docs.rs/clap/latest/clap/_tutorial/index.html))

This directory contains the source for the above.

## Contributing

New examples should fit within the above structure and support their narrative
- Add the example to [Cargo.toml](../Cargo.toml) for any `required-features`
- Document how the example works with a `.md` file which will be verified using [trycmd](https://docs.rs/trycmd)
- Pull the `.rs` and `.md` file into the appropriate module doc comment to be accessible on docs.rs