API reference

On this page 98

Every declaration below is extracted from zig-cli's source, with the doc comments as written there. A declaration listed without prose is public but undocumented in the source.

Root

`Command`

const Command = @import("cli/CommandBuilder.zig").TypedCommand

Create a command from a struct definition Example: var cmd = try cli.Command(MyOptions).init(allocator, "mycmd", "Description");

`Context`

const Context = @import("cli/CommandBuilder.zig").TypedContext

Context for accessing parsed options with compile-time validation

`Action`

const Action = @import("cli/CommandBuilder.zig").TypedAction

Action function signature

`config`

const config = @import("config/root.zig")

Configuration loader - supports TOML, JSONC, JSON5

`prompt`

const prompt = @import("prompt/root.zig")

All prompt types: text, confirm, select, password, number, path, etc.

`Option`

const Option = @import("cli/Option.zig")

Option definition (usually auto-generated from struct fields)

`Argument`

const Argument = @import("cli/Argument.zig")

Argument definition

`Parser`

const Parser = @import("cli/Parser.zig")

Command-line argument parser

`Help`

const Help = @import("cli/Help.zig")

Help text generator

`BaseCommand`

const BaseCommand = @import("cli/Command.zig")

Base command type (for low-level use)

Command

`TypedCommand`

fn TypedCommand(comptime T: type) type

Type-safe command builder that validates options/arguments at compile time

Example:

const GreetOpts = struct {
    name: []const u8,
    age: ?u16 = null,
    verbose: bool = false,
};

var cmd = try TypedCommand(GreetOpts).init(allocator, "greet", "Greet user");
cmd.setAction(greetAction);

`init`

fn init(allocator: std.mem.Allocator, name: []const u8, description: []const u8) !Self

`deinit`

fn deinit(self: *Self) void

`setAction`

fn setAction(self: *Self, comptime action: TypedAction(T)) *Self

`getCommand`

fn getCommand(self: *Self) *Command

`TypedContext`

fn TypedContext(comptime T: type) type

Type-safe parse context that provides compile-time validated field access

`init`

fn init(parse_context: *Command.ParseContext) Self

`get`

fn get(self: *Self, comptime field: std.meta.FieldEnum(T)) TypedFieldType(T, field)

Get a field value with compile-time type checking

Example: const name = ctx.get(.name);

`parse`

fn parse(self: *Self) !T

Parse the entire context into a typed struct

`TypedAction`

fn TypedAction(comptime T: type) type

Type-safe action function signature

config

`load`

fn load(comptime T: type, allocator: std.mem.Allocator, path: []const u8) !ConfigLoader(T)

Load config from file (auto-detects format from extension)

Example:

const AppConfig = struct {
    database: struct {
        host: []const u8,
        port: u16,
    },
    debug: bool = false,
};

var cfg = try config.load(AppConfig, allocator, "config.toml");
defer cfg.deinit();

`loadFromString`

fn loadFromString(comptime T: type, allocator: std.mem.Allocator, content: []const u8, format: Format) !ConfigLoader(T)

Load config from string with explicit format

`discover`

fn discover(comptime T: type, allocator: std.mem.Allocator, app_name: []const u8) !ConfigLoader(T)

Auto-discover config file for an application

Searches for: {app_name}.toml, {app_name}.json5, {app_name}.jsonc In directories: ., ./.config, ~/.config/{app_name}

`Config`

const Config = @import("Config.zig")

`Format`

const Format = Config.ConfigFormat

`Value`

const Value = Config.Value

`TomlParser`

const TomlParser = @import("TomlParser.zig")

`JsoncParser`

const JsoncParser = @import("JsoncParser.zig")

`Json5Parser`

const Json5Parser = @import("Json5Parser.zig")

prompt

`Terminal`

const Terminal = @import("Terminal.zig")

`Ansi`

const Ansi = @import("Ansi.zig")

`PromptCore`

const PromptCore = @import("PromptCore.zig")

`PromptState`

const PromptState = @import("PromptState.zig")

`TextPrompt`

const TextPrompt = @import("TextPrompt.zig")

`ConfirmPrompt`

const ConfirmPrompt = @import("ConfirmPrompt.zig")

`SelectPrompt`

const SelectPrompt = @import("SelectPrompt.zig")

`MultiSelectPrompt`

const MultiSelectPrompt = @import("MultiSelectPrompt.zig")

`PasswordPrompt`

const PasswordPrompt = @import("PasswordPrompt.zig")

`NumberPrompt`

const NumberPrompt = @import("NumberPrompt.zig")

`SpinnerPrompt`

const SpinnerPrompt = @import("SpinnerPrompt.zig")

`PathPrompt`

const PathPrompt = @import("PathPrompt.zig")

`GroupPrompt`

const GroupPrompt = @import("GroupPrompt.zig")

`Message`

const Message = @import("Message.zig")

`Box`

const Box = @import("Box.zig")

`Table`

const Table = @import("Table.zig")

`ProgressBar`

const ProgressBar = @import("ProgressBar.zig")

`Style`

const Style = @import("Style.zig")

`text`

fn text(allocator: std.mem.Allocator, message: []const u8) ![]const u8

`confirm`

fn confirm(allocator: std.mem.Allocator, message: []const u8) !bool

`select`

fn select(allocator: std.mem.Allocator, message: []const u8, choices: []const SelectPrompt.Choice) ![]const u8

`intro`

const intro = Message.intro

`outro`

const outro = Message.outro

`note`

const note = Message.note

`log`

const log = Message.log

`cancel`

const cancel = Message.cancel

`box`

const box = Box.render

`style`

const style = Style.style

Option

`OptionType`

const OptionType = enum

`init`

fn init(name: []const u8, long: []const u8, description: []const u8, option_type: OptionType) Option

`withShort`

fn withShort(self: Option, short: u8) Option

`withRequired`

fn withRequired(self: Option, required: bool) Option

`withDefault`

fn withDefault(self: Option, default_value: []const u8) Option

`matches`

fn matches(self: Option, arg: []const u8) bool

Argument

`ArgumentType`

const ArgumentType = enum

`init`

fn init(name: []const u8, description: []const u8, arg_type: ArgumentType) Argument

`withRequired`

fn withRequired(self: Argument, required: bool) Argument

`withVariadic`

fn withVariadic(self: Argument, variadic: bool) Argument

Parser

`ParseError`

const ParseError = error

`init`

fn init(allocator: std.mem.Allocator) Parser

`parse`

fn parse(self: *Parser, command: *Command, args: []const []const u8) !void

Help

`init`

fn init(allocator: std.mem.Allocator) Help

`generate`

fn generate(self: *Help, command: *Command, cli_name: []const u8, version: []const u8) !void

BaseCommand

`CommandAction`

const CommandAction = *const fn (context: *ParseContext) anyerror!void

`ParseContext`

const ParseContext = struct

`init`

fn init(allocator: std.mem.Allocator, command_name: []const u8) ParseContext

`deinit`

fn deinit(self: *ParseContext) void

`getOption`

fn getOption(self: *ParseContext, name: []const u8) ?[]const u8

`hasOption`

fn hasOption(self: *ParseContext, name: []const u8) bool

`getArgument`

fn getArgument(self: *ParseContext, index: usize) ?[]const u8

`getArgumentCount`

fn getArgumentCount(self: *ParseContext) usize

`init`

fn init(allocator: std.mem.Allocator, name: []const u8, description: []const u8) !*Command

`deinit`

fn deinit(self: *Command) void

`addAlias`

fn addAlias(self: *Command, alias: []const u8) !*Command

`addOption`

fn addOption(self: *Command, option: Option) !*Command

`addArgument`

fn addArgument(self: *Command, argument: Argument) !*Command

`addCommand`

fn addCommand(self: *Command, subcommand: *Command) !*Command

`setAction`

fn setAction(self: *Command, action: CommandAction) *Command

`findOption`

fn findOption(self: *Command, arg: []const u8) ?*const Option

`findSubcommand`

fn findSubcommand(self: *Command, name: []const u8) ?*Command