The name of the ArgGroup the argument belongs to.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
Arg::new("debug")
    .long("debug")
    .action(ArgAction::SetTrue)
    .group("mode")
# ;

Multiple arguments can be a member of a single group and then the group checked as if it was one of said arguments.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("debug")
        .long("debug")
        .action(ArgAction::SetTrue)
        .group("mode"))
    .arg(Arg::new("verbose")
        .long("verbose")
        .action(ArgAction::SetTrue)
        .group("mode"))
    .get_matches_from(vec![
        "prog", "--debug"
    ]);
assert!(m.contains_id("mode"));

The names of ArgGroup's the argument belongs to.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
Arg::new("debug")
    .long("debug")
    .action(ArgAction::SetTrue)
    .groups(["mode", "verbosity"])
# ;

Arguments can be members of multiple groups and then the group checked as if it was one of said arguments.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("debug")
        .long("debug")
        .action(ArgAction::SetTrue)
        .groups(["mode", "verbosity"]))
    .arg(Arg::new("verbose")
        .long("verbose")
        .action(ArgAction::SetTrue)
        .groups(["mode", "verbosity"]))
    .get_matches_from(vec![
        "prog", "--debug"
    ]);
assert!(m.contains_id("mode"));
assert!(m.contains_id("verbosity"));

Specifies the value of the argument if arg has been used at runtime.

If default is set to None, default_value will be removed.

Like with command-line values, this will be split by Arg::value_delimiter.

Examples

First we use the default value only if another arg is present at runtime.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
# use clap::builder::{ArgPredicate};
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("flag", ArgPredicate::IsPresent, Some("default")))
    .get_matches_from(vec![
        "prog", "--flag"
    ]);

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

Next we run the same test, but without providing --flag.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("flag", "true", Some("default")))
    .get_matches_from(vec![
        "prog"
    ]);

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

Now lets only use the default value if --opt contains the value special.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("opt")
        .action(ArgAction::Set)
        .long("opt"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("opt", "special", Some("default")))
    .get_matches_from(vec![
        "prog", "--opt", "special"
    ]);

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

We can run the same test and provide any value other than special and we won't get a default value.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("opt")
        .action(ArgAction::Set)
        .long("opt"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("opt", "special", Some("default")))
    .get_matches_from(vec![
        "prog", "--opt", "hahaha"
    ]);

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

If we want to unset the default value for an Arg based on the presence or value of some other Arg.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("other")
        .long("other")
        .default_value("default")
        .default_value_if("flag", "true", None))
    .get_matches_from(vec![
        "prog", "--flag"
    ]);

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

Specifies multiple values and conditions in the same manner as Arg::default_value_if.

The method takes a slice of tuples in the (arg, predicate, default) format.

Like with command-line values, this will be split by Arg::value_delimiter.

Examples

First we use the default value only if another arg is present at runtime.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("opt")
        .long("opt")
        .action(ArgAction::Set))
    .arg(Arg::new("other")
        .long("other")
        .default_value_ifs([
            ("flag", "true", Some("default")),
            ("opt", "channal", Some("chan")),
        ]))
    .get_matches_from(vec![
        "prog", "--opt", "channal"
    ]);

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

Next we run the same test, but without providing --flag.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("other")
        .long("other")
        .default_value_ifs([
            ("flag", "true", Some("default")),
            ("opt", "channal", Some("chan")),
        ]))
    .get_matches_from(vec![
        "prog"
    ]);

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

We can also see that these values are applied in order, and if more than one condition is true, only the first evaluated "wins"

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
# use clap::builder::ArgPredicate;
let m = Command::new("prog")
    .arg(Arg::new("flag")
        .long("flag")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("opt")
        .long("opt")
        .action(ArgAction::Set))
    .arg(Arg::new("other")
        .long("other")
        .default_value_ifs([
            ("flag", ArgPredicate::IsPresent, Some("default")),
            ("opt", ArgPredicate::Equals("channal".into()), Some("chan")),
        ]))
    .get_matches_from(vec![
        "prog", "--opt", "channal", "--flag"
    ]);

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

Set this arg as required as long as the specified argument is not present at runtime.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_unless_present("debug")
# ;

In the following example, the required argument is not provided, but it's not an error because the unless arg has been supplied.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present("dbg")
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug")
        .action(ArgAction::SetTrue))
    .try_get_matches_from(vec![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

Setting Arg::required_unless_present(name) and not supplying name or this arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present("dbg")
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .try_get_matches_from(vec![
        "prog"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Sets this arg as required unless all of the specified arguments are present at runtime.

In other words, parsing will succeed only if user either

• supplies the self arg.
• supplies all of the names arguments.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_unless_present_all(["cfg", "dbg"])
# ;

In the following example, the required argument is not provided, but it's not an error because all of the names args have been supplied.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_all(["dbg", "infile"])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("infile")
        .short('i')
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--debug", "-i", "file"
    ]);

assert!(res.is_ok());

Setting Arg::required_unless_present_all(names) and not supplying either all of unless args or the self arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_all(["dbg", "infile"])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("infile")
        .short('i')
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Sets this arg as required unless any of the specified arguments are present at runtime.

In other words, parsing will succeed only if user either

• supplies the self arg.
• supplies one or more of the unless arguments.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_unless_present_any(["cfg", "dbg"])
# ;

Setting Arg::required_unless_present_any(names) requires that the argument be used at runtime unless at least one of the args in names are present. In the following example, the required argument is not provided, but it's not an error because one the unless args have been supplied.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_any(["dbg", "infile"])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("infile")
        .short('i')
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

Setting Arg::required_unless_present_any(names) and not supplying at least one of names or this arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_any(["dbg", "infile"])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug")
        .action(ArgAction::SetTrue))
    .arg(Arg::new("infile")
        .short('i')
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

This argument is required only if the specified arg is present at runtime and its value equals val.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_if_eq("other_arg", "value")
# ;

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .required_if_eq("other", "special")
        .long("config"))
    .arg(Arg::new("other")
        .long("other")
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--other", "not-special"
    ]);

assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required

let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .required_if_eq("other", "special")
        .long("config"))
    .arg(Arg::new("other")
        .long("other")
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--other", "special"
    ]);

// We did use --other=special so "cfg" had become required but was missing.
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .required_if_eq("other", "special")
        .long("config"))
    .arg(Arg::new("other")
        .long("other")
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--other", "SPECIAL"
    ]);

// By default, the comparison is case-sensitive, so "cfg" wasn't required
assert!(res.is_ok());

let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .required_if_eq("other", "special")
        .long("config"))
    .arg(Arg::new("other")
        .long("other")
        .ignore_case(true)
        .action(ArgAction::Set))
    .try_get_matches_from(vec![
        "prog", "--other", "SPECIAL"
    ]);

// However, case-insensitive comparisons can be enabled.  This typically occurs when using Arg::possible_values().
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Specify this argument is required based on multiple conditions.

The conditions are set up in a (arg, val) style tuple. The requirement will only become valid if one of the specified arg's value equals its corresponding val.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_if_eq_any([
        ("extra", "val"),
        ("option", "spec")
    ])
# ;

Setting Arg::required_if_eq_any([(arg, val)]) makes this arg required if any of the args are used at runtime and it's corresponding value is equal to val. If the arg's value is anything other than val, this argument isn't required.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_if_eq_any([
            ("extra", "val"),
            ("option", "spec")
        ])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("extra")
        .action(ArgAction::Set)
        .long("extra"))
    .arg(Arg::new("option")
        .action(ArgAction::Set)
        .long("option"))
    .try_get_matches_from(vec![
        "prog", "--option", "other"
    ]);

assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required

Setting Arg::required_if_eq_any([(arg, val)]) and having any of the args used with its value of val but not using this arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_if_eq_any([
            ("extra", "val"),
            ("option", "spec")
        ])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("extra")
        .action(ArgAction::Set)
        .long("extra"))
    .arg(Arg::new("option")
        .action(ArgAction::Set)
        .long("option"))
    .try_get_matches_from(vec![
        "prog", "--option", "spec"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Specify this argument is required based on multiple conditions.

The conditions are set up in a (arg, val) style tuple. The requirement will only become valid if every one of the specified arg's value equals its corresponding val.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .required_if_eq_all([
        ("extra", "val"),
        ("option", "spec")
    ])
# ;

Setting Arg::required_if_eq_all([(arg, val)]) makes this arg required if all of the args are used at runtime and every value is equal to its corresponding val. If the arg's value is anything other than val, this argument isn't required.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_if_eq_all([
            ("extra", "val"),
            ("option", "spec")
        ])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("extra")
        .action(ArgAction::Set)
        .long("extra"))
    .arg(Arg::new("option")
        .action(ArgAction::Set)
        .long("option"))
    .try_get_matches_from(vec![
        "prog", "--option", "spec"
    ]);

assert!(res.is_ok()); // We didn't use --option=spec --extra=val so "cfg" isn't required

Setting Arg::required_if_eq_all([(arg, val)]) and having all of the args used with its value of val but not using this arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .required_if_eq_all([
            ("extra", "val"),
            ("option", "spec")
        ])
        .action(ArgAction::Set)
        .long("config"))
    .arg(Arg::new("extra")
        .action(ArgAction::Set)
        .long("extra"))
    .arg(Arg::new("option")
        .action(ArgAction::Set)
        .long("option"))
    .try_get_matches_from(vec![
        "prog", "--extra", "val", "--option", "spec"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Require another argument if this arg matches the ArgPredicate

This method takes value, another_arg pair. At runtime, clap will check if this arg (self) matches the ArgPredicate. If it does, another_arg will be marked as required.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .requires_if("val", "arg")
# ;

Setting Arg::requires_if(val, arg) requires that the arg be used at runtime if the defining argument's value is equal to val. If the defining argument is anything other than val, the other argument isn't required.

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .requires_if("my.cfg", "other")
        .long("config"))
    .arg(Arg::new("other"))
    .try_get_matches_from(vec![
        "prog", "--config", "some.cfg"
    ]);

assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required

Setting Arg::requires_if(val, arg) and setting the value to val but not supplying arg is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .requires_if("my.cfg", "input")
        .long("config"))
    .arg(Arg::new("input"))
    .try_get_matches_from(vec![
        "prog", "--config", "my.cfg"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Allows multiple conditional requirements.

The requirement will only become valid if this arg's value matches the ArgPredicate.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .requires_ifs([
        ("val", "arg"),
        ("other_val", "arg2"),
    ])
# ;

Setting Arg::requires_ifs(["val", "arg"]) requires that the arg be used at runtime if the defining argument's value is equal to val. If the defining argument's value is anything other than val, arg isn't required.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .requires_ifs([
            ("special.conf", "opt"),
            ("other.conf", "other"),
        ])
        .long("config"))
    .arg(Arg::new("opt")
        .long("option")
        .action(ArgAction::Set))
    .arg(Arg::new("other"))
    .try_get_matches_from(vec![
        "prog", "--config", "special.conf"
    ]);

assert!(res.is_err()); // We  used --config=special.conf so --option <val> is required
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

Setting Arg::requires_ifs with ArgPredicate::IsPresent and not supplying all the arguments is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction, builder::ArgPredicate};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .requires_ifs([
            (ArgPredicate::IsPresent, "input"),
            (ArgPredicate::IsPresent, "output"),
        ])
        .long("config"))
    .arg(Arg::new("input"))
    .arg(Arg::new("output"))
    .try_get_matches_from(vec![
        "prog", "--config", "file.conf", "in.txt"
    ]);

assert!(res.is_err());
// We didn't use output
assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

This argument is mutually exclusive with the specified argument.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .conflicts_with("debug")
# ;

Setting conflicting argument, and having both arguments present at runtime is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .conflicts_with("debug")
        .long("config"))
    .arg(Arg::new("debug")
        .long("debug")
        .action(ArgAction::SetTrue))
    .try_get_matches_from(vec![
        "prog", "--debug", "--config", "file.conf"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);

This argument is mutually exclusive with the specified arguments.

See Arg::conflicts_with.

Examples

# use clap_builder as clap;
# use clap::Arg;
Arg::new("config")
    .conflicts_with_all(["debug", "input"])
# ;

Setting conflicting argument, and having any of the arguments present at runtime with a conflicting argument is an error.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("cfg")
        .action(ArgAction::Set)
        .conflicts_with_all(["debug", "input"])
        .long("config"))
    .arg(Arg::new("debug")
        .long("debug"))
    .arg(Arg::new("input"))
    .try_get_matches_from(vec![
        "prog", "--config", "file.conf", "file.txt"
    ]);

assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);

Sets an overridable argument.

i.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")

Examples

# use clap_builder as clap;
# use clap::{Command, arg};
let m = Command::new("prog")
    .arg(arg!(-f --flag "some flag")
        .conflicts_with("debug"))
    .arg(arg!(-d --debug "other flag"))
    .arg(arg!(-c --color "third flag")
        .overrides_with("flag"))
    .get_matches_from(vec![
        "prog", "-f", "-d", "-c"]);
            //    ^~~~~~~~~~~~^~~~~ flag is overridden by color

assert!(m.get_flag("color"));
assert!(m.get_flag("debug")); // even though flag conflicts with debug, it's as if flag
                                // was never used because it was overridden with color
assert!(!m.get_flag("flag"));

Sets multiple mutually overridable arguments by name.

i.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")

Examples

# use clap_builder as clap;
# use clap::{Command, arg};
let m = Command::new("prog")
    .arg(arg!(-f --flag "some flag")
        .conflicts_with("color"))
    .arg(arg!(-d --debug "other flag"))
    .arg(arg!(-c --color "third flag")
        .overrides_with_all(["flag", "debug"]))
    .get_matches_from(vec![
        "prog", "-f", "-d", "-c"]);
            //    ^~~~~~^~~~~~~~~ flag and debug are overridden by color

assert!(m.get_flag("color")); // even though flag conflicts with color, it's as if flag
                                // and debug were never used because they were overridden
                                // with color
assert!(!m.get_flag("debug"));
assert!(!m.get_flag("flag"));

Sets the description of the argument for short help (-h).

Typically, this is a short (one line) description of the arg.

If Arg::long_help is not specified, this message will be displayed for --help.

Examples

Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to include a newline in the help text and have the following text be properly aligned with all the other help text.

Setting help displays a short message to the side of the argument when the user passes -h or --help (by default).

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays

helptest

Usage: helptest [OPTIONS]

Options:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

Sets the description of the argument for long help (--help).

Typically this a more detailed (multi-line) message that describes the arg.

If Arg::help is not specified, this message will be displayed for -h.

Examples

Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to include a newline in the help text and have the following text be properly aligned with all the other help text.

Setting help displays a short message to the side of the argument when the user passes -h or --help (by default).

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .long_help(
"The config file used by the myprog must be in JSON format
with only valid keys and may not contain other nonsense
that cannot be read by this program. Obviously I'm going on
and on, so I'll stop now."))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays

prog

Usage: prog [OPTIONS]

Options:
        --config
            The config file used by the myprog must be in JSON format
            with only valid keys and may not contain other nonsense
            that cannot be read by this program. Obviously I'm going on
            and on, so I'll stop now.

    -h, --help
            Print help information

    -V, --version
            Print version information

Allows custom ordering of args within the help message.

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

Args are automatically assigned a display order based on the order they are added to the [Command][crate::Command]. Overriding this is helpful when the order arguments are added in isn't the same as the display order, whether in one-off cases or to automatically sort arguments.

To change, see [Command::next_display_order][crate::Command::next_display_order].

Examples

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("boat")
        .short('b')
        .long("boat")
        .action(ArgAction::Set)
        .display_order(0)  // Sort
        .help("Some help and text"))
    .arg(Arg::new("airplane")
        .short('a')
        .long("airplane")
        .action(ArgAction::Set)
        .display_order(0)  // Sort
        .help("I should be first!"))
    .arg(Arg::new("custom-help")
        .short('?')
        .action(ArgAction::Help)
        .display_order(100)  // Don't sort
        .help("Alt help"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays the following help message

cust-ord

Usage: cust-ord [OPTIONS]

Options:
    -a, --airplane <airplane>    I should be first!
    -b, --boat <boar>            Some help and text
    -h, --help                   Print help information
    -?                           Alt help

Override the current help section.

Render the [help][Arg::help] on the line after the argument.

This can be helpful for arguments with very long or complex help messages. This can also be helpful for arguments with very long flag names, or many/long value names.

Examples

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("opt")
        .long("long-option-flag")
        .short('o')
        .action(ArgAction::Set)
        .next_line_help(true)
        .value_names(["value1", "value2"])
        .help("Some really long help and complex\n\
               help that makes more sense to be\n\
               on a line after the option"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays the following help message

nlh

Usage: nlh [OPTIONS]

Options:
    -h, --help       Print help information
    -V, --version    Print version information
    -o, --long-option-flag <value1> <value2>
        Some really long help and complex
        help that makes more sense to be
        on a line after the option

Do not display the argument in help message.

Examples

Setting Hidden will hide the argument when displaying help text

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .hide(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays

helptest

Usage: helptest [OPTIONS]

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

Do not display the [possible values][crate::builder::ValueParser::possible_values] in the help message.

This is useful for args with many values, or ones which are explained elsewhere in the help text.

To set this for all arguments, see [Command::hide_possible_values][crate::Command::hide_possible_values].

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("mode")
        .long("mode")
        .value_parser(["fast", "slow"])
        .action(ArgAction::Set)
        .hide_possible_values(true));

If we were to run the above program with --help the [values: fast, slow] portion of the help text would be omitted.

Do not display the default value of the argument in the help message.

This is useful when default behavior of an arg is explained elsewhere in the help text.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, ArgAction};
let m = Command::new("connect")
    .arg(Arg::new("host")
        .long("host")
        .default_value("localhost")
        .action(ArgAction::Set)
        .hide_default_value(true));

If we were to run the above program with --help the [default: localhost] portion of the help text would be omitted.

Hides an argument from short help (-h).

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Arg::new("debug")
    .hide_short_help(true);

Setting hide_short_help(true) will hide the argument when displaying short help text

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .hide_short_help(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "-h"
    ]);
# }

The above example displays

helptest

Usage: helptest [OPTIONS]

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

However, when --help is called

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .hide_short_help(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

Then the following would be displayed

helptest

Usage: helptest [OPTIONS]

Options:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

Hides an argument from long help (--help).

Examples

Setting hide_long_help(true) will hide the argument when displaying long help text

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .hide_long_help(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
# }

The above example displays

helptest

Usage: helptest [OPTIONS]

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

However, when -h is called

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg};
let m = Command::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .hide_long_help(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "-h"
    ]);
# }

Then the following would be displayed

helptest

Usage: helptest [OPTIONS]

OPTIONS:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

Create a new Arg with a unique name.

The name is used to check whether or not the argument was used at runtime, get values, set relationships with other args, etc..

Examples

# use clap_builder as clap;
# use clap::{Command, Arg};
Arg::new("config")
# ;

Set the identifier used for referencing this argument in the clap API.

See Arg::new for more details.

Sets the short version of the argument without the preceding -.

By default V and h are used by the auto-generated version and help arguments, respectively. You will need to disable the auto-generated flags ([disable_help_flag][crate::Command::disable_help_flag], [disable_version_flag][crate::Command::disable_version_flag]) and define your own.

Examples

When calling short, use a single valid UTF-8 character which will allow using the argument via a single hyphen (-) such as -c:

# use clap_builder as clap;
# use clap::{Command, Arg,  ArgAction};
let m = Command::new("prog")
    .arg(Arg::new("config")
        .short('c')
        .action(ArgAction::Set))
    .get_matches_from(vec![
        "prog", "-c", "file.toml"
    ]);

assert_eq!(m.get_one::<String>("config").map(String::as_str), Some("file.toml"));

To use -h for your own flag and still have help:

# use clap_builder as clap;
# use clap::{Command, Arg,  ArgAction};
let m = Command::new("prog")
    .disable_help_flag(true)
    .arg(Arg::new("host")
        .short('h')
        .long("host"))
    .arg(Arg::new("help")
        .long("help")
        .global(true)
        .action(ArgAction::Help))
    .get_matches_from(vec![
        "prog", "-h", "wikipedia.org"
    ]);

assert_eq!(m.get_one::<String>("host").map(String::as_str), Some("wikipedia.org"));

Sets the long version of the argument without the preceding --.

By default version and help are used by the auto-generated version and help arguments, respectively. You may use the word version or help for the long form of your own arguments, in which case clap simply will not assign those to the auto-generated version or help arguments.