The CLI applies identical parsing, module resolution, and static checks to a single file or a package. The executed command determines downstream processing after this 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-appRun 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.tpzA clean check exits zero. Diagnostics include the source location, a stable TPZ#### code, a 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 --jsonFix the first diagnostic and rerun check. Later errors can be consequences of the first one. explain expands a known code without modifying source code.
Narrow a check to one usage profile
check accepts --profile to narrow canonical Topaz to a smaller executable usage profile. A program that passes an ordinary check can still fail a profile check.
topaz check --profile agent-pack main.tpz
topaz check --profile test-profile tests/plan.tpzagent-pack accepts only the constructs that belong in ordinary application code. It rejects assert, the std.test import, Test.* members, and >> function composition, treating them as test-only or specification-level forms rather than production code. test-profile allows the canonical free assert(...) and rejects the same composition and test-framework surface. The Bootstrap Profile for compiler-kernel source is described in Toolchain Status.
Human diagnostics carry the stable TPZ5801 code and a rule note such as agent-pack/no-composition. With --format json, stderr holds one topaz.profile-diagnostic/v1 object per diagnostic and stdout holds one topaz.profile-check/v1 summary object. --profile belongs to check alone. It requires canonical current-mode Topaz and does not combine with --exports-json.
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 arg2test 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 file, 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 productbuild performs checks first, then writes the requested managed product. Native, Web, and HTTP builds require their external Rust target. Python products require Python only when executed. Static errors halt execution prior to artifact creation. External tool errors are reported after the primary Topaz stage and still exit 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 select a new empty --out-dir.
Package and machine boundaries
Omit the entry file and pass --root to use the entry point defined in topaz.toml. --locked requires 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.