The Zero CLI: check, run, build, test, fix, and explain

What the CLI Gives You

The zero binary is the entire development toolchain. There's no separate package manager, formatter, linter, or test runner — they're all subcommands of zero. That keeps the surface small and predictable, which is the point.

A short menu of the commands you'll touch most:

Command	What it does
zero check	Type-check source without producing an executable.
zero run	Compile and run in one step.
zero build	Compile to a native executable.
zero test	Run a package's test targets.
zero fix	Apply or preview structured repair plans.
zero explain	Look up the prose explanation for a diagnostic code.
zero new	Scaffold a new package.
zero --version	Print the toolchain version.

Every one of them accepts --json to emit machine-readable output instead of human-formatted text.

zero check

The workhorse. zero check runs the compiler's static checks — parsing, type-checking, capability and effect inference, missing-import detection — and stops before code generation. It's fast, which matters because agents and editors call it constantly.

zero check hello.0

Clean output (nothing printed, exit 0) means the file is well-formed. Errors come out as human-readable text by default. Add --json and you get the structured form that agents consume:

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

The diagnostic shape is fully documented in JSON Diagnostics. Note the stable code field — NAM003 always means "unknown identifier", regardless of compiler version.

You can also point check at a package directory instead of a single file:

zero check ./my-package

It reads zero.json, walks the source tree, and reports every issue across every target.

zero run

run compiles and executes in one step. Best when you're iterating on a small program and don't care about producing a binary on disk.

zero run hello.0

Equivalent to running zero build and then invoking the produced binary, except the artifact is thrown away. Stdout from your program is forwarded to your terminal's stdout — the program's world.out.write calls land on your screen.

If your program needs arguments, pass them after a --:

zero run greet.0 -- Alice

The runtime gives the program access to those arguments through the same World capability that exposes I/O.

zero build

When you want an artifact, use build:

zero build hello.0

The compiler produces a native executable next to your source file (or under the package's build directory if you're working in a package). You can run it like any other program — no separate runtime is required because Zero binaries are self-contained.

Zero binaries are small. The project's design goal is sub-10KB executables for trivial programs, achieved by skipping the LLVM toolchain and emitting compact code paths directly.

zero test

Run a package's test targets:

zero test

Tests live alongside source under src/, declared as test targets in the package's zero.json. The runner discovers them, executes each, and emits pass/fail. With --json, the output is structured per test — name, status, duration, captured diagnostics — for agents and CI tooling.

Zero packages covers how to declare test targets in zero.json.

zero fix

fix consumes the repair metadata that check --json produces. It comes in two modes:

zero fix --plan --json   # show the structured plan, don't apply
zero fix                 # apply the plan in place

A plan looks something like this (shape is illustrative):

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

The idea is that an agent fetches the plan, decides whether to trust it, and either applies it directly or hands it to a higher-level reasoning step. Plans are data; agents don't have to interpret prose to take action.

zero explain

explain is the prose side of the diagnostic system:

zero explain NAM003

It prints a human-readable explanation of the error code — what it means, why the compiler emits it, what typical fixes look like. Useful when:

• A human is debugging and wants a longer answer than the inline message.
• An agent hits a diagnostic code that wasn't in its training data and wants more context.

The code itself is stable across compiler versions, so cached explanations stay valid.

zero new

Scaffold a fresh package:

zero new cli hello

That creates a directory hello/ with a zero.json manifest and a starter src/main.0. The first argument (cli here) picks a template — an executable command-line app in this case. Zero packages explains the layout in detail.

The --json Habit

Almost every command supports --json. If you're building tooling, an agent harness, or a CI pipeline around Zero, default to the JSON form. It's:

• Stable. The schema is versioned and the team treats it as a contract.
• Complete. You get fields that aren't in the human output (precise spans, repair plan IDs, dependency graph data).
• Parseable. No regex over English prose to extract a line number.

For humans, leave --json off — the formatted text is what you want at a terminal.

Other Useful Commands

A few less-frequently-touched commands that are worth knowing:

• zero graph --json — emits the dependency graph of a package as structured data. Useful for understanding what depends on what, and for agents that want to reason about call sites.
• zero size --json — reports the on-disk size of compiled artifacts, broken down by target. Helpful when you care about binary footprint (which is a Zero design goal).
• zero --version — prints the toolchain version. Pin this somewhere if you're working in a team — Zero is pre-1.0 and breaking changes do land.

Next: Zero Packages

A single .0 file is fine for hello-world. Real projects use packages with a zero.json manifest and a src/ directory. Zero Packages shows how to scaffold one and explains every field.