What it is
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.
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.
Installation
Download the single header file from https://github.com/jarro2783/cxxopts and include it in your projectGetting started
The smallest useful thing you can do with it, and what each part means.
#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;
}#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;
}Advanced usage
Where the library earns its place over a simpler alternative.
#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;
}#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;
}#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;
}Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- 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.
Background
Why it exists, and what it was reacting to.
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.