A flag does not take a value. An option takes a value and converts it to its declared C++ type.

Flags

Register a flag with a long name and an optional one-character alias.

auto quiet = example.flag("quiet", 'q', "Suppress normal output");

auto dry_run = example.flag("dry-run");

The description is optional. A flag without a description remains parseable and is listed in generated help without explanatory text.

Both --quiet and -q set the first flag. Read flags with args::get. An absent flag returns false.

auto arguments = example.parse(argc, argv);
 
if (arguments.get(quiet)) {
    // Suppress output.
}

Flags do not accept values. For example, --quiet=true is rejected.

Typed Options

The option template argument defines the parsed value type. The value name is used as a placeholder in help and error output.

auto jobs = example.option<int>("jobs", 'j', "COUNT", "Number of parallel jobs");

auto output = example.option<std::string>("output", "FILE", "Output file");

The parser accepts long option values as the next argument or after =. Short option values are read from the next argument.

example --jobs 4
example --jobs=4
example -j 4

Grouped short flags such as -qv and attached short option values such as -j4 are rejected. Write them as separate arguments instead.

Defaults and Optional Values

Set a default through the returned handle. Handle configuration methods return the handle again, so the configured handle can be stored directly.

auto jobs = example.option<int>("jobs", 'j', "COUNT", "Number of parallel jobs").default_value(1);

An option with a default is always available through args::get. For an option without a default, check args::has before reading it.

if (arguments.has(output)) {
    write_to(arguments.get(output));
}
 
auto const job_count = arguments.get(jobs);

Generated help appends the rendered default value to the option description:

-j, --jobs <COUNT> Number of parallel jobs (default: 1)

An ordinary option may occur only once. Repeating it is reported as a parsing error.

Required Options

Use required() when an option must be specified explicitly. Required options are included directly in generated usage text and marked as required in the detailed help output.

auto email = example.option<std::string>("email", "EMAIL", "Email address").required();

For example, the generated help contains:

Usage: example --email <EMAIL>
 
      --email <EMAIL>   Email address (required)

Required option validation is delayed until args::validate() is called. This allows the application to handle actions such as help and version before missing required input is reported.

auto arguments = example.parse(argc, argv);
 
if (arguments.get(help)) {
    return arguments.selected_command().print_help();
}
 
arguments.validate();

When a required option is missing, validation reports Missing option --email <EMAIL>. A required option cannot also have a default value; combining required() and default_value() in either order throws std::invalid_argument while configuring the command.

Repeatable Options

Use repeatable_option when the same option may occur multiple times. Its handle reads all converted values as a vector in command-line order.

auto include = example.repeatable_option<std::string>("include", 'I', "PATH", "Additional include path");
 
auto arguments = example.parse(argc, argv);
auto const& include_paths = arguments.get(include);

For example, --include first -I second --include=third produces std::vector<std::string>{ "first", "second", "third" }. An absent repeatable option is unavailable through args::get unless it has a default value.

A repeatable option can also be required. It must then occur at least once and may still occur additional times.

auto include = example.repeatable_option<std::string>("include", 'I', "PATH").required();

Actions

Mark flags and options that select alternative command actions with action(). At most one explicitly specified action may occur on a command line. Omitting all actions is valid and lets the application perform its default action.

auto help = example.flag("help", 'h', "Show help").action();
auto version = example.flag("version", 'V', "Show version information").action();
auto list = example.flag("list", "List entries").action();
auto show = example.option<std::string>("show", "NAME", "Show one entry").action();

Normal switches are not part of this restriction and may be combined with an action. Default option values do not select an action. Only an action explicitly present on the command line participates in the exclusivity check.

Parent Switches

Flags and options remain available after selecting descendant commands. This allows application-wide and command-wide switches to appear anywhere after the command on which they are defined.

example --color auto login --verbose

example login --color auto --verbose

In both forms, --color belongs to example and --verbose belongs to login. A child switch cannot appear before its command because that command has not been selected yet.

Help for a command lists its own switches followed by switches from its ancestors. Required and optional parent options follow the same scope rules. Defaults and required-option validation apply only along the selected command path.

A command cannot define a long switch name or short alias already used by an ancestor or descendant because its meaning would otherwise depend on its position. Sibling commands may reuse switch names because only one sibling can be selected.