CLI11: Command line parser for C++11

[![Build Status Azure][azure-badge]][azure] [![Actions Status][actions-badge]][actions-link] [![Code Coverage][codecov-badge]][codecov] [![Codacy Badge][codacy-badge]][codacy-link] ![License: BSD][license-badge] [![DOI][doi-badge]][doi-link]

[![Gitter chat][gitter-badge]][gitter] [![Latest GHA release][releases-badge]][github releases] [![Latest release][repology-badge]][repology] [![Conan.io][conan-badge]][conan-link] [![Conda Version][conda-badge]][conda-link] [![Try CLI11 2.4 online][wandbox-badge]][wandbox-link]

What's new • [Documentation][gitbook] • [API Reference][api-docs]

CLI11 is a command line parser for C++11 and beyond that provides a rich feature set with a simple and intuitive interface.

Table of Contents

• CLI11: Command line parser for C++11
• Table of Contents
• Background
  • Introduction
  • Why write another CLI parser?
  • Other parsers
  • Features not supported by this library
• Install
• Usage
  • Adding options
  • Option types
  • Example
  • Option options
  • Validators
  • Default Validators
  • Validators that may be disabled 🆕
  • Extra Validators 🆕
  • Validator Usage
    • Transforming Validators
    • Validator operations
    • Custom Validators
    • Querying Validators
  • Getting results
  • Subcommands
  • Subcommand options
  • Callbacks
  • Option groups
  • Configuration file
  • Inheriting defaults
  • Formatting
  • Subclassing
  • How it works
  • Unicode support
  • Note on using Unicode paths
  • Utilities
  • Other libraries
• API
• Examples
• Contribute
• License

Features that were added in the last released minor version are marked with "🆕". Features only available in main are marked with "🚧".

Background

Introduction

CLI11 provides all the features you expect in a powerful command line parser, with a beautiful, minimal syntax and no dependencies beyond C++11. It is header-only, and comes in a single file form for easy inclusion in projects. It is easy to use for small projects, but powerful enough for complex command line projects, and can be customized for frameworks. It is tested on [Azure][] and [GitHub Actions][actions-link], and was originally used by the [GooFit GPU fitting framework][goofit]. It was inspired by [plumbum.cli][plumbum] for Python. CLI11 has a user-friendly introduction in this README, a more in-depth tutorial [GitBook][], as well as [API documentation][api-docs] generated by Travis. See the changelog or [GitHub Releases][] for details on current and past releases. Also see the [Version 1.0 post][], [Version 1.3 post][], [Version 1.6 post][], or [Version 2.0 post][] for more information.

You can be notified when new releases are made by subscribing to https://github.com/CLIUtils/CLI11/releases.atom on an RSS reader, like Feedly, or use the releases mode of the GitHub watching tool.

Why write another CLI parser?

An acceptable CLI parser library should be all of the following:

• Easy to include (i.e., header only, one file if possible, no external requirements).
• Short, simple syntax: This is one of the main reasons to use a CLI parser, it should make variables from the command line nearly as easy to define as any other variables. If most of your program is hidden in CLI parsing, this is a problem for readability.
• C++11 or better: Should work with GCC 4.8+ (default on CentOS/RHEL 7), Clang 3.4+, AppleClang 7+, NVCC 7.0+, or MSVC 2015+.
• Work on Linux, macOS, and Windows.
• Well tested on all common platforms and compilers. "Well" is defined as having good coverage measured by [CodeCov][].
• Clear help printing.
• Nice error messages.
• Standard shell idioms supported naturally, like grouping flags, a positional separator, etc.
• Easy to execute, with help, parse errors, etc. providing correct exit and details.
• Easy to extend as part of a framework that provides "applications" to users.
• Usable subcommand syntax, with support for multiple subcommands, nested subcommands, option groups, and optional fallthrough (explained later).
• Ability to add a configuration file (TOML, INI, or custom format), and produce it as well.
• Produce real values that can be used directly in code, not something you have to pay compute time to look up, for HPC applications.
• Work with common types, simple custom types, and extensible to exotic types.
• Permissively licensed.

Other parsers

The major CLI parsers for C++ include, with my biased opinions: (click to expand)

Library	My biased opinion
[Boost Program Options][]	A great library if you already depend on Boost, but its pre-C++11 syntax is really odd and setting up the correct call in the main function is poorly documented (and is nearly a page of code). A simple wrapper for the Boost library was originally developed, but was discarded as CLI11 became more powerful. The idea of capturing a value and setting it originated with Boost PO. [See this comparison.][cli11-po-compare]
[The Lean Mean C++ Option Parser][]	One header file is great, but the syntax is atrocious, in my opinion. It was quite impractical to wrap the syntax or to use in a complex project. It seems to handle standard parsing quite well.
[TCLAP][]	The not-quite-standard command line parsing causes common shortcuts to fail. It also seems to be poorly supported, with only minimal bugfixes accepted. Header only, but in quite a few files. Has not managed to get enough support to move to GitHub yet. No subcommands. Produces wrapped values.
[Cxxopts][]	C++11, single file, and nice CMake support, but requires regex, therefore GCC 4.8 (CentOS 7 default) does not work. Syntax closely based on Boost PO, so not ideal but familiar.
[DocOpt][]	Completely different approach to program options in C++11, you write the docs and the interface is generated. Too fragile and specialized.

After I wrote this, I also found the following libraries:

Library	My biased opinion
[GFlags][]	The Google Commandline Flags library. Uses macros heavily, and is limited in scope, missing things like subcommands. It provides a simple syntax and supports config files/env vars.
[GetOpt][]	Very limited C solution with long, convoluted syntax. Does not support much of anything, like help generation. Always available on UNIX, though (but in different flavors).
[ProgramOptions.hxx][]	Interesting library, less powerful and no subcommands. Nice callback system.
[Args][]	Also interesting, and supports subcommands. I like the optional-like design, but CLI11 is cleaner and provides direct value access, and is less verbose.
[Argument Aggregator][]	I'm a big fan of the [fmt][] library, and the try-catch statement looks familiar. :thumbsup: Doesn't seem to support subcommands.
[Clara][]	Simple library built for the excellent [Catch][] testing framework. Unique syntax, limited scope.
[Argh!][]	Very minimalistic C++11 parser, single header. Don't have many features. No help generation?!?! At least it's exception-free.
[CLI][]	Custom language and parser. Huge build-system overkill for very little benefit. Last release in 2009, but still occasionally active.
[argparse][]	C++17 single file argument parser. Design seems similar to CLI11 in some ways. The author has several other interesting projects.
[lyra][]	a simple header only parser with composable options. Might work well for simple standardized parsing

See [Awesome C++][] for a less-biased list of parsers. You can also find other single file libraries at [Single file libs][].

None of these libraries fulfill all the above requirements, or really even come close. As you probably have already guessed, CLI11 does. So, this library was designed to provide a great syntax, good compiler compatibility, and minimal installation fuss.

Features not supported by this library

There are some other possible "features" that are intentionally not supported by this library:

• Completion of partial options, such as Python's argparse supplies for incomplete arguments. It's better not to guess. Most third party command line parsers for python actually reimplement command line parsing rather than using argparse because of this perceived design flaw (recent versions do have an option to disable it). Recent releases of CLI11 do include partial option matching for option prefixes 🆕. This is enabled by .allow_subcommand_prefix_matching(), along with an example that generates suggested close matches.
• Autocomplete: This might eventually be added to both Plumbum and CLI11, but it is not supported yet.
• While not recommended, CLI11 does now support non-standard option names such as -option. This is enabled through allow_non_standard_option_names() modifier on an app.

Install

To use, the most common methods are described here, additional methods and details are available at [installation][]:

• All-in-one local header: Copy CLI11.hpp from the [most recent release][github releases] into your include directory, and you are set. This is combined from the source files for every release. This includes the entire command parser library, but does not include separate utilities (like Timer, AutoTimer). The utilities are completely self-contained and can be copied separately.
• All-in-one global header: Like above, but copying the file to a shared folder location like /opt/CLI11. Then, the C++ include path has to be extended to point at this folder. With CMake 3.10+, use include_directories(/opt/CLI11)
• For other methods including using CMake, conan or vcpkg and some specific instructions for GCC 8 or WASI see [installation][].

Usage

Adding options

To set up, add options, and run, your main function will look something like this:

```cpp int main(int argc, char** argv) { CLI::App app{"App description"}; argv = app.ensure_utf8(argv);

std::string filename = "default";
app.add_option("-f,--file", filename, "A help string");

CLI11_PARSE(app, argc, arg