Defining an Application

An app owns the metadata and argument definitions for one command-line application. The application name is required. All other metadata is optional.

#include <kaycxx/cli.hpp>
 
using namespace kaycxx::cli;
 
int main() {
    auto convert = app{"convert", {
        .version = "2.1.0",
        .description = "Convert input files",
        .author = "Example Author",
        .email = "author@example.com",
        .bugs = "https://example.com/issues",
        .copyright = "Copyright (c) 2026 Example Author",
        .license = "Licensed under the MIT License"
    }};
}

The application copies its name and metadata, so the strings passed to the constructor do not need to outlive it. Metadata is available through the corresponding application getters.

Registering Arguments

Register flags, options, and positional parameters before parsing. Names are specified without command-line punctuation: use "verbose", not "--verbose", and ‘'v’, not"-v"`.

auto verbose = convert.flag("verbose", 'v', "Enable verbose output");
auto level = convert.option<int>("level", 'l', "LEVEL", "Set the processing level");
auto input = convert.parameter<std::string>("INPUT", "Input file");
auto outputs = convert.parameters<std::string>("OUTPUT", "Output files");

Each argument registration method returns a handle. The application owns the underlying definition. The handle is the typed key used to configure that definition and read its parsed value. Keep the application alive while using its handles or parsed arguments.

Applications can own commands, and commands can own nested subcommands. A subcommand has its own description while version, author, contact, copyright, license, and bug-report metadata remain on the application. command() returns a lightweight handle to the owned command for configuration and dispatch. See Subcommands for the complete parsing, dispatch, and help behavior.

Descriptions are optional. print_help() lists arguments without descriptions using only their usage text.

Help and Version Output

Help and version switches are regular flags. The application chooses their names, aliases, descriptions, and language, then handles them like any other flag.

auto help = convert.flag("help", 'h', "Show help").action();
auto version = convert.flag("version", 'V', "Show version information").action();
 
auto arguments = convert.parse(argc, argv);
 
if (arguments.get(help)) {
    return convert.print_help();
}
if (arguments.get(version)) {
    return convert.print_version();
}

Marking both flags as actions makes them mutually exclusive. Passing both --help and --version produces a parse error.

print_help() and print_version() are convenience methods that generate and write formatted help and version text from the application metadata and registered arguments. Both return 0 as a suggested success code. The result can be returned directly from main or ignored when the application uses different exit codes.

Using these methods is optional. An application can instead write its own help or version text and return an appropriate exit code itself.

Passing an output stream writes there instead of to standard output, which is useful for embedding and testing.

convert.print_help(output);
convert.print_version(output);

Required options, subcommands and positional parameters are validated lazily. Help and version flags can therefore be handled before missing required input produces an error.