zig (CLI)

Active contributors: andrewrk, mlugg, jacobly, alexrp

Purpose

zig is a single multi-tool binary. Every sub-command flows through src/main.zig (~350 KB), which parses arguments, sets up logging and panic handling, and dispatches.

Sub-command catalog

The authoritative list lives in the normal_usage constant near the top of src/main.zig:

build            Build project from build.zig
fetch            Copy a package into global cache and print its hash
init             Initialize a Zig package in the current directory

build-exe        Create executable from source or object files
build-lib        Create library from source or object files
build-obj        Create object from source or object files
test             Perform unit testing
test-obj         Create object for unit testing
run              Create executable and run immediately

ast-check        Look for simple compile errors in any set of files
fmt              Reformat Zig source into canonical form
reduce           Minimize a bug report
translate-c      Convert C code to Zig code

ar               Use Zig as a drop-in archiver
cc               Use Zig as a drop-in C compiler
c++              Use Zig as a drop-in C++ compiler
dlltool          Use Zig as a drop-in dlltool.exe
lib              Use Zig as a drop-in lib.exe
ranlib           Use Zig as a drop-in ranlib
objcopy          Use Zig as a drop-in objcopy
rc               Use Zig as a drop-in rc.exe

env              Print lib path, std path, cache directory, and version
help             Print this help and exit
std              View standard library documentation in a browser
libc             Display native libc paths file or validate one
targets          List available compilation targets
version          Print version number and exit
zen              Print Zen of Zig and exit

Configuration

src/main.zig declares pub const std_options: std.Options = ... to override stdlib defaults:

pub const std_options: std.Options = .{
    .wasiCwd = wasi_cwd,
    .logFn = log,
    .log_level = switch (builtin.mode) {
        .Debug => .debug,
        .ReleaseSafe, .ReleaseFast => .info,
        .ReleaseSmall => .err,
    },
};

It also installs the custom panic handler:

pub const panic = crash_report.panic;
pub const debug = crash_report.debug;

Argument parsing

Each sub-command has its own arg parser inside main.zig. Common patterns:

• Long-running compile commands (build-exe, build-lib, build-obj, test, run) share a unified parser that builds a Compilation.Config.
• Toolchain shims forward the user's argv with minimal changes to clang/LLVM/resinator/objcopy.
• zig fmt, zig ast-check, zig fetch, zig init, zig translate-c, zig reduce are each their own small entry points.

Process model

src/main.zig allocates a 60 MB stack (thread_stack_size = 60 << 20) for the main thread. Sub-commands that need parallelism construct a std.Thread.Pool (the canonical one is owned by Compilation).

Key source files

File	Purpose
src/main.zig	Top-level CLI and dispatch.
src/print_env.zig	zig env.
src/print_targets.zig	zig targets.
src/print_zir.zig, src/print_zoir.zig, src/print_value.zig	IR/value pretty-printers used by debug flags.
src/fmt.zig	zig fmt.
src/introspect.zig	Resolves the lib/std paths reported by zig env.
src/crash_report.zig	Panic handler.
src/dev.zig	Build-time feature gating (Env).

See Compiler for what compile sub-commands construct, build-runner for zig build, and Sub-pages of the applications section for the rest.