cli C++ Library

The CLI is structured as a tree of Menu objects. You must provide at least one root menu to initialize the Cli instance. You can create a hierarchy by nesting menus using the Menu::Insert method, which takes ownership of the child menu via std::move.

To create a CLI, initialize a Menu and pass it to the Cli constructor.

// create a menu (this is the root menu of our cli)
auto rootMenu = make_unique<Menu>("myprompt");

// ... fills rootMenu with commands or sub-menus

// create the cli with the root menu
Cli cli(std::move(rootMenu));

By default, cli uses standard std::cin and std::cout, which may not support Unicode effectively on all platforms. To handle Unicode (e.g., UTF-8), you must provide custom Unicode-aware stream objects derived from std::istream or std::ostream when initializing a FileSession.

A common approach is using boost::nowide to provide UTF-8 aware streams.

The cli library is a header-only C++14 library. You can obtain it via GitHub releases, Vcpkg, or Conan. Since it is header-only, you only need to include the header paths in your compilation process.

To install via CMake to your system:

mkdir build && cd build
cmake ..
sudo make install

To specify a custom installation path:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX:PATH=<cli_install_location>
make install

You can include the cli library directly in your project using CMake's FetchContent module. This avoids manual installation and manages the dependency automatically.

Add the following to your CMakeLists.txt:

include(FetchContent)
FetchContent_Declare(
  cli
  GIT_REPOSITORY https://github.com/daniele77/cli.git
  GIT_TAG v2.1.0
)
FetchContent_MakeAvailable(cli)

add_executable(main-project)
target_link_libraries(main-project PRIVATE cli::cli)

Examples are located in the examples directory. Compilation requirements depend on whether you need remote (telnet) sessions:

1. No remote sessions (No Asio/Boost): cmake .. -DCLI_BuildExamples=ON

2. Using Boost Asio: cmake .. -DCLI_BuildExamples=ON -DCLI_UseBoostAsio=ON (Optionally specify path: -DBOOST_ROOT=<boost_path>)

3. Using Standalone Asio: cmake .. -DCLI_BuildExamples=ON -DCLI_UseStandaloneAsio=ON (Optionally specify path: -DASIO_INCLUDEDIR=<asio_path>)

After configuring, run: cmake --build .

mkdir build && cd build
cmake .. -DCLI_BuildExamples=ON
cmake --build .

When manually driving the LoopScheduler loop, you can choose between two execution modes:

1. ExecOne() (Blocking): This method uses a condition variable to wait. If the task queue is empty, the calling thread will sleep until either a new task is added via Post() or Stop() is called. This is efficient for dedicated worker threads.
2. PollOne() (Non-blocking): This method checks the queue immediately. If the queue is empty or the scheduler is stopped, it returns false without waiting. This is useful for integration into existing event loops where you don't want to block the main thread.

To create a CLI application, instantiate the cli::Cli class. You must provide a std::unique_ptr<cli::Menu> representing the root menu (the first level of commands) and an optional std::unique_ptr<cli::HistoryStorage> to define how command history is stored.

By default, if no history storage is provided, it uses cli::VolatileHistoryStorage (history is lost when the application restarts). For persistent history, use cli::FileHistoryStorage.

If your application already manages a boost::asio::io_context, you can pass it directly to the BoostAsioScheduler to integrate the CLI into your existing event loop.

// Existing application context
boost::asio::io_context ioc;

// CLI setup using the existing ioc
BoostAsioScheduler scheduler(ioc);
CliLocalTerminalSession localSession(cli, scheduler);
BoostAsioCliTelnetServer server(cli, scheduler, 5000);

// Run your existing application loop
ioc.run();

Commands can be added to any Menu using the Menu::Insert method. The library supports several types of command handlers:

• Free functions
• std::function objects
• Lambdas

Command handlers can take an arbitrary number of parameters. Supported types include basic types, std::string, and custom types (provided you overload std::istream::operator>>).

Special Case: Arbitrary String Arguments If you need to capture an arbitrary number of string arguments, your handler must take exactly one parameter of type std::vector<std::string>.