The CLI applies the same parsing, module resolution, and static checks to a single file or a package. The command selects what happens after that shared gate.
Format before checking
Use fmt --check in review and automation. It reports every file whose
canonical formatting differs, exits nonzero, and writes nothing.
topaz fmt --check --root my-app
topaz fmt --root my-app
Run the second command to apply formatting, then repeat the first. Package mode skips vendored dependencies and build output.
Check without running
topaz check main.tpz
topaz check --root my-app --locked
topaz check --format json main.tpz
A clean check exits zero. A diagnostic includes a source location, stable
TPZ#### code, summary, and relevant detail. JSON mode emits stable
machine-readable diagnostics. No user code runs and no deployment artifact is
written.
topaz explain TPZ5021
topaz explain TPZ5021 --json
Fix the first diagnostic and rerun check; later errors can be consequences of
the first one. explain expands a known code but does not modify source.
Test and run
topaz test --root my-app --locked
topaz test tests/summary.tpz --root my-app --locked
topaz run --root my-app --locked
topaz run main.tpz -- arg1 arg2
test uses the checked deterministic test host. A failed assertion, static
diagnostic, or runtime fault exits nonzero. Selecting a test file with
--root keeps the package manifest, lock, modules, and dependencies.
run executes a checked command entry through the interpreter. Arguments after
-- are passed to main. Web Application and HTTP packages use topaz dev
for loopback development because their observable product is a browser app or
service rather than a command entry.
Build one delivery target
topaz build main.tpz --out-dir native-product
topaz build --target python --root my-app --locked --out-dir python-product
topaz build --root my-app --locked --release --out-dir product
build checks first, then writes the requested managed product. Native, Web,
and HTTP builds require their external Rust target; Python products require
Python only when run. A static error stops before artifact creation. An
external-tool error is reported after the primary Topaz stage and still exits
nonzero.
If the output directory contains a different target, a malformed artifact
manifest, or changed managed bytes, Topaz refuses to guess ownership. Keep the
directory for inspection and choose a new empty --out-dir.
Package and machine boundaries
Omit the entry and pass --root to use the entry in topaz.toml. --locked
requires the current manifest and local dependency contents to match
topaz.lock. Program arguments always follow --.
--unchecked is a compiler-investigation escape hatch, not a normal
application command. It removes the static gate and must not be used to make a
failed checked build appear successful.