First Program

Outcome: create one .tpz file, check it before execution, run it, and repair one mistake from the checker’s source span.

Prerequisite: choose a starting point on the Learning path; use a local terminal for the exact commands below.

Install the command

On macOS or Linux:

BASH

curl -fsSL https://topaz.ooo/install.sh | sh

On Windows PowerShell:

POWERSHELL

irm https://topaz.ooo/install.ps1 | iex

If Node is already installed:

BASH

npm install -g topaz-lang

Confirm the installed product:

BASH

topaz version

Output

Topaz 5.11.0

You do not need a repository clone, package manifest, Rust, or Python for this first program.

If you use VS Code or an Open VSX-compatible editor, install the official Topaz extension from the Visual Studio Marketplace or the Open VSX Registry. It recognizes .tpz files, shows the Topaz file icon, and adds syntax highlighting. Diagnostics still come from topaz check.

Write the smallest study plan

Create first-program.tpz with these exact contents:

TOPAZ

let topic = "Topaz basics"
let minutes: int = 25
print("{topic}: {minutes} minutes")

Check the source, then run it:

BASH

topaz check first-program.tpz
topaz run first-program.tpz

check validates the file without executing it:

Output

first-program.tpz: types-ok (1 module)
first-program.tpz: resolve-ok (1 module)

run passes the same static gate and then prints:

Output

Topaz basics: 25 minutes

Read the program in the same order you observe it. The first let binds a string and lets the checker infer its type. The second binding writes int explicitly, so the checker must confirm that 25 is an integer. print evaluates the interpolated expressions inside {...} and writes one line.

Read and repair a diagnostic

Make a separate file named first-program-error.tpz. This source is intentionally invalid, so it is shown as plain text rather than as a runnable Topaz example:

let topic = "Topaz basics"
let minutes: int = "25"
print("{topic}: {minutes} minutes")

Run:

BASH

topaz check first-program-error.tpz

The checker does not execute the file. It identifies the declared type, the type it found, and the exact source span:

Output

error[TPZ5001]: expected `int`, found `string`
 --> first-program-error.tpz:2:20
  |
2 | let minutes: int = "25"
  |                    ^^^^

first-program-error.tpz: 1 type diagnostic

Repair the highlighted value by changing "25" to 25. Running topaz check first-program-error.tpz now succeeds, and topaz run first-program-error.tpz produces the same line as the working program above.

Decision: check or run?

Use topaz check while editing because it answers “Is this source valid?” without starting the program. topaz run performs the same static gate and then lets you observe behavior. Running check separately is a fast no-execution step, not an extra gate that run skips.

Try this

Change topic to "Functions" and minutes to 30. What should the program print?

Answer

It prints Functions: 30 minutes. Both edits preserve the inferred string and declared int types, so topaz check first-program.tpz still succeeds before the run.

Ready to continue when

You can create a .tpz file, run topaz check and topaz run, and use the expected/found types plus the highlighted source span to repair the invalid value.

Continue to Values and Functions. Use Syntax at a Glance when you need a compact spelling reminder.