Documentation

A batteries-included framework for building command-line interfaces in Zig. Drop .zig files in a directory and get a fully-featured CLI — with command discovery and routing wired up at compile time for zero-cost dispatch.

Requires Zig 0.16.0 or newer. zcli is currently v0.25.0 and MIT licensed.

Quick start3 commands

Install the meta-CLI, scaffold a project, add a command. That's the whole loop.

Install the zcli CLI

See the install page for every option, including shell completions.

terminalsh

$ curl -fsSL https://zcli.sh/install.sh | sh

Scaffold a project

terminalsh

$ zcli init myapp --description "My awesome CLI"
Creating new zcli project: myapp
  Creating build.zig.zon...
  Creating build.zig...
  Creating src/main.zig...
  Creating example command (hello)...
  Creating README.md...
  Creating AGENTS.md...
  Initializing git repository...
  Fetching dependencies (this may take a moment)...
✔ Build verified

✓ Project 'myapp' created successfully!

Add a command & build

terminalsh

$ cd myapp
$ zcli add command deploy --description "Deploy your application"
  ✔ Created src/commands/deploy.zig

$ zig build
$ ./zig-out/bin/myapp --help
USAGE  myapp <command> [options]
  deploy   Deploy your application
  hello    Say hello

Add more commands the same way — start with Commands & structure for the file-path rules, or AI agents if a coding agent is driving.

›Manual setup — wiring build.zig by hand — skip if zcli init worked

Add zcli to build.zig.zon

terminalsh

$ zig fetch --save https://github.com/ryanhair/zcli/archive/refs/tags/v0.25.0.tar.gz

Wire up build.zig

build.zigzig

const zcli = @import("zcli");

const zcli_dep = b.dependency("zcli", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("zcli", zcli_dep.module("zcli"));

const cmd_registry = try zcli.generate(b, exe, zcli_dep, .{
    .commands_dir = "src/commands",
    .plugins = &.{
        zcli.builtin(.help, .{}),
        zcli.builtin(.version, .{}),
        zcli.builtin(.not_found, .{}),
    },
    .app_name = "myapp",
    .app_description = "My awesome CLI",
});
exe.root_module.addImport("command_registry", cmd_registry);

Write your first command

src/commands/hello.zigzig

const Context = @import("command_registry").Context;

pub const meta = .{ .description = "Say hello" };
pub const Args = struct { name: []const u8 };
pub const Options = struct {};

pub fn execute(args: Args, _: Options, context: *Context) !void {
    try context.stdout().print("Hello, {s}!\n", .{args.name});
}

The full config — plugins_dir, shared modules, docs generation, per-command tests — is in the build integration guide.

Core

Defining a CLI: how files become commands, how types become parsers, and what a command has to work with.

commandsCommands & structureFile-based discovery, nested groups, index.zig landings, single-command CLIs, aliases. args & optionsArgs & optionsTyped parsing, required options, multi-value arrays, boolean negation, env vars. validationValidation & constraintsPer-field validate hooks, custom parse types, exclusive sets, requires. completionsCompletion authoringPer-field .complete hooks, .file/.dir builtins, and the zcli.completion Request/Result contract. contextThe contextThe per-command arena, buffered I/O, environ, plugin data, and the pre-wired builders. errorsError handlingStructured diagnostics, did-you-mean suggestions, and the standalone parsing API. buildBuild integrationzcli.generate, shared modules, per-command tests, docs generation.

Terminal UX

Talking to the user: prompts, progress, live layouts, full-screen TUIs — all themed from one declaration, all degrading cleanly when piped.

promptsInteractive promptsSeven primary prompt types, with optional searchable select/multiSelect and automatic line-input fallback off a TTY. progressProgress indicatorsSpinners in nine styles, bars with ETA, multi-bars for parallel work. uiThe CLI/TUI hybridStatic scrollback plus a diffed live region — and full-screen mode with widgets and overlays. themingThemingA 13-role palette and component tokens; declare once, everything follows.

Services

The batteries a real CLI ends up needing — config, credentials, and the network — with safe behavior as the only behavior.

configConfig filesJSON, TOML, or YAML; per-command scoping; a clear precedence cascade. pathsApplication pathsPlatform-standard config, cache, and data directories — resolved, never guessed. secretsSecrets & credentialsOS-keychain storage on macOS, Linux, and Windows — never plaintext. httpHTTP clientEnforced TLS, timeouts, bounded responses, redirect hygiene. processExternal programsDeadlock-free drains, bounded capture, explicit program and environment.

Extend & verify

pluginsPluginsThe seven built-ins, three ways to enable them, and writing your own with lifecycle hooks. testingTesting your CLIIn-process unit tests against a virtual terminal, subprocess integration, PTY-backed E2E.

Workflow & shipping

the zcli cliThe zcli CLIinit, add/rm/mv, tree, dev, guide, release — the meta-CLI reference. shippingShip & distributeReleases, GitHub Actions scaffold, minisign signing, self-upgrade, completions. ai agentsBuilt for coding agentsAGENTS.md, the version-matched guide, and the write→verify→fix loop. githubSource, issues & releasesThe repo — examples, ADRs, and the changelog live here too.