kaycxx-cli

Typed command-line parsing with GNU-style flags, options, positional parameters, and nested subcommands.

GitHub | API Documentation

Requirements

• C++23 compiler and standard library
• Exception support

Usage

#include <iostream>
#include <string>

#include <kaycxx/cli.hpp>

using namespace kaycxx::cli;

int main(int argc, char* argv[]) {
    auto example = app{"example", { .version = "1.0.0" }};

    auto help = example.flag("help", 'h', "Show help").action();
    auto version = example.flag("version", 'V', "Show version information").action();
    auto verbose = example.flag("verbose", 'v', "Enable verbose output");
    auto repetitions = example.option<int>("count", 'c', "COUNT", "Number of repetitions").default_value(1);
    auto input = example.parameter<std::string>("INPUT", "Input file name");

    try {
        auto arguments = example.parse(argc, argv);
        if (arguments.get(help)) {
            return example.print_help();
        }
        if (arguments.get(version)) {
            return example.print_version();
        }

        arguments.validate();
        for (auto remaining = arguments.get(repetitions); remaining > 0; --remaining) {
            if (arguments.get(verbose)) {
                std::cout << "Input: ";
            }
            std::cout << arguments.get(input) << '\n';
        }
        return 0;
    } catch (parse_error const& error) {
        std::cerr << example.name() << ": " << error.what() << '\n';
        return 1;
    }
}

CMake users consume the installed package with:

find_package(kaycxx-cli 0.2.0 CONFIG REQUIRED)
target_link_libraries(my-target PRIVATE kaycxx::cli)

Non-CMake users can use pkg-config:

c++ -std=c++23 $(pkg-config --cflags kaycxx-cli) -c main.cpp
c++ main.o $(pkg-config --libs kaycxx-cli)

Guides

• Defining an Application explains application metadata, registered arguments, handles, and help/version dispatch.
• Subcommands explains nested command trees, parent switches, command selection, and generated help.
• Flags and Options explains boolean flags, typed options, short aliases, defaults, actions, and value access.
• Positional Parameters explains single and repeated parameters, defaults, value counts, and argument allocation.
• Value Conversion explains built-in conversions and how custom types provide an ADL-discovered from_string function.
• Parsing and Errors explains parsing, lazy positional validation, the -- separator, and parse_error handling.

Build From Source

cmake --preset release
cmake --build --preset release

A shared library is built by default. For a static build:

cmake --preset release -D BUILD_SHARED_LIBS=OFF
cmake --build --preset release

Install

cmake --install build/release --prefix /tmp/root

If no prefix is specified, CMake installs to /usr/local by default on Unix systems.

Development

Run all tests:

cmake --preset debug
cmake --build --preset debug --target test

Generate API documentation with Doxygen:

cmake --build --preset debug --target apidoc

The generated HTML documentation is written to build/debug/apidoc/html/index.html.