std: introduce std.cli, automatically parse command-line arguments into a second "juicy main" parameter #35304

Implements #30677 (based roughly on the design outlined in this comment)
Implements #24510 (the second half of the original "juicy main" proposal)

This PR introduces APIs for parsing command-line arguments, situated underneath the new namespace std.cli.

std.cli.ArgsParser, automatic parsing into a second "juicy main" parameter

std.cli.ArgsParser is a minimal, opinionated, high-level API for parsing a process's arguments into a struct instance. While it exists as a regular API that can be called from code, in practice users will be more likely to use it indirectly by declaring a "juicy main" function with a second parameter.

Below is a simple example program that will automatically parse a command-line invocation like program_name https://server.example.com --poll-interval 30 --debug:

// User-defined structconstArgs=struct{server:[:0]constu8,@"--poll-interval":i32=60,@"--debug":bool=false,};pubfnmain(init:std.process.Init,args:Args)!void{// ...}

Fields whose names begin with @"--" are considered to be options and receive their values from the command line via --name=value or --name value. All other fields are considered to be positional arguments and receive their values from the command line in the same order they are declared.

Supported field types are integers (e.g. i32), floats (e.g. f64), enums (e.g. enum { red, green, blue }) and strings ([:0]const u8, with or without a sentinel), as well as optionals (?T) and slices ([]T) of the aforementioned types. Option fields additionally support void and bool (and their optional equivalents ?void and ?bool).

The API automatically handles printing of usage error messages in response to incorrect usage. It also automatically handles the -h/--help option (and --version option, if applicable) by generating help text, which can be customized by declaring pub const @"--help": std.cli.Help(T):

constArgs=struct{op:enum{sum,min,max},first_value:i32,rest_values:[]consti32,@"--output":?[:0]constu8,@"--pretty":bool=true,@"--verbose":?void,pubconst@"--help":std.cli.Help(Args)=.{.command_name="calculatinator",.description="Calculates numerical properties of sequences of numbers.",.args=.{.op=.{.display="(sum|min|max)",.description="Numerical property of interest"},.first_value=.{.display="<value>...",.description="Integer values"},.rest_values=.{.hidden=true},.@"--output"=.{.display="<file>",.description="Output to a file instead of stdout"},.@"--pretty"=.{.description="Pretty-print output"},.@"--verbose"=.{.description="Output verbose diagnostics to stderr"},},};pubconst@"--version":std.SemanticVersion=.{.major=1,.minor=2,.patch=0};};pubfnmain(init:std.process.Init,args:Args)!void{// ...}

Screenshot from 2026年05月13日 02-28-32

Usage: calculatinator [<option>...] (sum|min|max) <value>...
Calculates numerical properties of sequences of numbers.
Arguments:
 (sum|min|max) Numerical property of interest
 <value>... Integer values
Options:
 --output=<file> Output to a file instead of stdout
 --[no-]pretty Pretty-print output
 --verbose Output verbose diagnostics to stderr
 -h, --help Print this help and exit
 --version Print version and exit

std.cli.ArgsParser is intentionally designed to be simple and straight to the point, offloading the responsibility of parsing options and positional arguments on the command line into primitives, so that users can quickly get into action and focus on writing the code that makes their applications unique.

Extensibility or customizability are explicit non-goals. It is, for example, not possible customize the parser's behavior or parse custom types, and only long options names like --foo are supported, not short aliases like -f. The goal is to provide a simple and intuitive interface for receiving program arguments via the command line, which is something that many programs will eventually find themselves needing to do, even if they are not fully-fledged CLIs. Users developing more sophisticated CLIs will probably need to opt out of using this API and instead parse the process's arguments via other means. std.cli.ArgsTokenizer, described in more detail below, may assist with such endeavors.

std.cli.ArgsTokenizer (lower level getopt_long-style iterator API)

std.cli.ArgsTokenizer is a lower level API that tokenizes/splits an []const []const u8 argument vector into positional arguments and options based on a user-specified set of recognized options. It is roughly equivalent in functionality and behavior to getopt_long, the granddaddy of all parsers which established the de-facto command-line option parsing behavior.

Developers of advanced CLIs whose needs cannot be fulfilled by std.cli.ArgsParser are encouraged to give std.cli.ArgsTokenizer a try and see if it can serve as a foundational building block for their custom parsing approaches. It handles all standard forms of options and option-arguments (-fbar, -f bar, --foo=bar, --foo bar), stacked short options (-xyzfbar), the -- end-of-options delimiter and other de-facto conventions. It exposes two different variants of its functions, one for statically known sets of options and a second for runtime-known sets, and an important detail about its design is that the set of options can be swapped out mid-iteration for tasks like parsing subcommands.

testArgsTokenizer{constOption=union(enum){@"--amend":void,@"-m":[]constu8,@"--message":[]constu8,};varamend:bool=false;varmessage:?[]constu8=null;varpositionals:std.ArrayList([]constu8)=.empty;deferpositionals.deinit(std.testing.allocator);constargs:[]const[]constu8=&.{"git","commit","--amend","-mFix bugs"};vartokenizer:std.cli.ArgsTokenizer=.init(args);constprogram_name=tokenizer.nextPositional();while(tokenizer.next(Option))|token|switch(token){.option=>|option|switch(option){.@"--amend"=>{amend=true;},.@"-m",.@"--message"=>|arg|{message=arg;},},.end_of_options=>{},.positional=>|arg|{trypositionals.append(std.testing.allocator,arg);},.invalid_option=>|invalid|{returninvalid.err;},};trystd.testing.expectEqualStrings("git",program_nameorelse"");trystd.testing.expectEqual(1,positionals.items.len);trystd.testing.expectEqualStrings("commit",positionals.items[0]);trystd.testing.expectEqual(true,amend);trystd.testing.expectEqualStrings("Fix bugs",messageorelse"");}

std.cli.ArgsTokenizer is used internally by std.cli.ArgsParser. I also believe that the tokenizer API is powerful/flexible enough that it could replace/enhance significant portions of the manual argument parsing that is performed inside the Zig compiler itself.

Pre-merge checklist

• Port all of the compiler's internal tools to these APIs (those underneath tools/; not the compiler itself)
• Properly document std.cli.ArgsParser with doc comments that clearly describe the parser's behavior and any relevant restrictions
• Add more tests for std.cli.ArgsParser, both in the form of test declarations and standalone tests
• Implement subcommand parsing (via union(enum))

Breaking changes

• Relatively minor, but std.fmt.parseInt() and std.fmt.parseUnsigned() now reject inputs that contain consecutive underscores, e.g. 1_2__3 or 0xffff__ff80. This is for consistency with std.fmt.parseFloat(), and with Zig itself.

Follow-up tasks

Should this PR be merged, I also intend to open issues proposing the following changes to std:

• Move std.Io.Terminal to std.cli.Terminal
• Add more styles (e.g. italic) to std.cli.Terminal.Color
• Enhance std.cli.Terminal with functionality for detecting the terminal's width and rendering text with word wrapping (intended for rendering help text)

I can't help it, but I REALLY dislike the struct with field names like that. That would prevent me from using this.

I've updated all the internal tools to make use of the new API. Some important notes:

• Options in docgen, doctest, incr-check that were previously mandatory have been converted into positional arguments (options cannot be made required by the parser API, by design). These tools are invoked by the build script (which has been updated) so this hopefully shouldn't affect anything negatively.
• I swapped order of the source and destination parameters to update_mingw around, and changed it so that the destination parameter should point to the root of the Zig source tree, not the lib directory, for consistency with update_glicb/freebsd/netbsd/openbsd_libc.
• The -fqemu, -fwine, -fwasmtime, -fdarling options in incr-check have been renamed to --qemu, --wine, --wasmtime, --darling because the parser API doesn't support single-dash option names. Again, because this tool is invoked by the build script I hope this isn't a problem.
• For tools that previously didn't have help, but had top-level doc comments, I've converted those doc comments to the help summary multiline string literal and placed the args struct at the very top of the files.

Usage: docgen [options] input output
 Generates an HTML document from a docgen template.
Options:
 --code-dir dir Path to directory containing code example outputs
 -h, --help Print this help and exit

Usage: docgen [<option>...] [--] <code-dir> <input-file> <output-file>
Generates an HTML document from a docgen template.
Arguments:
 <code-dir> Path to directory containing code example outputs
 <input-file> Path to input file
 <output-file> Path to output file
Options:
 -h, --help Print this help and exit

Usage: doctest [options] -i input -o output
 Compiles and possibly runs a code example, capturing output and rendering
 it to HTML documentation.
Options:
 -h, --help Print this help and exit
 -i input Source code file path
 -o output Where to write output HTML docs to
 --zig zig Path to the zig compiler
 --zig-lib-dir dir Override the zig compiler library path
 --cache-root dir Path to local .zig-cache/

Usage: doctest [<option>...] [--] <zig-exe> <cache-root> <input-path> <output-path>
Compiles and possibly runs a code example,
capturing output and rendering it to HTML documentation.
Arguments:
 <zig-exe> Path to the zig compiler
 <cache-root> Path to local .zig-cache/
 <input-path> Source code file path
 <output-path> Where to write output HTML docs to
Options:
 --zig-lib-dir=<dir> Override the zig compiler library path
 -h, --help Print this help and exit

usage: ./dump-cov path/to/exe path/to/coverage [target]
 if omitted, 'target' defaults to 'native'
 example: dump-cov zig-out/test .zig-cache/v/xxxxxxxx x86_64-linux

Usage: dump-cov [<option>...] [--] <exe-path> <cov-path> [<target-query>]
Reads a Zig coverage file and prints human-readable information to stdout,
including file:line:column information for each PC.
Example: dump-cov zig-out/test .zig-cache/v/xxxxxxxx x86_64-linux
Arguments:
 <exe-path> Path to executable
 <cov-path> Path to coverage file
 <target-query> If omitted, defaults to 'native'
Options:
 -h, --help Print this help and exit

fetch_them_macos_headers [options] [cc args]
Options:
 --sysroot Path to macOS SDK
General Options:
-h, --help Print this help and exit

Usage: fetch_them_macos_headers [<option>...] [--] [<cc-args>...]
Arguments:
 <cc-args>... Additional arguments to forward to CC
Options:
 --sysroot=<path> Path to macOS SDK
 -h, --help Print this help and exit

gen_macos_headers_c [dir]
General Options:
-h, --help Print this help and exit

Usage: gen_macos_headers_c [<option>...] [--] <dir>
Arguments:
 <dir> Directory to search for headers
Options:
 -h, --help Print this help and exit

Usage: gen_outline_atomics [<option>...]
Options:
 -h, --help Print this help and exit

Usage: ./gen_spirv_spec <SPIRV-Headers repository path> <path/to/zig/src/codegen/spirv/extinst.zig.grammar.json>
Generates Zig bindings for SPIR-V specifications found in the SPIRV-Headers
repository. The result, printed to stdout, should be used to update
files in src/codegen/spirv. Don't forget to format the output.
<SPIRV-Headers repository path> should point to a clone of
https://github.com/KhronosGroup/SPIRV-Headers/

Usage: gen_spirv_spec [<option>...] [--] <spirv-headers-repo-dir> <extinst-zig-grammar-json>
Generates Zig bindings for SPIR-V specifications found in the SPIRV-Headers
repository. The result, printed to stdout, should be used to update
files in src/codegen/spirv. Don't forget to format the output.
Arguments:
 <spirv-headers-repo-dir> Should point to a clone of https://github.com/KhronosGroup/SPIRV-Headers/
 <extinst-zig-grammar-json> Path to zig/src/codegen/spirv/extinst.zig.grammar.json
Options:
 -h, --help Print this help and exit

Usage: gen_stubs [<option>...] [--] <build-all-dir>
Example: gen_stubs /path/to/musl/build-all >libc.S
The directory 'build-all' is expected to contain these subdirectories:
* aarch64
* arm
* i386
* hexagon
* loongarch64
* mips
* mips64
* mipsn32
* powerpc
* powerpc64
* riscv32
* riscv64
* s390x
* x32 (currently broken)
* x86_64
...each with 'lib/libc.so' inside of them.
When building the resulting libc.S file, these defines are required:
* `-DTIME32`: When the target's primary time ABI is 32-bit
* `-DPTR64`: When the target has 64-bit pointers
* One of the following, corresponding to the CPU architecture:
 - `-DARCH_aarch64`
 - `-DARCH_arm`
 - `-DARCH_i386`
 - `-DARCH_hexagon`
 - `-DARCH_loongarch64`
 - `-DARCH_mips`
 - `-DARCH_mips64`
 - `-DARCH_mipsn32`
 - `-DARCH_powerpc`
 - `-DARCH_powerpc64`
 - `-DARCH_riscv32`
 - `-DARCH_riscv64`
 - `-DARCH_s390x`
 - `-DARCH_x32`
 - `-DARCH_x86_64`
* One of the following, corresponding to the CPU architecture family:
 - `-DFAMILY_aarch64`
 - `-DFAMILY_arm`
 - `-DFAMILY_hexagon`
 - `-DFAMILY_loongarch`
 - `-DFAMILY_mips`
 - `-DFAMILY_powerpc`
 - `-DFAMILY_riscv`
 - `-DFAMILY_s390x`
 - `-DFAMILY_x86`
Arguments:
 <build-all-dir> Directory containing '<arch>/lib/libc.so'
Options:
 -h, --help Print this help and exit

Usage: ./generate_c_size_and_align_checks [target_triple]

Usage: zig run tools/generate_c_size_and_align_checks.zig -- [<option>...] [--] <target-triple>
Prints _Static_asserts for the size and alignment of all the basic built-in
C types. The output can be run through a compiler for the specified target
to verify that Zig's values are the same as those used by a C compiler
for the target.
Arguments:
 <target-triple> Zig target triple (e.g. x86_64-linux-gnu)
Options:
 -h, --help Print this help and exit

Usage: generate_JSONTestSuite [<option>...]
Run this program inside the test_parsing/ directory of this repo:
https://github.com/nst/JSONTestSuite
Options:
 -h, --help Print this help and exit

Usage: ./generate_linux_syscalls /path/to/linux
Alternative Usage: zig run /path/to/git/zig/tools/generate_linux_syscalls.zig -- /path/to/linux
Generates the list of Linux syscalls for each supported cpu arch, using the Linux development tree.
Prints to stdout Zig code which you can use to replace the file lib/std/os/linux/syscalls.zig.

Usage: generate_linux_syscalls [<option>...] [--] <linux-dir>
Alternative Usage: zig run /path/to/git/zig/tools/generate_linux_syscalls.zig -- /path/to/linux
Generates the list of Linux syscalls for each supported cpu arch, using the Linux development tree.
Prints to stdout Zig code which you can use to replace the file lib/std/os/linux/syscalls.zig.
Arguments:
 <linux-dir> Path to Linux source tree
Options:
 -h, --help Print this help and exit

Usage: incr-check <zig binary path> <input file> [options]
Options:
 --target triple-backend
 --quiet
 --zig-lib-dir /path/to/zig/lib
 --zig-cc-binary /path/to/zig
 -fqemu
 -fwine
 -fwasmtime
Debug Options:
 --preserve-tmp
 --debug-log foo

Usage: incr-check [<option>...] [--] <zig-exe> <input-file> <triple-backend>
Arguments:
 <zig-exe> Path to Zig binary
 <input-file> Path to input file
 <triple-backend> Target triple-backend (e.g. 'x86_64-linux-selfhosted')
Options:
 --[no-]quiet Suppress log messages about e.g. skipped tests
 --zig-lib-dir=<path> Override path to Zig lib directory
 --zig-cc-binary=<path> Path to CC Zig exe
 --[no-]qemu Enable QEMU integration
 --[no-]wine Enable Wine integration
 --[no-]wasmtime Enable Wasmtime integration
 --[no-]darling Enable Darling integration
 --[no-]preserve-tmp Preserve temp directory
 --debug-log=<arg> --debug-log arguments to forward to the Zig compiler
 -h, --help Print this help and exit

Usage: migrate_langref [<option>...] [--] <input-file> <output-file>
Arguments:
 <input-file> Path to input file
 <output-file> Path to output file
Options:
 -h, --help Print this help and exit

Usage: ./process_headers [--search-path <dir>] --out <dir> --abi <name>
--search-path can be used any number of times.
 subdirectories of search paths look like, e.g. x86_64-linux-gnu
--out is a dir that will be created, and populated with the results
--abi is either glibc, musl, freebsd, netbsd, or openbsd

Usage: process_headers [<option>...] [--] <out-dir> (musl|glibc|freebsd|netbsd|openbsd)
Arguments:
 <out-dir> Dir that will be created, and populated with the results
 (musl|glibc|freebsd|netbsd|openbsd) Libc vendor
Options:
 --search-path=<path> Search paths, subdirectories look like, e.g. x86_64-linux-gnu
 -h, --help Print this help and exit

Usage: ./process_headers [--search-path <dir>] --out <dir> --abi <name>
--search-path can be used any number of times.
 subdirectories of search paths look like, e.g. x86_64-linux-gnu
--out is a dir that will be created, and populated with the results

Usage: update-linux-headers [<option>...] [--] <out-dir>
Arguments:
 <out-dir> Dir that will be created, and populated with the results
Options:
 --search-path=<path> Search paths, subdirectories look like, e.g. x86_64-linux-gnu
 -h, --help Print this help and exit

Usage: ./update_clang_options /path/to/llvm-tblgen /path/to/git/llvm/llvm-project
Prints to stdout Zig code which you can use to replace the file src/clang_options.zon.

Usage: update_clang_options [<option>...] [--] <llvm-tblgen-exe> <llvm-src-root>
Prints to stdout Zig code which you can use to replace the file src/clang_options.zon.
Arguments:
 <llvm-tblgen-exe> Path to llvm-tblgen executable
 <llvm-src-root> Path to llvm-project source tree
Options:
 -h, --help Print this help and exit

Usage: ./update_cpu_features /path/to/llvm-tblgen /path/git/llvm-project /path/git/zig [zig_name filter]
Updates lib/std/target/<target>.zig from llvm/lib/Target/<Target>/<Target>.td .
On a less beefy system, or when debugging, compile with -fsingle-threaded.

Usage: update_cpu_features [<option>...] [--] <llvm-tblgen-exe> <llvm-src-root> <zig-src-root> [<filter>]
Updates lib/std/target/<target>.zig from llvm/lib/Target/<Target>/<Target>.td.
On a less beefy system, or when debugging, compile with -fsingle-threaded.
Arguments:
 <llvm-tblgen-exe> Path to llvm-tblgen executable
 <llvm-src-root> Path to llvm-project source tree
 <zig-src-root> Path to Zig source tree
 <filter> Optional Zig name filter
Options:
 -h, --help Print this help and exit

Usage: ./update_crc_catalog /path/git/zig

Usage: update_crc_catalog [<option>...] [--] <zig-src-root>
Arguments:
 <zig-src-root> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Usage: zig run tools/update_freebsd_libc.zig -- [<option>...] [--] <freebsd-src-path> <zig-src-path>
This script updates the .c, .h, .s, and .S files that make up the start
files such as crt1.o.
Example usage:
zig run tools/update_freebsd_libc.zig -- ~/Downloads/freebsd-src .
Arguments:
 <freebsd-src-path> Path to FreeBSD source tree
 <zig-src-path> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Usage: zig run tools/update_glibc.zig -- [<option>...] [--] <glibc-src-path> <zig-src-path>
This script updates the .c, .h, .s, and .S files that make up the start
files such as crt1.o.
Not to be confused with https://codeberg.org/ziglang/libc-abi-tools
which updates the 'abilists' file.
Example usage:
zig run tools/update_glibc.zig -- ~/Downloads/glibc .
Arguments:
 <glibc-src-path> Path to glibc source tree
 <zig-src-path> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Usage: zig run tools/update_mingw.zig -- [<option>...] [--] <mingw-src-path> <zig-src-path>
This script updates mingw-w64 crt and library files.
Example usage:
zig run tools/update_mingw.zig -- ~/Downloads/mingw-w64 .
Arguments:
 <mingw-src-path> Path to mingw-w64 source tree
 <zig-src-path> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Usage: zig run tools/update_netbsd_libc.zig -- [<option>...] [--] <netbsd-src-path> <zig-src-path>
This script updates the .c, .h, .s, and .S files that make up the start
files such as crt1.o.
Example usage:
zig run tools/update_netbsd_libc.zig -- ~/Downloads/netbsd-src .
Arguments:
 <netbsd-src-path> Path to NetBSD source tree
 <zig-src-path> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Usage: zig run tools/update_openbsd_libc.zig -- [<option>...] [--] <openbsd-src-path> <zig-src-path>
This script updates the .c, .h, .s, and .S files that make up the start
files such as crt1.o.
Example usage:
zig run tools/update_openbsd_libc.zig -- ~/Downloads/openbsd-src .
Arguments:
 <openbsd-src-path> Path to OpenBSD source tree
 <zig-src-path> Path to Zig source tree
Options:
 -h, --help Print this help and exit

Some reflections, mostly wrt. help text generation:

• Maybe a good future enhancement to std.Io/cli.Terminal would be to offer a writer mode that strips ANSI SGR control sequences when disabled/unsupported, so that people can pre-bake ANSI styling into their help string literals. Also relevant: #9502 do you want ANSI color code support for std.fmt.format?
• Maybe std.cli.Help should have header/footer or prolog/epilog fields, for adding sections of text before Usage: and after the last option? On the other hand, infodumping pages after pages of details about your program is better left to a README or man pages.
• It would be neat, but probably overkill, if the default option-argument display selection (<value>) tried to choose based on a limited set of common names or suffixes, e.g. names like --input/--output or those ending in -path or -file use <path> by default.
• I wonder if it would make sense to add a assume_zig_run: bool = false field to std.cli.Help, for files/scripts that are meant to be compiled and run directly via zig run, which when set would render the usage message as Usage: zig run filename.zig -- [<option>...] instead of Usage: filename.exe. (Probably not, and as I've demonstrated when I update some of these tools, you can achieve the same effect manually by setting command_name.)

@lukasl wrote in #35304 (comment):

I can't help it, but I REALLY dislike the struct with field names like that. That would prevent me from using this.

Do you think you could elaborate on why you feel it bothers you? Is it purely an aesthetic preference and a subjective distaste for @"", or is it a concern about readability and developer ergonomics/typing?

The API could be redesigned to work with a struct like

constArgs=Struct{positional:struct{script:[]constu8,},options:struct{cache_dir:?[:0]constu8,debug:bool=false,},};

similar to what was originally proposed by Josh Wolfe in #24601.

However, I would still argue that the design I'm proposing with this PR has a number of advantages. One of the main ones is that options are provided on the command line exactly as the fields are named, unlike the original proposal where it's ambiguous to an unassuming user as for whether the field a: i32 will become the short option -a or the long option --a, or whether cache_dir becomes --cache_dir or --cache-dir. Here, what you see is exactly what you get.

I also feel that requiring options to be named like actual options is intuitive. If I was completely new to a language and saw a struct with fields named like @"--output", I would immediately clock it as having to do with command-line options. Because args parsing is a common task that you're likely to run into early on, it's also a good opportunity for introducing newcomes to the language to the @"" identifier syntax and teaching them that Zig allows any arbitrary identifier name using this form. Structurally, this design is also the simplest, with a completely flattened struct.

I'll admit that I too was initially a bit concerned about whether args.@"--option" would feel like too much visual noise, but now after having updated the 20+ internal tools I don't feel like it was much of an issue at all. It certainly didn't bother me any more than something like assert(@typeInfo(@TypeOf(foo)).@"struct".layout == .@"extern") 😛

Maybe a good future enhancement to std.Io/cli.Terminal would be to offer a writer mode that strips ANSI SGR control sequences when disabled/unsupported, so that people can pre-bake ANSI styling into their help string literals

How are you going to deal with terminal feature detection? That's pretty much an unsolved problem that would pollute stdlib imo.
The "standard" way of doing that with terminfo/termcaps is not something I'd ever want in std. This article provides some insights.
How would you handle blinking text for example? Not all terminals support that, including popular and modern terminal emulators such as Kitty, and Alacritty, and there is no direct/standardized way to handle that.
I like the idea of a writer that strips unsupported escape sequences at comptime, but that implies two things:

• The user has to choose a set of supported terminals (how?)
• Heuristics, you can only guess with so much accuracy

I think it is more than reasonable however, to include ANSI color codes, as of status quo, since those have been supported by hardware since the 70-80s. A good rule of thumb could be "if the Linux kernel's terminal can display it, it's safe to support it", because the Linux kernel's terminal aims to be compatible with virtually all terminal hardware. Note that I said "display", not parse, as it reduces truecolor escape sequences and 8 bit colors to color codes anyways. In theory, a terminal emulator could not implement these escape sequences, but I think it is more than reasonable to have color codes as a baseline.

Another approach would be to specify that the style may not be displayed depending on the terminal. That is also more reasonable than feature detection imo. In that case, it would be acceptable to support commonly defined sequences, basically ANSI + XTerm (truecolor, 8 bit color codes, and all SRG sequences relevant to printing stylized text).
In that regard, doing anything other than rendering stylized text (bg, fg color, bold, italic...), line by line, should be out of scope for an std API.

Don't hesitate to tell me if I misunderstood what you meant or completely missed the point.

Side Note: The std.Io.Terminal.setColor function could also use escape sequences for windows, as Windows 10 supports ANSI escape sequences as well, that could remove duplication (which is mostly why win10 started supporting it). I don't know if that would be more efficient however. The MSDN doc specifies that these APIs are present for backwards compatibilty, whilst not being deprecated.

Personaly I think this is quite useless, its simple to implement something like this with a tiny bit of comptime. If this was added I wouldnt even use it tbh because argument parsing is already easy.

@Souleymeine wrote in #35304 (comment):

How are you going to deal with terminal feature detection? That's pretty much an unsolved problem that would pollute stdlib imo.

std.Io.Terminal already handles detection of color support/preferences in a simple, de-facto standardized manner using the NO_COLOR/CLICOLOR_FORCE environment variables and std.file.enableAnsiEscapeCodes/std.file.isTty, and it already handles modern Windows ANSI escape code support.

I am not suggesting adding terminfo support or any kind of emulation. My proposition is simply that there should be a writer or function that, if ANSI escape codes are detected as unsupported or disabled using the already existing means, strips SGR sequences (as a binary "keep all" or "strip all" toggle and not on a sequence-by-sequence basis). Which sequences one would use, out of concern for feature support and presentation issues, would be up to each user's own judgment, just like it is now with the (albeit limited) set of styles defined in std.Io.Terminal.Color.

As you can see from parts of this change set, calling setColor inline is quite cumbersome and limits the ability to take a pre-styled string as an input, so something like a stripping writer would be an improvement over status quo and relatively trivial to implement.

std.cli.ArgsParser can now parse subcommands, represented as tagged unions:

constCommand=union(enum){multiply:struct{x:i32,y:i32,pubconst@"--help":std.cli.Help(@This())=.{.description="Multiplies two integers and prints the product.",.args=.{.x=.{.description="First factor"},.y=.{.description="Second factor"},},};},divide:struct{x:i32,y:i32,@"--round":enum{@"toward-zero",down,up}=.@"toward-zero",pubconst@"--help":std.cli.Help(@This())=.{.description="Divides two integers and prints the quotient.",.args=.{.x=.{.description="Dividend"},.y=.{.description="Divisor (must not be 0)"},.@"--round"=.{.display="(toward-zero|down|up)",.description="Rounding mode"},},};},pubconst@"--help":std.cli.Help(@This())=.{.command_name="math",.description="Math!",.args=.{.multiply=.{.description="Multiply integers"},.divide=.{.description="Divide integers"},},};};pubfnmain(init:std.process.Init,cmd:Command)!void{// ...}

$ ./math --help
Usage: math [<option>...] <command> [<argument>...]
Math!
Commands:
 multiply Multiply integers
 divide Divide integers
Options:
 -h, --help Print this help and exit

$ ./math divide 10
error: incorrect number of arguments (expected 2)
Try 'math divide --help' for more information.

$ ./math divide --help
Usage: math divide [<option>...] [--] <x> <y>
Divides two integers and prints the quotient.
Arguments:
 <x> Dividend
 <y> Divisor (must not be 0)
Options:
 --round=(toward-zero|down|up) Rounding mode
 -h, --help Print this help and exit

@castholm wrote in #35304 (comment):

Do you think you could elaborate on why you feel it bothers you? Is it purely an aesthetic preference and a subjective distaste for @"", or is it a concern about readability and developer ergonomics/typing?

Yes, it's subjective distaste for @"". In my view, any such escaping mechanism should be used as a tool to deal with exceptional cases, not to handle common cases. I see this as a hack around the fact that Zig doesn't have Go-style field name tags, and I personally don't think stdlib should adopt such hacks. My personal opinion is that the positional / options split would be a much better solution, with the convention that _ is replaced by - for the CLI args.