Reference · CLI

Commands

Build, example, test, codegen and quality commands in one place.

5 min read

Your app

These steps come from the template’s templates/minimal-app/build.zig. The app step is registered only for macOS targets.

Terminal

zig build                      # build the executable
zig build run                  # build and run
zig build app                  # package a macOS .app bundle (zig-out/)
zig build -Dtest-mode=true     # enable the automation harness (forwarded to zenit)

Examples in the zenit repo

Every example has two steps: zig build <name> produces an ad-hoc-signed .app, and zig build run-<name> runs the executable directly.

Step.app nameWhat it is

hello-buttonHello ButtonMinimal window and button

counter-reactiveReactive CounterSignal / Memo / Effect demo

virtual-list-perf100k Virtual List100k-row VirtualList stress test

text-inputText Input DemoInput / Textarea with text_core

multi-windowMulti WindowTwo native windows, per-window routing

storybookzenit StorybookAll-component showcase and e2e target

devtools-probeDevTools ProbeReal-window acceptance for the DevTools performance panel

interop-probezenit Interop ProbeRich clipboard / drag-out system verification

console-probeConsole ProbeConsole + DevTools real-window verification

design-probeDesign ProbeTarget for design-mockup comparison

Terminal

zig build run-hello-button
zig build run-counter-reactive
zig build run-storybook

Tests

Suites

CommandWhat it does

testAlias of test-headless

test-headlessDeterministic tests; no live Metal device required

test-allDeterministic plus live-device Metal tests

test-null-backendBuild and run deterministic tests on the Null GPU backend to prove the RHI abstraction

UI and reactivity

CommandWhat it does

test-uiUI system tests; -Dtest-filter=<substring> runs only matching names

test-ui-coreui_core integration tests (src/ui/core/tests.zig)

test-reactiveReactive system tests

test-allocation-campaignSweep allocator failure points across transactional framework boundaries

Rendering and GPU

CommandWhat it does

test-renderRender module tests

test-gpuGPU abstraction tests

test-metalTests that need a live Metal device

test-svgSVG parser / rasterizer tests

test-timing-ringFrame timing ring tests

Text and i18n

CommandWhat it does

test-textText module tests (font catalog / weights)

test-text-coretext_core module tests

test-text-propertiesDeterministic, seedable text-coordinate property tests

test-i18ni18n module tests

test-bidi-conformanceFull Unicode 17.0.0 UAX #9 conformance data

Platform, windows and packaging

CommandWhat it does

test-window-lifecycleDeterministic multi-window lifecycle and routing tests

test-text-hook-ownersProcess-wide text-measurement hook ownership stack (closing one window keeps the others’ hooks)

test-selector-scaleHiDPI FontSelector scale propagation

test-system-sdkSystem SDK tests

test-system-sdk-backendsDeterministic native backend tests

check-system-sdk-crossCompile System SDK tests for Linux / Windows (no run)

test-harnesstest_harness (file-RPC) tests

test-package-consumerBuild and launch a downstream app against direct and Zig-filtered packages

Codegen and tools

CommandWhat it does

benchPerf baselines: zig build bench [-- filter] [-- json=path]

gen-iconsRegenerate the module chosen by -Dicon-set (lucide by default)

gen-icons-lucideRegenerate the public Lucide icon module

gen-icons-commonRegenerate the provider-neutral common icon module

gen-icons-untitled / gen-icons-allInternal icon set; internal checkouts only

gen-component-indexAST-scan src/ui and regenerate component_index_generated.zig

capability-matrixPrint the generated macOS capability matrix

text-corpus-dumpPrint the committed T0 text-coordinate corpus

Build options

OptionDefaultEffect

-Dtest-mode=truefalseEnable the e2e harness (file-RPC server)

-De2e-port=<n>19816E2E port, used in the default RPC directory name

-Dtest-filter=<s>—Run only test-ui tests whose name contains the substring

-Dicon-set=<name>lucideBuilt-in icon provider: lucide or untitled (internal only)

-Dgpu-backend=<name>metalGPU backend: metal or null

NOTE

Forward dependency options explicitly. Zig isolates dependency build options. A downstream app must forward .@"test-mode" and .@"e2e-port" in b.dependency("zenit", ...) for zig build -Dtest-mode=true to reach zenit; the template already does.

Quality scripts

ScriptWhat it checks

./scripts/check_oss_boundary.shStatically checks src/ui imports, then builds hello-button to confirm no forbidden module is reachable

./scripts/check_style_literals.shRatchets bare color / font-size literals in examples down, never up (ui.arb escapes are allowed)

bash scripts/switch_icon_set.sh lucideRuns test-headless and the storybook build with one icon set, without touching the worktree

TIP

Override with ZIG. Repo scripts use the zig on PATH. To pin a specific toolchain, set ZIG=/absolute/path/to/zig.

Bundle checks

Example bundles are ad-hoc signed with the quarantine attribute cleared. These commands verify the signature and list any remaining extended attributes.

Terminal

zig build hello-button
codesign --verify --deep --strict "zig-out/Hello Button.app"
xattr -lr "zig-out/Hello Button.app"

← PREV

Public API

Troubleshooting