Installation

Lute ships as a single command-line tool, lute. It reads .lute scenario files and checks, compiles, traces, and inspects them. The current language version is 0.53.0.

Quick start with bunx

The fastest way to run Lute without installing anything permanently is bunx, which fetches the published npm package and runs its bundled native binary:

bunx @lute-lang/lute check scene.lute

The npm package is named @lute-lang/lute; the command it installs is lute. bunx @lute-lang/lute <args> and a globally installed lute <args> are the same program.

Global install

To keep lute on your PATH for everyday use, install the package globally with bun:

bun add -g @lute-lang/lute
lute check scene.lute

@lute-lang/lute is a thin launcher: it detects your platform and dispatches to a prebuilt native binary shipped as a platform-specific optional dependency (@lute-lang/lute-core-darwin-arm64 or @lute-lang/lute-core-linux-x64). The correct one is selected automatically at install time.

Platform support

Platform	npm core package	Status
macOS (Apple silicon)	@lute-lang/lute-core-darwin-arm64	Supported
Linux (x86-64)	@lute-lang/lute-core-linux-x64	Supported

On an unsupported platform the launcher exits with an actionable error naming the supported matrix. Windows and musl-based Linux are not yet packaged — build from source instead.

Building from source

Lute’s compiler, checker, and CLI are written in Rust. If you have a Rust toolchain, install the CLI directly from a checkout of the repository:

cargo install --path crates/lute-cli

This builds the lute binary (the crate declares [[bin]] name = "lute") and places it in your Cargo bin directory. For a throwaway local build during development, cargo build -p lute-cli produces ./target/debug/lute.

Verify

Whichever route you took, confirm the tool is on your PATH:

$ lute version
lute toolchain 0.53.0
language      0.53.0
IR schema     0.53.0

The three lines are the toolchain (this CLI), the language the checker enforces, and the IR schema that lute compile stamps into every artifact as irVersion. A release sets all three to its own number, so you should see the same version on each line. Why there are three, and how an engine gates on irVersion, is in the versioning policy.

For scripts and CI, --json prints the same three axes as one object:

$ lute version --json
{"toolchain":"0.53.0","language":"0.53.0","ir":"0.53.0"}

(lute --version also works and prints just lute 0.53.0 — the toolchain axis alone.)

If your editor runs the language server, check that it is the same build: lute-lsp --version prints lute-lsp <version>, and lute doctor compares the lute-lsp first on your PATH with the one beside this CLI, flagging an older server (one that predates the flag reports no version at all) with how to reinstall it. When that lute-lsp is the npm launcher, lute doctor compares the binary the launcher starts; if it cannot tell which one that is, the line ends (compared by reported version only).

If your editor and the terminal disagree about a file — red underlines on a file lute check calls ok, or the other way round — trust the terminal and run lute doctor --project . in the project: the usual cause is an editor language server older than your lute, and restarting the editor after an upgrade fixes it.

Next

Head to Write your first scene to build a real .lute file from an empty file, running lute at every step.

Or start from a whole project: lute init <DIR> scaffolds a minimal one, and lute init --template beats <DIR> scaffolds a game driven by beats and occasions — an occasions plugin, beats, a quest, lore entries, a play script, and scenario tests that whole-project lute check, lute test, and lute play pass as scaffolded.