Version 2.7.2: Faster compiles

This patch release makes the precompiled and experimental module modes cheaper for clients. Include-what-you-use is followed, more function bodies compile into the library instead of into every translation unit, and the C++20 named module now imports the precompiled implementation instead of the full header-only library. It also fixes the Bazel precompiled build, which could give consumers duplicate implementations.

Changed

• The C++20 named module uses the precompiled implementation and we lowered its floor from C++23 to C++20. CLI11::Module now works for both find_package and add_subdirectory, and configure fails with a clear message if CMake is older than 3.28. #1413
• Removed <iostream>, <codecvt>, <iomanip>, <fstream>, and <locale> from the declaration headers, so precompiled clients do not parse them. App::exit() is now three overloads instead of one with stream default arguments. #1411
• Moved the remaining non-template function bodies out of App.hpp, Option.hpp, Validators.hpp, TypeTools.hpp, ConfigFwd.hpp, and FormatterFwd.hpp into the impl/*_inl.hpp files, so they compile into the library in precompiled mode. Header-only mode is unchanged. #1415 #1416 #1417

Fixed

• Fixed the Bazel precompiled build: CLI11_COMPILE and CLI11_ENABLE_EXTRA_VALIDATORS now propagate to consumers, which previously got duplicate implementations from both the headers and the library. Added a cli11_header_only target, the Windows shell32 link, and more tests. #1420
• Made ExtraValidators_inl.hpp use the same CLI11_ENABLE_EXTRA_VALIDATORS test as its header, and gave the file permission validators the CLI11_MODULE_INLINE marker the other global validators have. #1415

Documentation

• Documented the precompiled mode in the README. #1412
• Added a minimal module example, corrected the CLI11::Module target name in the book, and noted that macros such as CLI11_PARSE do not come through an import. #1413

Internal

• Added an iwyu preset that runs include-what-you-use over the one precompiled translation unit, with a mapping file for both standard libraries, and applied its findings. #1418

Version 2.7.1: LTO link fix

This patch release fixes linking against the precompiled shared library when it
is built with link-time optimization.

Fixed

• Fixed missing symbols in the precompiled library under LTO: Precompile.cpp
  now explicitly instantiates Option::ignore_case<App> and
  ignore_underscore<App>, and the library always compiles the full validator
  set unless CMake disables it. #1409

Documentation

• Added the changelog to the Doxygen site. #1405
• Titled the changelog entries and named the releases from them. #1406

Internal

• Moved the release checklist to a prepare-release skill. #1407

Version 2.7.0: Audit and documentation

This version adds a FileSize validator, a PositionalOnly prefix command mode, and more control over config file generation. It also contains a large set of bug fixes from a systematic audit of the parsing, config, help formatting, string handling, and type conversion code, along with performance improvements that remove unnecessary copies in hot paths.

Added

• Added a FileSize validator to check minimum and maximum file sizes. #1305
• Added PrefixCommandMode::PositionalOnly, which restores the pre-2.6.2 prefix command behavior as an opt-in mode: only a positional argument or the -- separator triggers prefix mode, and unrecognized options are collected as extras. #1382
• Added an option to write only the active subcommand defaults when generating a config file. #1314

Changed

• Improved performance by removing unnecessary string and container copies in parsing and validator hot paths. #1368
• Improved the performance of string splitting by replacing a stringstream with a find-based loop. #1396
• Sorted the excludes and needs sets by name for stable help output. #1308
• Removed en_US.UTF-8 from the unicode locale fallback list. #1312
• Modernization and portability fixes: added missing standard includes, exported CLI::Number from the C++20 module, and cleaned up the warning lists. #1367
• Aligned the Meson build with wrapdb policy by removing disable_auto_if for subprojects. #1349

Fixed

• Fixed require_subcommand maximum enforcement for dot notation and for disabled fallthrough, dot-notation subcommands with Windows-style prefixes, get_options const/non-const consistency, and a crash when parsing with argc == 0. #1363, #1384
• Fixed missing symbol export from the precompiled shared library on macOS. #1387
• Fixed double indentation of nested option groups in help output. #1371, #1379
• Fixed config reading and writing bugs: section headers with trailing comments, one-line multiline comments, embedded delimiters with the Join policy, and multiline values for indented keys. #1369, #1361
• Fixed help formatting issues: hidden positionals appearing in the usage line, long subcommand names running into their descriptions, and ExtrasError reporting the wrong error name. #1369
• Fixed ignore_case and ignore_underscore so both apply when used together. #1358
• Fixed string handling edge cases in split_up, remove_quotes, append_codepoint, and escape_detect. #1364
• Fixed type conversion edge cases: negative input to unsigned types, whitespace-only floating point input, containers of pairs with an odd element count, large integer sums, and the Join policy with default values. #1362
• Fixed stale processed values being returned after Option::clear(). #1360
• Fixed out-of-bounds reads in the non-codecvt narrow/widen conversion paths used under C++26. #1359
• Fixed infinite recursion on subcommand option groups with fallthrough enabled. #1316
• Fixed empty strings given to wrapper types such as std::optional to consistently produce a default-constructed value. #1340
• Fixed CLI::ExistingFile to reject an empty filename with a clear error. #1351
• Fixed an empty description on a modified Transformer. #1345
• Fixed unsigned wraparound in split_program_name for command lines without spaces. #1339
• Fixed FileOnDefaultPath with an empty default path, and PositiveNumber rejecting subnormal values. #1366
• Fixed compilation with libc++/clang in C++26 mode. #1326
• Fixed the case of the shell32 library name in CMake. #1347
• Removed the static keyword from the precompiled library definition in CMake. #1304

Documentation

• Clarified the behavior of the prefix_command overloads. #1310
• Documented the Catch2 dependency for the test build. #1342
• Corrected documentation errors, including the AsSizeValue example, the App::required() doc, and validator comments. #1304, #1366
• Modernized some documentation. #1336
• Moved the tutorial book into the Doxygen documentation, modernized the HTML output with doxygen-awesome-css, and reorganized the sidebar navigation. #1390, #1392, #1397, #1398
• Corrected errors found in a documentation review. #1394
• Split the documentation into Guide and Examples sections and filled gaps in the guide. #1400

Internal

• Added a dev CMake preset and workflow for faster local iteration using the precompiled library and ccache. #1387
• Added a CUDA test for the single-header build. #1381
• Refactored the duplicated parse-completion pipeline and removed dead code. #1365
• Moved static std::string reference initializers to helper functions. #1335
• Routed formatter label fallback through an internal helper as a step toward internationalization support. #1320
• Cleaned up the CMake logic for finding Catch2 and Boost, and corrected the example test regular expressions. #1325, #1322
• Reorganized the GitHub workflows and reduced CI build times. #1323, #1387
• Added C++26 CI coverage (GCC, and clang with modules), and made codecov wait for all coverage uploads. #1388, #1391
• Tidied the configuration files in the root directory. #1393
• Attached the source packages to tagged releases, wrote the release notes from the changelog, and added a CI check for a changelog entry on every build. #1401, #1402, #1403

Version 2.6.2: C++20 modules

This version adds C++20 modules support, additional controls for help output and
finer grained control for extras handling and prefix command operation. Fixes
compatibility issues with C++26 and Windows and a number of small issue with
help output and specific combinations of options and conditions.

Added

• Added C++20 modules support with new module files and tests. #1286
• Added configuration modes for extras handling: AssumeMultipleArguments and
  AssumeSingleArgument. #1270
• Added option for full install including impl headers with precompiled option.
  #1252
• Added improvements to prefix commands including PrefixCommandMode and
  separator specification. #1266
• Added controls for option name formatting in help output, allowing disabling
  of default values, flags, and type names. #1247
• Added refactor of Meson build system with updated version and new options.
  #1280
• Added support for Bazel 9. #1287
• Added module testing infrastructure. #1255

Changed

• Changed default to install impl headers even when precompiled option is
  selected. #1291
• Updated copyright dates to 2026. #1283
• Updated CI pipelines including Azure Pipelines and GitHub workflows.
  #1267, #1283
• Updated documentation and book chapters. #1250

Fixed

• Fixed extra spaces in option and app descriptions. #1295
• Fixed option searching to use fallthrough in parent apps. #1292
• Fixed C++26 template ambiguity for std::complex. #1278
• Fixed UTF-8 config filenames not supported on Windows. #1273
• Fixed enumeration stream output generating unconvertible strings if certain a
  user supplied stream conversion method was supplied #1261
• Fixed code simplification issues by removing use of static std::string which
  was causing some heap allocation issues when using CLI11 as part of DLL on
  certain operating systems #1244
• Fixed MISRACPP2023-25_5_2-a-1 rule violation #1299

Version 2.6.1: Compilation fixes

Patch fixing some compile issues in specific situations in the recent release,
and a potential segmentation fault from specially crafted config files

Added

• Added CI tests for install and package management on macos-arm64 #1238

Fixed

• Fixed incorrect links to validator examples. #1239
• Fixed incorrect inclusion of definition for extra validators #1238
• Fixed fuzz generated failure from crafted files introduced in recent release
  #1238
• Removed some usage of static const std::string in inline function that had
  potential memory issues when CLI11 is used with shared libraries, this likely
  isn't a bug but the fix did result in smaller code size so was kept. #1244

Version 2.6.0: Callback control

Version 2.6.0

This version adds finer grained control of when option callbacks are executed,
and further refinements in the help formatting. It also fixes a number of bugs
in type support and the ordering of options. The other major change is moving
Extra Validators to a new file which can be disabled for slightly faster
compilation if not used, and allowing additional future Validators to be easily
added.

Added

• Added option to align long options with a ratio via
  long_option_alignment_ratio in the formatter. This allows more control over
  help output formatting. #1185
• Added support for std::string_view in the as<T> method on options.
  #1187
• Added flags on the formatter to disable formatting for the description and
  footer, allowing custom formatting such as word art. #1150
• Added subcommand prefix matching as a modifier to CLI::App. Also included an
  example of close matching logic. #1152
• Added additional fuzzing mechanics, including fuzzing subcommands, and
  improved handling of edge cases. #1170
• Added new tests for array options and fixed ambiguity between tuple and
  container conversions. #1136
• Added ability to use rvalue references in add_flag descriptions. #1173
• Added CMake presets for default and tidy builds. #1181
• Added several validator examples and documentation #1192
• Added permission validators for files and directories #1203
• Added fine grained control for option callback priority, and in what order
  options including help execute in the processing sequence. #1226
• Added github action to link with future testing is oss-fuzz #1225

Changed

• Moved several of the validators to ExtraValidators.hpp and
  ExtraValidators_inl.hpp files, The compilation of these nonessential
  validators can be disabled by setting CLI11_DISABLE_EXTRA_VALIDATORS to
  OFF. Future additional validators will be behind a compile flag
  CLI11_ENABLE_EXTRA_VALIDATORS. All non-essential validators will be under
  this option with version 3.0. #1192
• Updated processing order: requirements are now checked before callbacks,
  avoiding unexpected side effects. #1186
• Updated minimum required CMake version to 3.14+. #1182
• Improved Meson build: support for building shared precompiled libraries,
  pkgconfig, and header installation. #1167
• Improved fuzzing tests with new failure cases and extended coverage. #1164
• Updated CI to remove deprecated images and add new ones (Windows-2022/2025,
  arm64, FreeBSD). #1172, #1178
• Updated license file to include the correct version number for packagers.
  #1180

Fixed

• Fixed issue with IPV4 validator where it would allow a trailing .. #1192
• Fixed edge case where a missing config file and no default caused a segfault.
  #1199
• Fixed issue with TOML multiline arrays when the first line contained only a
  single character. #1196
• Fixed default value conversion errors when locales added thousands separators.
  #1160
• Fixed multiple footer printing in help output for option groups. #1161
• Fixed incorrect argument order in extras error messages. #1162
• Fixed reversed argument order in unexpected argument error messages. #1158
• Fixed ambiguity with vector<array> options. #1147
• Fixed bug parsing negative floating point values without a leading zero.
  #1140
• Fixed spelling mistake in Error.hpp. #1129
• Fixed compilation issue with MSVC 2017. #1143
• Fixed issue with default strings of arrays in config output. #1155
• Fixed fuzzing issues with NaNs and certain error pathways. #1138
• Fixed fuzzer misinterpreting --sub1.- as a short option. #1148
• Fixed issue where parse_order was not cleared on reset. #1218
• modify code to make compatible with /GR- option in MSVC #1206
• Fixed issue where the version flag would not take precedence over option
  requirements #1226
• Fixed extra newlines being printed if a footer was in use #1229

Version 2.5.0: Formatter

This version add a new formatter with improved control capabilities and output aligned with standards for help output. It also add a modifier to enable use of non-standard option names. Along with several bug fixes for edge cases in string and config file parsing.

• Better help formatter #866, this better aligns the help generation with UNIX standard and allows use in help2man. #1093
• Add mechanism to allow option groups to be hidden and all options be considered part of the parent for help display #1039
• Add a modifier to allow non-standard single flag option names such as -option. #1078
• Add modifier for subcommands to disable fallthrough which can resolve some issues with positional arguments #1073
• Add some polish to config file output removing some unnecessary output and add modifier to control output of default values #1075
• Add the ability to specify pair/tuple defaults and improved parsing #1081
• Bugfix: Take the configurability of an option name into account when determining naming conflicts #1049
• Bugfix: Fix an issue where an extra subcommand header was being printed in the output #1058
• Bugfix: Add additional fuzzing tests and fixes for a bug in escape string processing, and resolve inconsistencies in the handing of {} between command line parsing and config file parsing. #1060
• Bugfix: Improve handling of some ambiguities in vector input processing for config files, specifically in the case of vector of vector inputs. #1069
• Bugfix: Fix an issue in the handling of uint8_t enums, and some issues related to single element tuples #1087
• Bugfix: Fix an issue with binary strings containing a \x #1097
• Bugfix: Move the help generation priority so it triggers before config file processing #1106
• Bugfix: Fixed an issue where max/min on positionals was not being respected and optional positionals were being ignored #1108
• Bugfix: Fix an issue with strings which started and ended with brackets being misinterpreted as vectors. The parsing now has special handling of strings which start with [[ #1110
• Bugfix: Fix some macros for support in C++26 related to wide string parsing #1113
• Bugfix: Allow trailing spaces on numeric string conversions #1115
• Docs: Update pymod.find_installation to find python in meson.build #1076
• Docs: Add example for transform validators #689
• Docs: Fix several spelling mistakes #1101
• Backend: Update copyright dates to 2025 #1112
• Backend: Update CMake minimum version to 3.10 #1084

New Contributors

• @uilianries made their first contribution in #1061
• @LostInCompilation made their first contribution in #866
• @tansy made their first contribution in #975
• @JonathanGzzBen made their first contribution in #689
• @nshaheed made their first contribution in #1076
• @jmarrec made their first contribution in #1113

Full Changelog: v2.4.2...v2.5.0

Version 2.4.2: Build systems

This version improves support for alternative build systems, like Meson and Bazel. The single-include file now is in its own subdirectory. Several smaller fixes as well.

What's Changed

• Meson: fixes, cleanups, and modernizations #1024 & #1025
• Support building with Bazel #1033
• Restore non-arch dependent path for the pkgconfig file #1012
• Add get_subcommand_no_throw #1016
• Move single file to single-include folder #1030 & #1036
• Fixed app.set_failure_message(...) -> app.failure_message(...) #1018
• Add IWYU pragmas #1008
• Fix internal header include paths #1011
• Improved clarity in RequiredError #1029
• Added ability to use lexical_cast overloads constrained with enable_if #1021
• Bug fixes in latest release related to environmental variable parsing from option groups and unrecognized fields in a config file #1005

New Contributors

• @krico made their first contribution in #1018
• @dcbaker made their first contribution in #1024
• @gostefan made their first contribution in #1008
• @sifferman made their first contribution in #1029
• @calebzulawski made their first contribution in #1033

Full Changelog: v2.4.1...v2.4.2

Version 2.4.1

A transitive include that might be present in some standard libraries is now included directly. Also fixes a test on architectures that need libatomic linked and fixes an inadvertent breaking change regarding unused defaults for config files.

• Bugfix: Include cstdint #996
• Bugfix: Fix change in operation of config_ptr with unused default in the count method #1003
• Tests: Include libatomic if required for fuzzing test #1000

Full Changelog: v2.4.0...v2.4.1

Version 2.4.0

This version adds Unicode support, support for TOML standard including multiline strings, digit separators, string escape sequences,and dot notation. An initial round of a fuzzer was added to testing which has caught several bugs related to config file processing, and a few other edge cases not previously observed.

• Add Unicode support and bug fixes #804, #923, #876, #848, #832, #987
• Match TOML standard for string and numerical entries, multiline strings #968, #967,#964, #935
• Add validation for environmental variables #926
• Add an escape string transform #970
• Add A REVERSE multi-option policy to support multiple config files and other applications #918
• Add usage message replacement #768
• Allow using dot notation for subcommand arguments such as --sub1.field #789
• Bugfix: Fuzzing tests and fixes #930, #905, #874, #846
• Bugfix: Missing coverage tests #928
• Bugfix: CMake package and package config tests and fixes #916
• Bugfix: Support for Windows ARM compilation and tests #913, #914
• Bugfix: Environmental variable checks in non-triggered subcommands #904
• Bugfix: Environmental variables were not being correctly process by config pointer #891
• Bugfix: Undefined behavior in sum_string_vector #893
• Bugfix: Warnings and updates for CUDA 11 support #851
• Backend: Add tests for newer compilers (lost with Travis CI) #972
• Backend: Increase minimum CMake to 3.5 #898
• Backend: Remove integrated Conan support (provided now by Conan center) #853
• Tests: Support Catch2 Version 3 #896, #980

New Contributors

• @andreasxp made their first contribution in #804
• @Krzmbrzl made their first contribution in #844
• @ptheywood made their first contribution in #851
• @trokhymchuk made their first contribution in #893
• @peterh made their first contribution in #913
• @looopTools made their first contribution in #969

Full Changelog: v2.3.2...v2.4.0