Example programs

The examples/ directory holds small, complete programs. Each one builds and runs on its own, so you can copy a file into your project and change it. Build them with the CLI11_BUILD_EXAMPLES CMake option, which is on by default when CLI11 is the top level project.

Read Making a git clone for a step by step walkthrough of a larger program.

Start here

minimal.cpp is the smallest program that parses and exits correctly. Use it as a starting point for a new application:

// Copyright (c) 2017-2026, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause
 
// Code modified from https://github.com/CLIUtils/CLI11/issues/1334
 
#include <CLI/CLI.hpp>

int main(int argc, char **argv) {
 
    CLI::App app{"App description"};
    CLI11_PARSE(app, argc, argv);
    return 0;
}

simple.cpp adds options, a flag, and a version flag, and shows how to read the values and the counts back after the parse:

// Copyright (c) 2017-2026, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause
 
#include <CLI/CLI.hpp>
#include <iostream>
#include <string>
 
int main(int argc, char **argv) {
 
    CLI::App app("K3Pi goofit fitter");
    // add version output
    app.set_version_flag("--version", std::string(CLI11_VERSION));
    std::string file;
    CLI::Option *opt = app.add_option("-f,--file,file", file, "File name");
 
    int count{0};
    CLI::Option *copt = app.add_option("-c,--count", count, "Counter");
 
    int v{0};
    CLI::Option *flag = app.add_flag("--flag", v, "Some flag that can be passed multiple times");
 
    double value{0.0};  // = 3.14;
    app.add_option("-d,--double", value, "Some Value");
 
    CLI11_PARSE(app, argc, argv);
 
    std::cout << "Working on file: " << file << ", direct count: " << app.count("--file")
              << ", opt count: " << opt->count() << '\n';
    std::cout << "Working on count: " << count << ", direct count: " << app.count("--count")
              << ", opt count: " << copt->count() << '\n';
    std::cout << "Received flag: " << v << " (" << flag->count() << ") times\n";
    std::cout << "Some value: " << value << '\n';
 
    return 0;
}

Options and flags

Example	Shows
array_option.cpp	An option that fills a std::array
digit_args.cpp	Numbered flags (-1 to -9) with values attached
enum.cpp	An option that takes an enum class value
enum_ostream.cpp	A custom operator<< for an enum class in help and errors
ranges.cpp	Options that accept a range of values
retired.cpp	Retired and deprecated options
inter_argument_order.cpp	Recovery of the original order of unlimited arguments
custom_parse.cpp	A custom lexical cast for a user type

Validators

Example	Shows
validators.cpp	The built in ExistingFile and Range validators
custom_validator.cpp	A CLI::Validator subclass
date_validator.cpp	A CLI::CustomValidator built from a lambda
positional_validation.cpp	Validators that select between positionals

Subcommands and groups

Example	Shows
subcommands.cpp	Basic subcommands and --help-all
subcom_help.cpp	A required argument on a subcommand
subcom_partitioned.cpp	Subcommands built as separate CLI::App_p objects
subcom_in_files	A subcommand defined in its own source and header file
shapes.cpp	Repeated subcommands with immediate callbacks
nested.cpp	Nested subcommands
groups.cpp	Help groups
option_groups.cpp	Option groups and the requirements between them
positional_arity.cpp	Option groups that select on the number of positionals

Help output

Example	Shows
formatter.cpp	A CLI::Formatter subclass
help_usage.cpp	A custom usage line and wide character support
modhelp.cpp	Help printed after the parse, with option values
close_match.cpp	A "did you mean" message for an unknown option

Configuration files

Example	Shows
config_app.cpp	Reading a configuration file and printing the result
json.cpp	A JSON configuration file, with nlohmann/json as the parser

Passing arguments on

Example	Shows
prefix_command.cpp	prefix_command on the main application
arg_capture.cpp	prefix_command on a subcommand, with an alias
callback_passthrough.cpp	A callback that parses the remaining arguments
testEXE.cpp	Arguments collected for another program