cxxopts

Language: CPP

CLI/Utils

cxxopts was created to offer a modern, header-only alternative to traditional C++ command-line parsers. It supports optional arguments, default values, boolean flags, and automatic help generation, allowing developers to focus on application logic rather than argument parsing.

cxxopts is a lightweight C++ library for parsing command-line options. It provides a simple and modern API to define options, parse arguments, and handle help messages, making it ideal for CLI applications.

Installation

linux: Download the single header file from https://github.com/jarro2783/cxxopts and include it in your project

mac: Same as Linux; copy the header into your include path

windows: Download the header file from GitHub and include it in your project

Usage

cxxopts allows you to define named options, positional arguments, boolean flags, and automatically generates help messages. It supports both short (`-h`) and long (`--help`) option formats and integrates easily into existing C++ projects.

Parsing basic options

#include <cxxopts.hpp>
#include <iostream>
int main(int argc, char* argv[]) {
    cxxopts::Options options("MyApp", "A brief description");
    options.add_options()
        ("n,name", "Name of user", cxxopts::value<std::string>())
        ("h,help", "Print help");

    auto result = options.parse(argc, argv);

    if(result.count("help")) {
        std::cout << options.help() << std::endl;
        return 0;
    }

    if(result.count("name")) {
        std::cout << "Hello, " << result["name"].as<std::string>() << "!" << std::endl;
    }
    return 0;
}

Defines a `--name` option and `--help` flag, parses command-line arguments, and prints the help or greeting message accordingly.

Using default values

#include <cxxopts.hpp>
#include <iostream>
int main(int argc, char* argv[]) {
    cxxopts::Options options("MyApp", "Demo with defaults");
    options.add_options()
        ("n,name", "Name of user", cxxopts::value<std::string>()->default_value("Guest"));

    auto result = options.parse(argc, argv);
    std::cout << "Hello, " << result["name"].as<std::string>() << "!" << std::endl;
    return 0;
}

Sets a default value for an option if the user does not provide it.

Boolean flags

#include <cxxopts.hpp>
#include <iostream>
int main(int argc, char* argv[]) {
    cxxopts::Options options("MyApp", "Boolean flags example");
    options.add_options()
        ("v,verbose", "Enable verbose mode");

    auto result = options.parse(argc, argv);
    if(result.count("verbose")) {
        std::cout << "Verbose mode enabled" << std::endl;
    }
    return 0;
}

Demonstrates using a boolean flag `--verbose` to control program behavior.

Positional arguments

#include <cxxopts.hpp>
#include <iostream>
int main(int argc, char* argv[]) {
    cxxopts::Options options("MyApp", "Positional argument example");
    options.add_options()
        ("input", "Input file", cxxopts::value<std::string>());
    options.parse_positional({"input"});

    auto result = options.parse(argc, argv);
    if(result.count("input")) {
        std::cout << "Input file: " << result["input"].as<std::string>() << std::endl;
    }
    return 0;
}

Maps positional arguments to named options for easier parsing.

Handling exceptions

#include <cxxopts.hpp>
#include <iostream>
int main(int argc, char* argv[]) {
    try {
        cxxopts::Options options("MyApp", "Demo");
        options.add_options()
            ("n,name", "Name", cxxopts::value<std::string>());
        auto result = options.parse(argc, argv);
    } catch(const cxxopts::OptionException& e) {
        std::cerr << "Error parsing options: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}

Catches parsing exceptions to handle invalid or missing arguments gracefully.

Error Handling

cxxopts::OptionException: Thrown when an invalid option is provided or a required value is missing. Use try-catch blocks to handle gracefully.

Best Practices

Always provide a `--help` option for user convenience.

Use default values for options to simplify usage.

Catch exceptions to prevent application crashes on invalid input.

Document command-line options clearly for end users.

Use named and positional arguments consistently.

Official Docs Github