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

<details><summary>The major CLI parsers for C++ include, with my biased opinions: (click to expand)</summary><p>

| 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