Creates a new instance of an Command.

It is common, but not required, to use binary name as the name. This name will only be displayed to the user when they request to print version or help and usage information.

See also command! and crate_name!.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("My Program")
# ;

Adds an argument to the list of valid possibilities.

Examples

# use clap_builder as clap;
# use clap::{Command, arg, Arg};
Command::new("myprog")
    // Adding a single "flag" argument with a short and help text, using Arg::new()
    .arg(
        Arg::new("debug")
           .short('d')
           .help("turns on debugging mode")
    )
    // Adding a single "option" argument with a short, a long, and help text using the less
    // verbose Arg::from()
    .arg(
        arg!(-c --config <CONFIG> "Optionally sets a config file to use")
    )
# ;

Adds multiple arguments to the list of valid possibilities.

Examples

# use clap_builder as clap;
# use clap::{Command, arg, Arg};
Command::new("myprog")
    .args([
        arg!(-d --debug "turns on debugging info"),
        Arg::new("input").help("the input file to use")
    ])
# ;

Allows one to mutate an Arg after it's been added to a Command.

Panics

If the argument is undefined

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};

let mut cmd = Command::new("foo")
    .arg(Arg::new("bar")
        .short('b')
        .action(ArgAction::SetTrue))
    .mut_arg("bar", |a| a.short('B'));

let res = cmd.try_get_matches_from_mut(vec!["foo", "-b"]);

// Since we changed `bar`'s short to "B" this should err as there
// is no `-b` anymore, only `-B`

assert!(res.is_err());

let res = cmd.try_get_matches_from_mut(vec!["foo", "-B"]);
assert!(res.is_ok());

Allows one to mutate all Args after they've been added to a Command.

This does not affect the built-in --help or --version arguments.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};

let mut cmd = Command::new("foo")
    .arg(Arg::new("bar")
        .long("bar")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("baz")
        .long("baz")
        .action(ArgAction::SetTrue))
    .mut_args(|a| {
        if let Some(l) = a.get_long().map(|l| format!("prefix-{l}")) {
            a.long(l)
        } else {
            a
        }
    });

let res = cmd.try_get_matches_from_mut(vec!["foo", "--bar"]);

// Since we changed `bar`'s long to "prefix-bar" this should err as there
// is no `--bar` anymore, only `--prefix-bar`.

assert!(res.is_err());

let res = cmd.try_get_matches_from_mut(vec!["foo", "--prefix-bar"]);
assert!(res.is_ok());

Allows one to mutate an ArgGroup after it's been added to a Command.

Panics

If the argument is undefined

Examples

# use clap_builder as clap;
# use clap::{Command, arg, ArgGroup};

Command::new("foo")
    .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
    .arg(arg!(--major "auto increase major"))
    .arg(arg!(--minor "auto increase minor"))
    .arg(arg!(--patch "auto increase patch"))
    .group(ArgGroup::new("vers")
         .args(["set-ver", "major", "minor","patch"])
         .required(true))
    .mut_group("vers", |a| a.required(false));

Allows one to mutate a Command after it's been added as a subcommand.

This can be useful for modifying auto-generated arguments of nested subcommands with Command::mut_arg.

Panics

If the subcommand is undefined

Examples

# use clap_builder as clap;
# use clap::Command;

let mut cmd = Command::new("foo")
        .subcommand(Command::new("bar"))
        .mut_subcommand("bar", |subcmd| subcmd.disable_help_flag(true));

let res = cmd.try_get_matches_from_mut(vec!["foo", "bar", "--help"]);

// Since we disabled the help flag on the "bar" subcommand, this should err.

assert!(res.is_err());

let res = cmd.try_get_matches_from_mut(vec!["foo", "bar"]);
assert!(res.is_ok());

Adds an ArgGroup to the application.

ArgGroups are a family of related arguments. By placing them in a logical group, you can build easier requirement and exclusion rules.

Example use cases:

• Make an entire ArgGroup required, meaning that one (and only one) argument from that group must be present at runtime.
• Name an ArgGroup as a conflict to another argument. Meaning any of the arguments that belong to that group will cause a failure if present with the conflicting argument.
• Ensure exclusion between arguments.
• Extract a value from a group instead of determining exactly which argument was used.

Examples

The following example demonstrates using an ArgGroup to ensure that one, and only one, of the arguments from the specified group is present at runtime.

# use clap_builder as clap;
# use clap::{Command, arg, ArgGroup};
Command::new("cmd")
    .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
    .arg(arg!(--major "auto increase major"))
    .arg(arg!(--minor "auto increase minor"))
    .arg(arg!(--patch "auto increase patch"))
    .group(ArgGroup::new("vers")
         .args(["set-ver", "major", "minor","patch"])
         .required(true))
# ;

Adds multiple ArgGroups to the Command at once.

Examples

# use clap_builder as clap;
# use clap::{Command, arg, ArgGroup};
Command::new("cmd")
    .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
    .arg(arg!(--major         "auto increase major"))
    .arg(arg!(--minor         "auto increase minor"))
    .arg(arg!(--patch         "auto increase patch"))
    .arg(arg!(-c <FILE>       "a config file").required(false))
    .arg(arg!(-i <IFACE>      "an interface").required(false))
    .groups([
        ArgGroup::new("vers")
            .args(["set-ver", "major", "minor","patch"])
            .required(true),
        ArgGroup::new("input")
            .args(["c", "i"])
    ])
# ;

Adds a subcommand to the list of valid possibilities.

Subcommands are effectively sub-Commands, because they can contain their own arguments, subcommands, version, usage, etc. They also function just like Commands, in that they get their own auto generated help, version, and usage.

A subcommand's Command::name will be used for:

• The argument the user passes in
• Programmatically looking up the subcommand

Examples

# use clap_builder as clap;
# use clap::{Command, arg};
Command::new("myprog")
    .subcommand(Command::new("config")
        .about("Controls configuration features")
        .arg(arg!(<config> "Required configuration file to use")))
# ;

Adds multiple subcommands to the list of valid possibilities.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
# Command::new("myprog")
.subcommands( [
       Command::new("config").about("Controls configuration functionality")
                                .arg(Arg::new("config_file")),
       Command::new("debug").about("Controls debug functionality")])
# ;

Delay initialization for parts of the Command

This is useful for large applications to delay definitions of subcommands until they are being invoked.

Examples

# use clap_builder as clap;
# use clap::{Command, arg};
Command::new("myprog")
    .subcommand(Command::new("config")
        .about("Controls configuration features")
        .defer(|cmd| {
            cmd.arg(arg!(<config> "Required configuration file to use"))
        })
    )
# ;

Catch problems earlier in the development cycle.

Most error states are handled as asserts under the assumption they are programming mistake and not something to handle at runtime. Rather than relying on tests (manual or automated) that exhaustively test your CLI to ensure the asserts are evaluated, this will run those asserts in a way convenient for running as a test.

Note: This will not help with asserts in ArgMatches, those will need exhaustive testing of your CLI.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
fn cmd() -> Command {
    Command::new("foo")
        .arg(
            Arg::new("bar").short('b').action(ArgAction::SetTrue)
        )
}

#[test]
fn verify_app() {
    cmd().debug_assert();
}

fn main() {
    let m = cmd().get_matches_from(vec!["foo", "-b"]);
    println!("{}", m.get_flag("bar"));
}

Custom error message for post-parsing validation

Examples

# use clap_builder as clap;
# use clap::{Command, error::ErrorKind};
let mut cmd = Command::new("myprog");
let err = cmd.error(ErrorKind::InvalidValue, "Some failure case");

Parse env::args_os, [exiting][Error::exit] on failure.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let matches = Command::new("myprog")
    // Args and options go here...
    .get_matches();

Parse env::args_os, [exiting][Error::exit] on failure.

Like Command::get_matches but doesn't consume the Command.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let mut cmd = Command::new("myprog")
    // Args and options go here...
    ;
let matches = cmd.get_matches_mut();

Parse env::args_os, returning a clap::Result on failure.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let matches = Command::new("myprog")
    // Args and options go here...
    .try_get_matches()
    .unwrap_or_else(|e| e.exit());

Parse the specified arguments, [exiting][Error::exit] on failure.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let matches = Command::new("myprog")
    // Args and options go here...
    .get_matches_from(arg_vec);

Parse the specified arguments, returning a clap::Result on failure.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let matches = Command::new("myprog")
    // Args and options go here...
    .try_get_matches_from(arg_vec)
    .unwrap_or_else(|e| e.exit());

Parse the specified arguments, returning a clap::Result on failure.

Like Command::try_get_matches_from but doesn't consume the Command.

Panics

If contradictory arguments or settings exist (debug builds).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let mut cmd = Command::new("myprog");
    // Args and options go here...
let matches = cmd.try_get_matches_from_mut(arg_vec)
    .unwrap_or_else(|e| e.exit());

Prints the short help message (-h) to io::stdout().

See also Command::print_long_help.

Examples

# use clap_builder as clap;
# use clap::Command;
let mut cmd = Command::new("myprog");
cmd.print_help();

Prints the long help message (--help) to io::stdout().

See also Command::print_help.

Examples

# use clap_builder as clap;
# use clap::Command;
let mut cmd = Command::new("myprog");
cmd.print_long_help();

Render the short help message (-h) to a StyledStr

See also Command::render_long_help.

Examples

# use clap_builder as clap;
# use clap::Command;
use std::io;
let mut cmd = Command::new("myprog");
let mut out = io::stdout();
let help = cmd.render_help();
println!("{help}");

Render the long help message (--help) to a StyledStr.

See also Command::render_help.

Examples

# use clap_builder as clap;
# use clap::Command;
use std::io;
let mut cmd = Command::new("myprog");
let mut out = io::stdout();
let help = cmd.render_long_help();
println!("{help}");

Version message rendered as if the user ran -V.

See also Command::render_long_version.

Coloring

This function does not try to color the message nor it inserts any ANSI escape codes.

Examples

# use clap_builder as clap;
# use clap::Command;
use std::io;
let cmd = Command::new("myprog");
println!("{}", cmd.render_version());

Version message rendered as if the user ran --version.

See also Command::render_version.

Coloring

This function does not try to color the message nor it inserts any ANSI escape codes.

Examples

# use clap_builder as clap;
# use clap::Command;
use std::io;
let cmd = Command::new("myprog");
println!("{}", cmd.render_long_version());

Usage statement

Examples

# use clap_builder as clap;
# use clap::Command;
use std::io;
let mut cmd = Command::new("myprog");
println!("{}", cmd.render_usage());

Sets the short version of the subcommand flag without the preceding -.

Allows the subcommand to be used as if it were an Arg::short.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let matches = Command::new("pacman")
    .subcommand(
        Command::new("sync").short_flag('S').arg(
            Arg::new("search")
                .short('s')
                .long("search")
                .action(ArgAction::SetTrue)
                .help("search remote repositories for matching strings"),
        ),
    )
    .get_matches_from(vec!["pacman", "-Ss"]);

assert_eq!(matches.subcommand_name().unwrap(), "sync");
let sync_matches = matches.subcommand_matches("sync").unwrap();
assert!(sync_matches.get_flag("search"));

Sets the long version of the subcommand flag without the preceding --.

Allows the subcommand to be used as if it were an Arg::long.

Examples

To set long_flag use a word containing valid UTF-8 codepoints. If you supply a double leading -- such as --sync they will be stripped. Hyphens in the middle of the word; however, will not be stripped (i.e. sync-file is allowed).

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let matches = Command::new("pacman")
    .subcommand(
        Command::new("sync").long_flag("sync").arg(
            Arg::new("search")
                .short('s')
                .long("search")
                .action(ArgAction::SetTrue)
                .help("search remote repositories for matching strings"),
        ),
    )
    .get_matches_from(vec!["pacman", "--sync", "--search"]);

assert_eq!(matches.subcommand_name().unwrap(), "sync");
let sync_matches = matches.subcommand_matches("sync").unwrap();
assert!(sync_matches.get_flag("search"));

Sets a hidden alias to this subcommand.

This allows the subcommand to be accessed via either the original name, or this given alias. This is more efficient and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all aliased variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
    .subcommand(Command::new("test")
        .alias("do-stuff"))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add an alias, which functions as "hidden" short flag subcommand

This will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").short_flag('t')
                .short_flag_alias('d'))
            .get_matches_from(vec!["myprog", "-d"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add an alias, which functions as a "hidden" long flag subcommand.

This will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").long_flag("test")
                .long_flag_alias("testing"))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

Sets multiple hidden aliases to this subcommand.

This allows the subcommand to be accessed via either the original name or any of the given aliases. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command and not all aliased variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("myprog")
    .subcommand(Command::new("test")
        .aliases(["do-stuff", "do-tests", "tests"]))
        .arg(Arg::new("input")
            .help("the file to add")
            .required(false))
    .get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add aliases, which function as "hidden" short flag subcommands.

These will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
    .subcommand(Command::new("test").short_flag('t')
        .short_flag_aliases(['a', 'b', 'c']))
        .arg(Arg::new("input")
            .help("the file to add")
            .required(false))
    .get_matches_from(vec!["myprog", "-a"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add aliases, which function as "hidden" long flag subcommands.

These will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").long_flag("test")
                .long_flag_aliases(["testing", "testall", "test_all"]))
                .arg(Arg::new("input")
                            .help("the file to add")
                            .required(false))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

Sets a visible alias to this subcommand.

This allows the subcommand to be accessed via either the original name or the given alias. This is more efficient and easier than creating hidden subcommands as one only needs to check for the existence of this command and not all aliased variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("myprog")
    .subcommand(Command::new("test")
        .visible_alias("do-stuff"))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add an alias, which functions as "visible" short flag subcommand

This will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

See also Command::short_flag_alias.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").short_flag('t')
                .visible_short_flag_alias('d'))
            .get_matches_from(vec!["myprog", "-d"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add an alias, which functions as a "visible" long flag subcommand.

This will automatically dispatch as if this subcommand was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

See also Command::long_flag_alias.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").long_flag("test")
                .visible_long_flag_alias("testing"))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

Sets multiple visible aliases to this subcommand.

This allows the subcommand to be accessed via either the original name or any of the given aliases. This is more efficient and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command and not all aliased variants.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
    .subcommand(Command::new("test")
        .visible_aliases(["do-stuff", "tests"]))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add aliases, which function as visible short flag subcommands.

See Command::short_flag_aliases.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").short_flag('b')
                .visible_short_flag_aliases(['t']))
            .get_matches_from(vec!["myprog", "-t"]);
assert_eq!(m.subcommand_name(), Some("test"));

Add aliases, which function as visible long flag subcommands.

See Command::long_flag_aliases.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, };
let m = Command::new("myprog")
            .subcommand(Command::new("test").long_flag("test")
                .visible_long_flag_aliases(["testing", "testall", "test_all"]))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

Set the placement of this subcommand within the help.

Subcommands with a lower value will be displayed first in the help message. Those with the same display order will be sorted.

Commands are automatically assigned a display order based on the order they are added to their parent Command. Overriding this is helpful when the order commands are added in isn't the same as the display order, whether in one-off cases or to automatically sort commands.

Examples

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, };
let m = Command::new("cust-ord")
    .subcommand(Command::new("beta")
        .display_order(0)  // Sort
        .about("Some help and text"))
    .subcommand(Command::new("alpha")
        .display_order(0)  // Sort
        .about("I should be first!"))
    .get_matches_from(vec![
        "cust-ord", "--help"
    ]);
# }

The above example displays the following help message

cust-ord

Usage: cust-ord [OPTIONS]

Commands:
    alpha    I should be first!
    beta     Some help and text
    help     Print help for the subcommand(s)

Options:
    -h, --help       Print help
    -V, --version    Print version

Specifies that this subcommand should be hidden from help messages

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .subcommand(
        Command::new("test").hide(true)
    )
# ;

If no subcommand is present at runtime, error and exit gracefully.

Examples

# use clap_builder as clap;
# use clap::{Command, error::ErrorKind};
let err = Command::new("myprog")
    .subcommand_required(true)
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog",
    ]);
assert!(err.is_err());
assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingSubcommand);
# ;

Assume unexpected positional arguments are a subcommand.

Arguments will be stored in the "" argument in the ArgMatches

Examples

# use clap_builder as clap;
# use std::ffi::OsString;
# use clap::Command;
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_external_subcommands(true)
    .get_matches_from(vec![
        "myprog", "subcmd", "--option", "value", "-fff", "--flag"
    ]);

// All trailing arguments will be stored under the subcommand's sub-matches using an empty
// string argument name
match m.subcommand() {
    Some((external, ext_m)) => {
         let ext_args: Vec<_> = ext_m.get_many::<OsString>("").unwrap().collect();
         assert_eq!(external, "subcmd");
         assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
    },
    _ => {},
}

Specifies how to parse external subcommand arguments.

The default parser is for OsString. This can be used to switch it to String or another type.

Examples

# #[cfg(unix)] {
# use clap_builder as clap;
# use std::ffi::OsString;
# use clap::Command;
# use clap::value_parser;
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_external_subcommands(true)
    .get_matches_from(vec![
        "myprog", "subcmd", "--option", "value", "-fff", "--flag"
    ]);

// All trailing arguments will be stored under the subcommand's sub-matches using an empty
// string argument name
match m.subcommand() {
    Some((external, ext_m)) => {
         let ext_args: Vec<_> = ext_m.get_many::<OsString>("").unwrap().collect();
         assert_eq!(external, "subcmd");
         assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
    },
    _ => {},
}
# }

# use clap_builder as clap;
# use clap::Command;
# use clap::value_parser;
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .external_subcommand_value_parser(value_parser!(String))
    .get_matches_from(vec![
        "myprog", "subcmd", "--option", "value", "-fff", "--flag"
    ]);

// All trailing arguments will be stored under the subcommand's sub-matches using an empty
// string argument name
match m.subcommand() {
    Some((external, ext_m)) => {
         let ext_args: Vec<_> = ext_m.get_many::<String>("").unwrap().collect();
         assert_eq!(external, "subcmd");
         assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
    },
    _ => {},
}

Specifies that use of an argument prevents the use of subcommands.

By default clap allows arguments between subcommands such as <cmd> [cmd_args] <subcmd> [subcmd_args] <subsubcmd> [subsubcmd_args].

This setting disables that functionality and says that arguments can only follow the final subcommand. For instance using this setting makes only the following invocations possible:

• <cmd> <subcmd> <subsubcmd> [subsubcmd_args]
• <cmd> <subcmd> [subcmd_args]
• <cmd> [cmd_args]

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .args_conflicts_with_subcommands(true);

Prevent subcommands from being consumed as an arguments value.

By default, if an option taking multiple values is followed by a subcommand, the subcommand will be parsed as another value.

cmd --foo val1 val2 subcommand
          --------- ----------
            values   another value

This setting instructs the parser to stop when encountering a subcommand instead of greedily consuming arguments.

cmd --foo val1 val2 subcommand
          --------- ----------
            values   subcommand

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let cmd = Command::new("cmd").subcommand(Command::new("sub")).arg(
    Arg::new("arg")
        .long("arg")
        .num_args(1..)
        .action(ArgAction::Set),
);

let matches = cmd
    .clone()
    .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"])
    .unwrap();
assert_eq!(
    matches.get_many::<String>("arg").unwrap().collect::<Vec<_>>(),
    &["1", "2", "3", "sub"]
);
assert!(matches.subcommand_matches("sub").is_none());

let matches = cmd
    .subcommand_precedence_over_arg(true)
    .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"])
    .unwrap();
assert_eq!(
    matches.get_many::<String>("arg").unwrap().collect::<Vec<_>>(),
    &["1", "2", "3"]
);
assert!(matches.subcommand_matches("sub").is_some());

Allows subcommands to override all requirements of the parent command.

For example, if you had a subcommand or top level application with a required argument that is only required as long as there is no subcommand present, using this setting would allow you to set those arguments to Arg::required(true) and yet receive no error so long as the user uses a valid subcommand instead.

Examples

This first example shows that it is an error to not use a required argument

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let err = Command::new("myprog")
    .subcommand_negates_reqs(true)
    .arg(Arg::new("opt").required(true))
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog"
    ]);
assert!(err.is_err());
assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
# ;

This next example shows that it is no longer error to not use a required argument if a valid subcommand is used.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let noerr = Command::new("myprog")
    .subcommand_negates_reqs(true)
    .arg(Arg::new("opt").required(true))
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog", "test"
    ]);
assert!(noerr.is_ok());
# ;

Multiple-personality program dispatched on the binary name (argv[0])

A "multicall" executable is a single executable that contains a variety of applets, and decides which applet to run based on the name of the file. The executable can be called from different names by creating hard links or symbolic links to it.

This is desirable for:

• Easy distribution, a single binary that can install hardlinks to access the different personalities.
• Minimal binary size by sharing common code (e.g. standard library, clap)
• Custom shells or REPLs where there isn't a single top-level command

Setting multicall will cause

• argv[0] to be stripped to the base name and parsed as the first argument, as if [Command::no_binary_name][Command::no_binary_name] was set.
• Help and errors to report subcommands as if they were the top-level command

When the subcommand is not present, there are several strategies you may employ, depending on your needs:

• Let the error percolate up normally
• Print a specialized error message using the [Error::context][crate::Error::context]
• Print the [help][Command::write_help] but this might be ambiguous
• Disable multicall and re-parse it
• Disable multicall and re-parse it with a specific subcommand

When detecting the error condition, the ErrorKind isn't sufficient as a sub-subcommand might report the same error. Enable [allow_external_subcommands][Command::allow_external_subcommands] if you want to specifically get the unrecognized binary name.

Examples

hostname is an example of a multicall executable. Both hostname and dnsdomainname are provided by the same executable and which behaviour to use is based on the executable file name.

This is desirable when the executable has a primary purpose but there is related functionality that would be convenient to provide and implement it to be in the same executable.

The name of the cmd is essentially unused and may be the same as the name of a subcommand.

The names of the immediate subcommands of the Command are matched against the basename of the first argument, which is conventionally the path of the executable.

This does not allow the subcommand to be passed as the first non-path argument.

# use clap_builder as clap;
# use clap::{Command, error::ErrorKind};
let mut cmd = Command::new("hostname")
    .multicall(true)
    .subcommand(Command::new("hostname"))
    .subcommand(Command::new("dnsdomainname"));
let m = cmd.try_get_matches_from_mut(&["/usr/bin/hostname", "dnsdomainname"]);
assert!(m.is_err());
assert_eq!(m.unwrap_err().kind(), ErrorKind::UnknownArgument);
let m = cmd.get_matches_from(&["/usr/bin/dnsdomainname"]);
assert_eq!(m.subcommand_name(), Some("dnsdomainname"));

Busybox is another common example of a multicall executable with a subcommmand for each applet that can be run directly, e.g. with the cat applet being run by running busybox cat, or with cat as a link to the busybox binary.

This is desirable when the launcher program has additional options or it is useful to run the applet without installing a symlink e.g. to test the applet without installing it or there may already be a command of that name installed.

To make an applet usable as both a multicall link and a subcommand the subcommands must be defined both in the top-level Command and as subcommands of the "main" applet.

# use clap_builder as clap;
# use clap::Command;
fn applet_commands() -> [Command; 2] {
    [Command::new("true"), Command::new("false")]
}
let mut cmd = Command::new("busybox")
    .multicall(true)
    .subcommand(
        Command::new("busybox")
            .subcommand_value_name("APPLET")
            .subcommand_help_heading("APPLETS")
            .subcommands(applet_commands()),
    )
    .subcommands(applet_commands());
// When called from the executable's canonical name
// its applets can be matched as subcommands.
let m = cmd.try_get_matches_from_mut(&["/usr/bin/busybox", "true"]).unwrap();
assert_eq!(m.subcommand_name(), Some("busybox"));
assert_eq!(m.subcommand().unwrap().1.subcommand_name(), Some("true"));
// When called from a link named after an applet that applet is matched.
let m = cmd.get_matches_from(&["/usr/bin/true"]);
assert_eq!(m.subcommand_name(), Some("true"));

Sets the value name used for subcommands when printing usage and help.

By default, this is "COMMAND".

See also Command::subcommand_help_heading

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .subcommand(Command::new("sub1"))
    .print_help()
# ;

will produce

myprog

Usage: myprog [COMMAND]

Commands:
    help    Print this message or the help of the given subcommand(s)
    sub1

Options:
    -h, --help       Print help
    -V, --version    Print version

but usage of subcommand_value_name

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .subcommand(Command::new("sub1"))
    .subcommand_value_name("THING")
    .print_help()
# ;

will produce

myprog

Usage: myprog [THING]

Commands:
    help    Print this message or the help of the given subcommand(s)
    sub1

Options:
    -h, --help       Print help
    -V, --version    Print version

Sets the help heading used for subcommands when printing usage and help.

By default, this is "Commands".

See also Command::subcommand_value_name

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .subcommand(Command::new("sub1"))
    .print_help()
# ;

will produce

myprog

Usage: myprog [COMMAND]

Commands:
    help    Print this message or the help of the given subcommand(s)
    sub1

Options:
    -h, --help       Print help
    -V, --version    Print version

but usage of subcommand_help_heading

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .subcommand(Command::new("sub1"))
    .subcommand_help_heading("Things")
    .print_help()
# ;

will produce

myprog

Usage: myprog [COMMAND]

Things:
    help    Print this message or the help of the given subcommand(s)
    sub1

Options:
    -h, --help       Print help
    -V, --version    Print version

(Re)Sets the program's name.

See Command::new for more details.

Examples

let cmd = clap::command!()
    .name("foo");

// continued logic goes here, such as `cmd.get_matches()` etc.

Overrides the runtime-determined name of the binary for help and error messages.

This should only be used when absolutely necessary, such as when the binary name for your application is misleading, or perhaps not how the user should invoke your program.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("My Program")
     .bin_name("my_binary")
# ;

Overrides the runtime-determined display name of the program for help and error messages.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("My Program")
     .display_name("my_program")
# ;

Sets the author(s) for the help message.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
     .author("Me, me@mymain.com")
# ;

Sets the program's description for the short help (-h).

If Command::long_about is not specified, this message will be displayed for --help.

See also crate_description!.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .about("Does really amazing things for great people")
# ;

Sets the program's description for the long help (--help).

If not set, Command::about will be used for long help in addition to short help (-h).

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .long_about(
"Does really amazing things to great people. Now let's talk a little
 more in depth about how this subcommand really works. It may take about
 a few lines of text, but that's ok!")
# ;

Free-form help text for after auto-generated short help (-h).

This is often used to describe how to use the arguments, caveats to be noted, or license and contact information.

If Command::after_long_help is not specified, this message will be displayed for --help.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .after_help("Does really amazing things for great people... but be careful with -R!")
# ;

Free-form help text for after auto-generated long help (--help).

This is often used to describe how to use the arguments, caveats to be noted, or license and contact information.

If not set, Command::after_help will be used for long help in addition to short help (-h).

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .after_long_help("Does really amazing things to great people... but be careful with -R, \
                     like, for real, be careful with this!")
# ;

Free-form help text for before auto-generated short help (-h).

This is often used for header, copyright, or license information.

If Command::before_long_help is not specified, this message will be displayed for --help.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .before_help("Some info I'd like to appear before the help info")
# ;

Free-form help text for before auto-generated long help (--help).

This is often used for header, copyright, or license information.

If not set, Command::before_help will be used for long help in addition to short help (-h).

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .before_long_help("Some verbose and long info I'd like to appear before the help info")
# ;

Sets the version for the short version (-V) and help messages.

If Command::long_version is not specified, this message will be displayed for --version.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .version("v0.1.24")
# ;

Sets the version for the long version (--version) and help messages.

If Command::version is not specified, this message will be displayed for -V.

Examples

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .long_version(
"v0.1.24
 commit: abcdef89726d
 revision: 123
 release: 2
 binary: myprog")
# ;

Overrides the clap generated usage string for help and error messages.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .override_usage("myapp [-clDas] <some_file>")
# ;

Or for multiple usage lines:

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myprog")
    .override_usage(
        "myapp -X [-a] [-b] <file>\n       \
         myapp -Y [-c] <file1> <file2>\n       \
         myapp -Z [-d|-e]"
    )
# ;

Overrides the clap generated help message (both -h and --help).

This should only be used when the auto-generated message does not suffice.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Command::new("myapp")
    .override_help("myapp v1.0\n\
           Does awesome things\n\
           (C) me@mail.com\n\n\

           Usage: myapp <opts> <command>\n\n\

           Options:\n\
           -h, --help       Display this message\n\
           -V, --version    Display version info\n\
           -s <stuff>       Do something with stuff\n\
           -v               Be verbose\n\n\

           Commands:\n\
           help             Print this message\n\
           work             Do some work")
# ;

Sets the help template to be used, overriding the default format.

Tags are given inside curly brackets.

Valid tags are:

• {name} - Display name for the (sub-)command.
• {bin} - Binary name.(deprecated)
• {version} - Version number.
• {author} - Author information.
• {author-with-newline} - Author followed by \n.
• {author-section} - Author preceded and followed by \n.
• {about} - General description (from Command::about or Command::long_about).
• {about-with-newline} - About followed by \n.
• {about-section} - About preceded and followed by '\n'.
• {usage-heading} - Automatically generated usage heading.
• {usage} - Automatically generated or given usage string.
• {all-args} - Help for all arguments (options, flags, positional arguments, and subcommands) including titles.
• {options} - Help for options.
• {positionals} - Help for positional arguments.
• {subcommands} - Help for subcommands.
• {tab} - Standard tab sized used within clap
• {after-help} - Help from Command::after_help or Command::after_long_help.
• {before-help} - Help from Command::before_help or Command::before_long_help.

Examples

For a very brief help:

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .version("1.0")
    .help_template("{name} ({version}) - {usage}")
# ;

For showing more application context:

# use clap_builder as clap;
# use clap::Command;
Command::new("myprog")
    .version("1.0")
    .help_template("\
{before-help}{name} {version}
{author-with-newline}{about-with-newline}
{usage-heading} {usage}

{all-args}{after-help}
")
# ;

Flatten subcommand help into the current command's help

This shows a summary of subcommands within the usage and help for the current command, similar to git stash --help showing information on push, pop, etc. To see more information, a user can still pass --help to the individual subcommands.

Set the default section heading for future args.

This will be used for any arg that hasn't had Arg::help_heading called.

This is useful if the default Options or Arguments headings are not specific enough for one's use case.

For subcommands, see Command::subcommand_help_heading

Change the starting value for assigning future display orders for args.

This will be used for any arg that hasn't had Arg::display_order called.

Exit gracefully if no arguments are present (e.g. $ myprog).

Examples

# use clap_builder as clap;
# use clap::{Command};
Command::new("myprog")
    .arg_required_else_help(true);

Allows one to implement two styles of CLIs where positionals can be used out of order.

The first example is a CLI where the second to last positional argument is optional, but the final positional argument is required. Such as $ prog [optional] <required> where one of the two following usages is allowed:

• $ prog [optional] <required>
• $ prog <required>

This would otherwise not be allowed. This is useful when [optional] has a default value.

Note: when using this style of "missing positionals" the final positional must be required if -- will not be used to skip to the final positional argument.

Note: This style also only allows a single positional argument to be "skipped" without the use of --. To skip more than one, see the second example.

The second example is when one wants to skip multiple optional positional arguments, and use of the -- operator is OK (but not required if all arguments will be specified anyways).

For example, imagine a CLI which has three positional arguments [foo] [bar] [baz]... where baz accepts multiple values (similar to man ARGS... style training arguments).

With this setting the following invocations are possible:

• $ prog foo bar baz1 baz2 baz3
• $ prog foo -- baz1 baz2 baz3
• $ prog -- baz1 baz2 baz3

Examples

Style number one from above:

# use clap_builder as clap;
# use clap::{Command, Arg};
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_missing_positional(true)
    .arg(Arg::new("arg1"))
    .arg(Arg::new("arg2")
        .required(true))
    .get_matches_from(vec![
        "prog", "other"
    ]);

assert_eq!(m.get_one::<String>("arg1"), None);
assert_eq!(m.get_one::<String>("arg2").unwrap(), "other");

Now the same example, but using a default value for the first optional positional argument

# use clap_builder as clap;
# use clap::{Command, Arg};
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_missing_positional(true)
    .arg(Arg::new("arg1")
        .default_value("something"))
    .arg(Arg::new("arg2")
        .required(true))
    .get_matches_from(vec![
        "prog", "other"
    ]);

assert_eq!(m.get_one::<String>("arg1").unwrap(), "something");
assert_eq!(m.get_one::<String>("arg2").unwrap(), "other");

Style number two from above:

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_missing_positional(true)
    .arg(Arg::new("foo"))
    .arg(Arg::new("bar"))
    .arg(Arg::new("baz").action(ArgAction::Set).num_args(1..))
    .get_matches_from(vec![
        "prog", "foo", "bar", "baz1", "baz2", "baz3"
    ]);

assert_eq!(m.get_one::<String>("foo").unwrap(), "foo");
assert_eq!(m.get_one::<String>("bar").unwrap(), "bar");
assert_eq!(m.get_many::<String>("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);

Now nofice if we don't specify foo or baz but use the -- operator.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
// Assume there is an external subcommand named "subcmd"
let m = Command::new("myprog")
    .allow_missing_positional(true)
    .arg(Arg::new("foo"))
    .arg(Arg::new("bar"))
    .arg(Arg::new("baz").action(ArgAction::Set).num_args(1..))
    .get_matches_from(vec![
        "prog", "--", "baz1", "baz2", "baz3"
    ]);

assert_eq!(m.get_one::<String>("foo"), None);
assert_eq!(m.get_one::<String>("bar"), None);
assert_eq!(m.get_many::<String>("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);

Get the name of the binary.

Get the name of the binary.

Set binary name. Uses &mut self instead of self.

Get the name of the cmd.

Get all known names of the cmd (i.e. primary name and visible aliases).

Get the version of the cmd.

Get the long version of the cmd.

Get the placement within help

Get the authors of the cmd.

Get the short flag of the subcommand.

Get the long flag of the subcommand.

Get the help message specified via Command::about.