Installation

Single file edition

#include <CLI11.hpp>

This example uses the single file edition of CLI11. You can download CLI11.hpp from the latest release and put it into the same folder as your source code, then compile this with C++ enabled. For a larger project, you can just put this in an include folder and you are set. This is the simplest and most straightforward means of including CLI11 with a project.

Full edition

#include <CLI/CLI.hpp>

If you want to use CLI11 in its full form, you can also use the original multiple file edition. This has an extra utility (Timer), and is does not require that you use a release. The only change to your code would be the include shown above.

CMake support for the full edition

If you use CMake 3.5+ for your project (highly recommended), CLI11 comes with a powerful CMakeLists.txt file that was designed to also be used with add_subproject. You can add the repository to your code (preferably as a git submodule), then add the following line to your project (assuming your folder is called CLI11):

add_subdirectory(CLI11)

Then, you will have a target CLI11::CLI11 that you can link to with target_link_libraries. It will provide the include paths you need for the library. This is the way GooFit uses CLI11, for example.

You can also configure and optionally install CLI11, and CMake will create the necessary lib/cmake/CLI11/CLI11Config.cmake files, so find_package(CLI11 CONFIG REQUIRED) also works.

If you use conan.io, CLI11 supports that too. CLI11 also supports Meson and pkg-config if you are not using CMake.

If the CMake option CLI11_PRECOMPILED is set then the library is compiled into a static library. This can be used to improve compile times if CLI11 is included in many different parts of a project.

Global Headers

Use CLI/*.hpp files stored in a shared folder. You could check out the git repository to a system-wide folder, for example /opt/. With CMake, you could add to the include path via:

if(NOT DEFINED CLI11_DIR)
set (CLI11_DIR "/opt/CLI11" CACHE STRING "CLI11 git repository")
endif()
include_directories(${CLI11_DIR}/include)

And then in the source code (adding several headers might be needed to prevent linker errors):

#include "CLI/App.hpp"
#include "CLI/Formatter.hpp"
#include "CLI/Config.hpp"

Global Headers with Target

configuring and installing the project is required for linking CLI11 to your project in the same way as you would do with any other external library. With CMake, this step allows using find_package(CLI11 CONFIG REQUIRED) and then using the CLI11::CLI11 target when linking. If CMAKE_INSTALL_PREFIX was changed during install to a specific folder like /opt/CLI11, then you have to pass -DCLI11_DIR=/opt/CLI11 when building your current project. You can also use Conan.io or Hunter. (These are just conveniences to allow you to use your favorite method of managing packages; it's just header only so including the correct path and using C++11 is all you really need.)

Using Fetchcontent

If you do not want to add cmake as a submodule or include it with your code the project can be added using FetchContent. This capability requires CMake 3.14+ (or 3.11+ with more work).

An example CMake file would include:

include(FetchContent)
FetchContent_Declare(
    cli11_proj
    QUIET
    GIT_REPOSITORY https://github.com/CLIUtils/CLI11.git
    GIT_TAG v2.3.2
)

FetchContent_MakeAvailable(cli11_proj)

# And now you can use it
target_link_libraries(<your project> PRIVATE CLI11::CLI11)

And use

#include <CLI/CLI.hpp>

in your project. It is highly recommended that you use the git hash for GIT_TAG instead of a tag or branch, as that will both be more secure, as well as faster to reconfigure - CMake will not have to reach out to the internet to see if the tag moved. You can also download just the single header file from the releases using file(DOWNLOAD).

Running tests on the full edition

CLI11 has examples and tests that can be accessed using a CMake build on any platform. Simply build and run ctest to run the 200+ tests to ensure CLI11 works on your system.

As an example of the build system, the following code will download and test CLI11 in a simple Alpine Linux docker container ¹:

gitbook:~ $ docker run -it alpine
root:/ # apk add --no-cache g++ cmake make git
fetch ...
root:/ # git clone https://github.com/CLIUtils/CLI11.git
Cloning into 'CLI11' ...
root:/ # cd CLI11
root:CLI11 # mkdir build
root:CLI11 # cd build
root:build # cmake ..
-- The CXX compiler identification is GNU 6.3.0 ...
root:build # make
Scanning dependencies ...
root:build # make test
Running tests...
Test project /CLI11/build
      Start  1: HelpersTest
 1/10 Test  #1: HelpersTest ......................   Passed    0.01 sec
      Start  2: IniTest
 2/10 Test  #2: IniTest ..........................   Passed    0.01 sec
      Start  3: SimpleTest
 3/10 Test  #3: SimpleTest .......................   Passed    0.01 sec
      Start  4: AppTest
 4/10 Test  #4: AppTest ..........................   Passed    0.02 sec
      Start  5: CreationTest
 5/10 Test  #5: CreationTest .....................   Passed    0.01 sec
      Start  6: SubcommandTest
 6/10 Test  #6: SubcommandTest ...................   Passed    0.01 sec
      Start  7: HelpTest
 7/10 Test  #7: HelpTest .........................   Passed    0.01 sec
      Start  8: NewParseTest
 8/10 Test  #8: NewParseTest .....................   Passed    0.01 sec
      Start  9: TimerTest
 9/10 Test  #9: TimerTest ........................   Passed    0.24 sec
      Start 10: link_test_2
10/10 Test #10: link_test_2 ......................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 10

Total Test time (real) =   0.34 sec

For the curious, the CMake options and defaults are listed below. Most options default to off if CLI11 is used as a subdirectory in another project.

¹: Docker is being used to create a pristine disposable environment; there is nothing special about this container. Alpine is being used because it is small, modern, and fast. Commands are similar on any other platform.

Meson support

Global Headers from pkg-config

If CLI11 is installed globally, then nothing more than dependency('CLI11') is required. If it installed in a non-default search path, then setting the PKG_CONFIG_PATH environment variable of the --pkg-config-path option to meson setup is all that's required.

Using Meson's subprojects

Meson has a system called wraps, which allow Meson to fetch sources, configure, and build dependencies as part of a main project. This is the mechanism that Meson recommends for projects to use, as it allows updating the dependency transparently, and allows packagers to have fine grained control on the use of subprojects vs system provided dependencies. Simply run meson wrap install cli11 to install the cli11.wrap file, and commit it, if desired.

It is also possible to use git submodules. This is generally discouraged by Meson upstream, but may be appropriate if a project needs to build with multiple build systems and wishes to share subprojects between them. As long as the submodule is in the parent project's subproject directory nothing additional is needed.

Installing cli11 using vcpkg

You can download and install cli11 using the vcpkg dependency manager:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install cli11

The cli11 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

Installing CLI11 using Conan

You can install pre-built binaries for CLI11 or build it from source using Conan. Use the following command:

conan install --requires="cli11/[*]" --build=missing

The CLI11 Conan recipe is kept up to date by Conan maintainers and community contributors. If the version is out of date, please create an issue or pull request on the ConanCenterIndex repository.

Special instructions for GCC 8, Some clang, and WASI

If you are using GCC 8 and using it in C++17 mode with CLI11. CLI11 makes use of the <filesystem> header if available, but specifically for this compiler, the filesystem library is separate from the standard library and needs to be linked separately. So it is available but CLI11 doesn't use it by default.

Specifically libstdc++fs needs to be added to the linking list and CLI11_HAS_FILESYSTEM=1 has to be defined. Then the filesystem variant of the Validators could be used on GCC 8. GCC 9+ does not have this issue so the <filesystem> is used by default.

There may also be other cases where a specific library needs to be linked.

Defining CLI11_HAS_FILESYSTEM=0 which will remove the usage and hence any linking issue.

In some cases certain clang compilations may require linking against libc++fs. These situations have not been encountered so the specific situations requiring them are unknown yet.

If building with WASI it is necessary to add the flag -lc-printscan-long-double to the build to allow long double support. See #841 for more details.