Project commands

[commands] declares the project’s own commands. Each one runs a file in the project as luau-run <name>:

luau-run.toml

[commands.bench]
description = "Run the benchmarks"
entry = "tools/Bench.luau"
runtime = "lute"
timeout-seconds = 600

luau-run bench --quick then runs tools/Bench.luau on Lute with --quick after it.

Field	Required	What it holds
description	Yes	One line saying what the command does.
entry	Yes	A path from the project’s folder to the file to run: .luau for lute and luau, .ts for bun. It must lie inside the project, even after following links.
runtime	Yes	lute, luau or bun.
requirements	No	Up to 64 names of tools the command needs, each pinned with Rokit or Aftman.
runtimeArgs	No	Up to 64 options given to the runtime before the entry.
timeout-seconds	No	1 to 2,147,483. Without it, the command runs until it ends or you stop it.

A command’s name is lowercase letters, digits and hyphens, starting with a letter, and cannot be one of Luau Run’s own commands: doctor, init, onboard, pin, plan, run, self-install, setup, test, uninstall or update.

Each runtime runs the entry this way:

Runtime	Runs	With
lute	lute run <runtimeArgs> <entry> <arguments>	The Lute luau-run test uses in this folder. If the project’s rokit.toml pins another Lute, Luau Run warns and still runs this one.
luau	luau <runtimeArgs> <entry> -a <arguments>	The luau the project pins with Rokit or Aftman.
bun	bun --no-install <runtimeArgs> -- <entry> <arguments>	The bun on PATH.

An option in runtimeArgs that could replace the entry or run other code, such as Bun’s --eval, is refused.

luau and each name in requirements must be pinned with Rokit or Aftman and installed. The pin can be in the project’s folder, a folder above it, or your own ~\.rokit or ~\.aftman. Otherwise the command is refused, and the message says what to run, such as rokit install. A Foreman pin is refused, since Foreman picks the newest installed match each run. A path you name for the tool replaces the pinned program, but the pin must still be there.

The command runs in the folder you ran it from, with your terminal’s input and output, and Luau Run exits with its exit code. Luau Run exits 64 when it refuses the command, 2 when the command reaches timeout-seconds, and 70 on a fault of its own.

Ctrl+C reaches the command itself, so it can clean up, and Luau Run waits for it to exit. A second Ctrl+C ends Luau Run and the command at once.

On Windows, everything the command starts ends with it. When the command exits, Luau Run ends anything still running a second later and names it in warning[command.left-process-running]. The command’s exit code is kept. At timeout-seconds, everything it started ends at once.