The CLI is organized around one invariant: run, test, emit, and build receive the same parse/resolve/type gate as check. A static failure stops execution or artifact production and is reported as a Topaz diagnostic.
Contract and components
parse and dump-ast inspect syntax; check validates a compilation unit and can emit deterministic JSON diagnostics or public exports; run interprets; test uses TestHost; emit lowers to Rust; build creates native, web, web-worker, web-app, or Python artifacts. dev serves and rebuilds only a package-mode web-app on loopback. fmt, lsp, doc, explain, refactor, migrate, and package commands operate on the same source/version model. Topaz 5.7.0 includes the web-app target and dev command in the public CLI.
Workflow
Pass an entry and optional --root for an explicit unit, or omit the entry for package mode. Use --language-version only when selecting a compatibility lane; the default is 5.6. Human diagnostics optimize for source reading, while --format json and explain --json provide stable machine fields and codes. Program arguments follow --.
topaz fmt --check uses the same parse-gated formatter and package file selection as topaz fmt, but reports every drifted path and exits nonzero without writing source or metadata. It skips vendored dependencies and build output in package mode.
Topaz 5.6.4 adds check --profile agent-pack as an executable source-form boundary over canonical topaz-5.7. It rejects forms that the language accepts but the agent profile excludes, before any program runs. In JSON mode, stderr is a topaz.profile-diagnostic/v1 JSONL stream with profile, rule, source span, and a machine-applicable identifier fix when one is unambiguous; stdout is one topaz.profile-check/v1 summary. test-profile explicitly permits the canonical test-only assert(...) function. Fence labels, example self-containment, and SPEC citations still require pack or documentation review; public-docs likewise remains a documentation check because prose, localization, and page metadata are not compiler properties.
Current support
The current public 5.7.0 command-line tool provides text and JSON diagnostics, whole-program checks, language and profile selection, formatting, LSP support, refactoring, migration, package, and documentation commands. Examples in this manual are checked or executed with the same command-line behavior.
Boundaries and limitations
--unchecked skips the normal static check for compiler investigation and should not be used for application builds. --backend native may fall back to the general boxed representation when an operation cannot be specialized safely. Topaz reports its own diagnostic before showing additional errors from external tools.
Command reference
topaz check --root . src/main.tpz
topaz check --format json src/main.tpz
topaz check --profile agent-pack --format json src/main.tpz
topaz fmt --check --root .
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1