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, or Python artifacts. fmt, lsp, doc, explain, refactor, migrate, and package commands operate on the same source/version model.
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 --.
Current support
The 5.6.0 command-line tool provides text and JSON diagnostics, whole-program checks, language 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 explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1