Find the command for your next task and use its diagnostics to locate the file you need to fix. Each section explains what a successful command changes.
Install topaz with First Program. File commands below use its first-program.tpz. For package commands, open the completed study-plan folder from First Application.
Format before checking
topaz fmt --check --root .
topaz fmt --root .fmt --check reports files that differ from Topaz formatting, exits nonzero, and leaves them unchanged. Run the second command to apply formatting. Repeat the first and expect exit code 0. Package formatting skips vendored dependencies and build output.
Check without running
Choose the command for your input. The first and third use a file. The second reads the package entry from topaz.toml.
topaz check first-program.tpz
topaz check --root . --locked
topaz check --format json first-program.tpzA successful check exits with code 0 without running user code or creating a deployment product. A diagnostic gives the source location, a stable TPZ#### code, a summary, and relevant detail. JSON mode provides these diagnostics for tools.
topaz explain TPZ5021
topaz explain TPZ5021 --jsonThese commands print the explanation of TPZ5021 as text or JSON and leave source files unchanged. Fix the first reported error and rerun check. Later errors may follow from the first.
For an import error, check the file path, selected root, and exported name in Modules & Visibility. For a lock mismatch, follow Packages & Distribution.
Check a usage profile
A usage profile adds rules for a particular kind of code. Run the first command on your single file, or the second inside the study-plan package.
topaz check --profile agent-pack first-program.tpz
topaz check --profile test-profile tests/plan.tpz --root .| Construct | agent-pack | test-profile |
|---|---|---|
Built-in assert, including references used as values | Rejected | Accepted |
std.test imports and Test.* members | Rejected | Rejected |
Function composition with >> | Rejected | Rejected |
Your own function named assert | Checked as application code | Checked as application code |
A successful profile check exits with code 0. A rejected construct produces TPZ5801 with a rule note such as agent-pack/no-composition. The study-plan test uses the built-in assert and passes test-profile.
With --format json, standard error (stderr) contains one topaz.profile-diagnostic/v1 object per diagnostic. Standard output (stdout) contains a topaz.profile-check/v1 summary. Use --profile with check and current-mode Topaz syntax. It cannot be combined with --exports-json.
The compiler-kernel Bootstrap Profile is described in Toolchain Status.
Test and run
Inside the study-plan package, select the test file and then run the application.
topaz test tests/plan.tpz --root . --locked
topaz run --root . --lockedThe test reports test-ok. The program prints tasks=2, remaining=25 minutes. test runs checked code in the deterministic test host. A failed assertion, static error, or runtime fault exits nonzero. With --root, the selected test retains the package manifest, lock file, modules, and dependencies.
Without a file argument, test --root . selects the manifest entry. Pass each test file explicitly to run it.
run executes the checked entry through the interpreter. Put program arguments after --, as in topaz run --root . --locked -- arg1 arg2. They reach main through its argument array. The study planner ignores these arguments and still prints tasks=2, remaining=25 minutes.
Build a delivery target
The first command builds a file. The second builds the study-plan package.
topaz build first-program.tpz --out-dir native-product
topaz build --root . --locked --release --out-dir productbuild creates the chosen directory with the runnable product and topaz-artifact.json. Native and Web builds use the Rust toolchain installed for their target. Source is checked before execution or artifact generation. A static error stops the command before it produces a runnable artifact.
External tool errors also exit nonzero. Follow the reported toolchain error. If the output directory contains another target, an invalid manifest, or changed generated files, Topaz stops. Preserve the directory for inspection and choose a new empty --out-dir.
Related documentation
- Toolchain Overview gives the workflow and editor setup.
- Packages & Distribution explains manifests, dependencies, and locks.
- Toolchain Status explains the default self compiler and installation information.