1. CLI11 是什么CLI11 是一个header-only、现代 CC11 起的命令行解析库由 Henry Schreiner 发起并维护采用BSD-3-Clause开源协议托管于 GitHubgithub.com/CLIUtils/CLI11。目前最新稳定版本为 2.x 系列。它的核心定位是让 C 开发者用最少的代码、最自然的方式写出功能完整、对用户友好的命令行程序。官方口号是CLI parsing for modern C即为现代 C 而生的命令行解析。CLI11 之所以诞生是因为传统方案POSIX getopt、Boost.Program_options存在 API 老旧、模板复杂、二进制体积膨胀、帮助信息难看等问题。CLI11 选择了一条截然不同的路以选项对象为中心Option-centric用链式调用fluent interface声明式地描述程序接受哪些参数解析、校验、帮助生成全部自动完成。#include CLI/CLI.hpp #include iostream int main(int argc, char** argv) { CLI::App app{我的程序}; int count 1; app.add_option(-c,--count, count, 处理次数); CLI11_PARSE(app, argc, argv); std::cout count count std::endl; return 0; }就这么十几行一个支持 -c 5、--count 5、--count5、自动生成 --help 帮助信息的程序就完成了。2. 为什么需要命令行解析库先看一个不借助任何库的朴素实现会面临什么问题// 手写解析的典型噩梦 int main(int argc, char** argv) { for (int i 1; i argc; i) { if (std::string(argv[i]) -c) { count std::stoi(argv[i]); // 越界风险、非法输入崩溃 } else if (std::string(argv[i]) --verbose) { verbose true; } // 更多选项重复代码、无帮助、无类型校验、无子命令…… } }手写解析的问题随选项数量增长呈指数级恶化类型转换与错误处理std::stoi 遇到非法输入直接抛异常需要手动捕获并输出友好的错误信息重复劳动每个选项都要写匹配参数名 → 取值 → 转换 → 赋给变量四步选项一多全是模板代码无帮助信息-h/--help 要手写且容易与代码实现脱节无校验能力范围检查、互斥关系、必填约束都要手写判断无子命令支持git add、git commit 这类多命令结构极难手写无配置文件支持命令行 配置文件的合并逻辑要自己设计。CLI11 把这些全部内置开发者只需要声明意图其余交给库。3. 核心优点3.1 声明式链式 API代码即文档CLI11 的 API 设计围绕把参数描述清楚展开每个 add_* 调用就是一行声明可读性极强app.add_option(-p,--port, port, 服务端口)-required()-check(CLI::Range(1, 65535));这一行完成了定义短/长选项、绑定变量、标注必填、添加范围校验。相比手写解析代码量减少 80% 以上。3.2 header-only、零依赖、可移植只有一个头文件CLI/CLI.hpp直接拷贝进项目即可使用无需编译、无需链接、无需安装依赖支持 C11 及以上所有标准Windows / Linux / macOS 全平台可用不依赖 Boost 等重型库接入成本极低对嵌入式、工具链类项目尤其友好。3.3 自动生成高质量帮助与版本信息CLI11 根据你的声明自动生成格式规范的帮助文本、--help/-h、--version且支持彩色输出终端支持时Usage: mytool [OPTIONS] Options: -h,--help Print this help message and exit -c,--count INT 处理次数 [required] -v,--verbose 输出详细信息帮助信息永远与代码同步不会出现文档写的和实际行为不一致。3.4 强大的类型系统与自动校验通过模板技术CLI11 支持任意可流式读取operator的类型自动转换int、double、std::string、bool、std::vectorT、枚举需自定义转换、自定义结构体等。配合内置校验器Range、In、Regex、SizeAtLeast 等与自定义校验参数合法性在解析阶段就完成拦截。3.5 子命令Subcommand原生支持git、docker、npm 这类主命令 子命令的工具结构CLI11 用嵌套 CLI::App 对象天然表达子命令可以继续嵌套子命令帮助信息自动分层展示。3.6 配置文件与环境变量支持CLI11 支持 TOML/INI 风格配置文件支持从环境变量读取默认值并定义了清晰的优先级命令行 配置文件 环境变量 代码默认值。这极大方便了默认值可被覆盖的场景。3.7 异常机制与友好的错误输出解析失败抛出 CLI::ParseError配合 app.exit(e) 自动输出格式化的错误信息与退出码CLI11_PARSE 宏封装了完整的 try/catch 流程代码更简洁。3.8 活跃社区与成熟度CLI11 已被大量知名项目采用如 DCMTK、Plumed、SCons 的 C 后端等2.x 系列 API 稳定文档齐全Bug 修复及时。4. 适用场景场景说明示例CLI 工具/命令行程序几乎所有需要接受参数的 C 可执行程序批处理工具、数据转换器、代码生成器构建/开发辅助工具自定义构建脚本、代码检查工具的入口自定义 linter、脚手架生成器服务端程序启动参数需要配置端口、日志级别、配置文件路径的守护进程Web 服务、消息队列消费者科学计算/研究脚本入口需要大量数值参数的仿真/实验程序数值仿真器、模型训练入口测试/基准程序需要控制用例、次数、输出格式的测试工具Benchmark 驱动、回归测试套件嵌入式/资源受限环境header-only 特性让单文件工具成为可能单文件命令行工具、CI 辅助脚本教学/内部工具需要快速交付、低维护成本的小工具团队内部运维脚本不适用场景需要解析复杂嵌套语法的 DSL应使用真正的语法分析器对二进制体积极度敏感且只解析 1~2 个选项的极简场景手写几行即可非 C 项目。5. 快速上手安装与第一个程序5.1 获取 CLI11方式一单头文件直接拷贝最简单从 GitHub Releases 下载 CLI11.hpp或 clone 仓库后把 include/CLI/ 目录拷入项目git clone https://github.com/CLIUtils/CLI11.git cp -r CLI11/include/CLI/ /your/project/third_party/方式二CMake FetchContent / find_packageinclude(FetchContent) FetchContent_Declare( CLI11 GIT_REPOSITORY https://github.com/CLIUtils/CLI11.git GIT_TAG v2.4.2 ) FetchContent_MakeAvailable(CLI11) add_executable(mytool main.cpp) target_link_libraries(mytool PRIVATE CLI11::CLI11)方式三包管理器vcpkg / Conanvcpkg install cli11 # 或 conan install cli11/2.4.25.2 第一个程序单文件解析#include CLI/CLI.hpp #include iostream #include string int main(int argc, char** argv) { CLI::App app{文件处理工具 v1.0}; // 位置参数positional std::string input_file; app.add_option(input, input_file, 输入文件路径)-required(); // 选项参数flag / option int count 1; app.add_option(-c,--count, count, 处理次数默认 1); bool verbose false; app.add_flag(-v,--verbose, verbose, 输出详细信息); std::string mode fast; app.add_option(--mode, mode, 处理模式: fast|safe)-check(CLI::IsMember({fast, safe})); CLI11_PARSE(app, argc, argv); std::cout 输入文件: input_file std::endl; std::cout 处理次数: count std::endl; std::cout 详细模式: (verbose ? on : off) std::endl; std::cout 处理模式: mode std::endl; return 0; }编译运行g -stdc17 -I./third_party main.cpp -o mytool ./mytool data.txt -c 3 -v --mode safe # 输出 # 输入文件: data.txt # 处理次数: 3 # 详细模式: on # 处理模式: safe ./mytool --help # 自动输出帮助信息注意 CLI11_PARSE 宏做了什么它捕获 CLI::ParseError 异常调用 app.exit(e) 输出错误/帮助并返回正确退出码主函数直接 return 即可。6. 核心 API 详解6.1 三种基本参数类型CLI11 把命令行参数抽象为三类理解它们是掌握 CLI11 的关键类型说明添加方法示例位置参数Positional不带 -/-- 前缀、按顺序匹配add_option(name, var, ...)mytool data.txt选项Option带 -/-- 前缀、可携带值add_option(-o,--output, var, ...)mytool -o out.txt标志Flag布尔开关不携带值add_flag(-v,--verbose, var, ...)mytool -v6.2 add_option选项与位置参数CLI::Option* opt app.add_option(-p,--port, port, 端口号);一个 add_option 可同时定义短选项-p和长选项--port用逗号分隔绑定到变量后解析时自动赋值位置参数只需不给 - 前缀app.add_option(filename, name, 文件名)返回 CLI::Option* 指针可继续链式调用约束方法。6.3 add_flag布尔标志bool verbose false; app.add_flag(-v,--verbose, verbose, 详细输出); app.add_flag(-q,--quiet, quiet, 安静模式);还支持计数标志记录出现次数与负向标志int verbosity 0; app.add_flag(-V,--verbose{2},-v, verbosity, 详细级别); // -V 计 2-v 计 1 bool no_color false; app.add_flag(--no-color, no_color, 禁用颜色); // --no-color 出现则为 true6.4 add_option 自动推导容器类型CLI11 对 std::vectorT 有特殊处理同一选项可多次出现自动收集到 vector 中std::vectorint nums; app.add_option(-n,--number, nums, 数字列表可多次); // ./tool -n 1 -n 2 -n 3 → nums {1,2,3} // ./tool -n 1 2 3 → 同样支持空格分隔多值取决于 expected 配置6.5 链式约束方法速查add_option 返回的 CLI::Option* 支持以下常用约束app.add_option(--port, port, 端口) -required() // 必填 -default_val(8080) // 默认值 -expected(1) // 期望取值的个数 -check(CLI::Range(1, 65535)) // 范围校验 -check(CLI::IsMember({http, https})) // 枚举值白名单 -each([](const std::string s){ // 每次解析到值时回调 std::cout 解析到: s std::endl; });6.6 帮助与版本app.set_help_flag(-h,--help, 显示帮助信息并退出); // 默认即支持 -h/--help app.set_version_flag(-V,--version, 1.2.3, 显示版本号并退出); // 启用 --version app.footer(更多信息请访问 https://example.com); // 帮助底部附加信息7. 进阶能力校验、转换与回调7.1 内置校验器CLI11 提供多个开箱即用的校验器都在 CLI:: 命名空间校验器作用CLI::Range(min, max)数值范围检查支持 CLI::Range(0.0, 1.0) 浮点CLI::IsMember({...})白名单检查可指定 ignore_case、ignore_underscoreCLI::IsMember({a,b}, CLI::ignore_case)忽略大小写的白名单CLI::Regex(pattern)正则匹配C11 std::regexCLI::SizeAtLeast(n) / SizeAtMost(n)容器元素数量范围CLI::ExistingFile / ExistingDirectory校验文件/目录存在CLI::NonexistentPath校验路径不存在用于新建文件CLI::NonNegativeNumber / PositiveNumber数值正负校验7.2 自定义校验器校验器本质是 std::functionstd::string(const std::string)输入待校验字符串返回空串表示通过返回非空串表示错误信息app.add_option(--ip, ip, IP 地址)-check([](const std::string s) - std::string { std::istringstream iss(s); int a, b, c, d; char dot1, dot2, dot3; if (iss a dot1 b dot2 c dot3 d iss.eof() dot1 . dot2 . dot3 . a 0 a 255 b 0 b 255 c 0 c 255 d 0 d 255) { return ; // 校验通过 } return 不是合法的 IPv4 地址; });7.3 类型转换自定义类型任何重载了 operator 的类型都可以直接用于 add_optionstruct Point { double x, y; }; std::istream operator(std::istream is, Point p) { char comma; if (is p.x comma p.y comma ! ,) { is.setstate(std::ios::failbit); } return is; } Point center; app.add_option(--center, center, 中心点格式 x,y); // ./tool --center 1.5,2.57.4 回调解析即处理有时不需要绑定变量而是希望解析到某个选项时立刻执行动作app.add_option(--print, [](const std::string s){ std::cout 收到参数: s std::endl; }, 打印收到的参数); app.add_flag_callback(--debug, []{ g_debug true; }, 开启调试);7.5 选项分组CLI::Option_group* group app.add_option_group(网络配置); group-add_option(--host, host, 主机名); group-add_option(--port, port, 端口); // 帮助信息中会以分组形式展示8. 子命令系统8.1 基本用法子命令是 CLI11 的招牌能力。用 add_subcommand 创建子命令每个子命令是独立的 CLI::App拥有自己的选项、位置参数、帮助信息CLI::App app{git 风格的版本工具}; // 子命令 add CLI::App* add_cmd app.add_subcommand(add, 添加文件); std::vectorstd::string files; add_cmd-add_option(files, files, 要添加的文件)-required(); // 子命令 commit CLI::App* commit_cmd app.add_subcommand(commit, 提交更改); std::string message; commit_cmd-add_option(-m,--message, message, 提交信息)-required(); commit_cmd-add_flag(--amend, amend, 修改上一次提交); // 不匹配任何子命令时要求报错 app.require_subcommand(1); // 必须且只能有一个子命令 CLI11_PARSE(app, argc, argv); if (*add_cmd) { // 用户执行了 add 子命令 for (const auto f : files) std::cout 添加: f std::endl; } if (*commit_cmd) { std::cout 提交: message (amend ? (amend) : ) std::endl; }运行效果./tool add a.txt b.txt ./tool commit -m fix bug ./tool --help # 显示主命令帮助 子命令列表 ./tool add --help # 显示 add 子命令的帮助8.2 子命令高级控制app.require_subcommand(1); // 恰好 1 个子命令 app.require_subcommand(0, 2); // 0~2 个子命令 app.require_subcommand(-1); // -1 表示至少 1 个 // 别名docker ps 与 docker container ls 这类 CLI::App* ls app.add_subcommand(ls, 列出); ls-alias(list); // 子命令失败时回退到主命令解析如 tool --version app.fallthrough();8.3 嵌套子命令CLI::App* remote app.add_subcommand(remote, 远程仓库管理); CLI::App* remote_add remote-add_subcommand(add, 添加远程仓库); std::string name, url; remote_add-add_option(name, name, 远程名)-required(); remote_add-add_option(url, url, 远程地址)-required(); // ./tool remote add origin https://github.com/foo/bar.git9. 配置文件的魔法CLI11 支持TOML/INI 风格配置文件且与命令行天然合并。配置文件中用选项的长名称作为键# config.ini port 9090 host 127.0.0.1 verbose trueapp.add_option(--port, port, 端口); app.add_option(--host, host, 主机); app.add_flag(--verbose, verbose, 详细输出); app.set_config(--config, config.ini, 配置文件路径, false); // 参数选项名、默认配置文件、说明、是否要求文件存在 CLI11_PARSE(app, argc, argv);优先级规则命令行显式给出的值 配置文件中的值 代码默认值。也就是说./tool --port 1234 # port1234命令行覆盖配置文件 ./tool # port9090读配置文件 ./tool --config other.ini # 指定其他配置文件配置文件机制极大减少了命令行参数的数量特别适合选项很多的服务类程序。10. 与主流命令行库对比特性CLI11cxxoptsBoost.Program_options手写 getopt接入方式header-only零依赖header-only需编译链接 Boost系统自带语言标准C11C11C98C链式声明 API优秀良好一般无自动帮助生成优秀良好一般无子命令支持原生、可嵌套无弱无配置文件支持TOML/INI 内置无有无校验器生态丰富Range/IsMember/Regex/文件路径等基础基础无类型自动转换任意可流式类型常见类型常见类型无错误信息友好度高自动格式化中中低二进制体积影响小小大链接 Boost无与 CMake 集成FetchContent/find_package 官方支持良好一般N/A选型建议需要子命令git/docker 风格→ CLI11 是当前 C 生态最自然的选择需要配置文件能力 → CLI11 或 Boost.Program_options仅需最简 flag 解析且极度在意体积 → 手写或 cxxopts项目已依赖 Boost → 考虑 Boost.Program_options 避免引入新依赖但会牺牲子命令与易用性。11. 常见坑点与 FAQQ1为什么我的位置参数没有被解析位置参数必须在所有 add_option 中按出现顺序声明且位置参数之后不能再有必填的位置参数未赋值。常见错误是把位置参数声明放在其他选项之后却期望它排在前面。Q2--help 之后程序没有退出CLI11_PARSE 宏内部会处理帮助/版本/错误并 return app.exit(e)。如果你手写了 try/catch需要自己调用 app.exit(e) 返回退出码不要吞掉 CLI::ParseError。Q3选项的值被当成位置参数了检查是否忘了给选项加 -/-- 前缀另外 -- 之后的参数会全部按位置参数处理POSIX 惯例这是预期行为。Q4默认值参与校验吗CLI11 中如果提供了 default_val默认值不经过校验器默认值被视为可信输入。若希望默认值也过校验需要在代码里手动校验或使用 -check(...) 的同时自行判断。Q5配置文件中的键名大小写敏感吗默认大小写敏感可通过 app.set_config(...) 后对 CLI::Config 定制或统一使用小写键名规避。Q6如何让同一个选项接受可变数量参数app.add_option(--nums, nums)-expected(-1); // -1 表示直到下一个选项 // 或 expected(2, 5) 表示 2~5 个Q7布尔标志 --flag false 这种写法支持吗CLI11 的 add_flag 默认不消费值--flag 即 true。若想支持 --flag false可用 add_option 绑定 bool 变量--flagfalse 或 --flag false 均可。Q8解析失败时如何拿到错误信息try { app.parse(argc, argv); } catch (const CLI::ParseError e) { return app.exit(e); // 已输出格式化错误 }或捕获 CLI::CallForHelp、CLI::CallForVersion 分别处理帮助/版本请求。Q9如何在 Windows 上正确处理 Unicode 参数CLI11 按 char* 接收参数。Windows 下建议用 wmain/GetCommandLineW 转 UTF-8 后传入或依赖控制台代码页设置。Q10CLI11 有性能开销吗解析发生在程序启动阶段为 O(参数个数) 级别可忽略。CLI11 不引入运行时分配热点对启动速度无感知影响。12. 总结CLI11 是当前 C 生态中命令行解析的最优解之一对使用者声明式 API 让命令行程序 10 分钟上手帮助/校验/子命令/配置文件开箱即用对维护者header-only 零依赖、代码即文档、自动生成的帮助永不脱节大幅降低维护成本对工程BSD-3 协议可放心商用CMake 集成完善适合从个人工具到企业级 CLI 的全谱系场景。如果说 Qt 系列博客解决的是界面怎么写本文解决的则是入口怎么接——任何一个 C 命令行程序的起点都值得用 CLI11 来夯实。