CLI reference
Every command, flag and exit code.
CLI reference
The CLI installs as microstudio, and as @microstudio/cli under the same
package. It is the same binary either way.
microstudio — a local, headless Roblox development runtime
Usage: microstudio [<file.luau>] [-e <code>] run a script, or prompt
microstudio <dev|test|repl|run> [options]Arguments are parsed by hand, with these rules:
- The first token is treated as a command only when it does not start with
-. A bare-is not a flag: it means "read the script from stdin". - A value flag accepts either
--flag valueor--flag=value. - Anything that is not a flag is a positional argument.
Global flags
| Flag | Type | Effect |
|---|---|---|
-h, --help | boolean | print the help text and exit 0 |
-v, --version | boolean | print microstudio <version> and exit 0 |
The subcommands help and version do the same thing.
run
Runs a Luau file, a -e snippet, or stdin on a fresh world, with the full Roblox
API available and nothing read from disk.
microstudio [<file.luau>] [-e <code>] [-]
microstudio run [<file.luau>] [-e <code>] [--interactive] [--watch]
[--clock virtual|real] [--state-dir <path>]| Flag | Type | Default | Effect |
|---|---|---|---|
<file.luau> | positional | — | a script to run; a path that is not a file is an error |
- | positional | — | read the script from stdin |
-e <code>, --eval <code> | string | — | run one line of Luau |
--interactive | boolean | off | keep the world running and prompt into it after the script finishes |
--watch | boolean | off | re-run the file when it changes (requires a file, not -e or stdin) |
--clock virtual|real | enum | see below | virtual time, or wall time |
--state-dir <path> | path | see state directory | where simulated services keep their JSON |
With no file, -e or -, MicroStudio starts a prompt instead — see
The REPL.
Clock selection: a plain script runs on the virtual clock and finishes as
fast as the CPU allows. --clock real selects wall time, and --interactive
alone also selects wall time so the prompt and the script share a live clock.
Passing --clock virtual forces virtual time.
Exit codes:
| Code | Meaning |
|---|---|
0 | the script (and the work it scheduled) completed without errors |
1 | the script errored, or the run recorded an error |
2 | no script exists at the given path |
dev
Reads the Rojo project, loads the compiled Luau into a live DataModel and runs
the server scripts. Runs until Ctrl-C, unless --once is given.
microstudio dev [dir] [--project <file>] [--services a,b]
[--once] [--interactive] [--watch] [--clock virtual|real]
[--timeout <seconds>] [--state-dir <path>]| Flag | Type | Default | Effect |
|---|---|---|---|
[dir] | positional | working directory | the directory a Rojo project is searched from |
--project <file> | path | searched for automatically | the Rojo project file to read |
--services <a,b> | comma-separated names | the server-side set | which services to mount |
--once | boolean | off | boot, drive for --timeout, then exit |
--timeout <seconds> | number | 0.1 | how long --once drives the project, in seconds |
--interactive | boolean | off | keep running and prompt for Luau against the live world |
--watch | boolean | off | restart the session when a mount or the project file changes |
--clock virtual|real | enum | real | wall time, or virtual time that only moves on :advance |
--state-dir <path> | path | <project>/.microstudio | where simulated services keep their JSON |
Exit codes:
| Code | Meaning |
|---|---|
0 | the session stopped with no recorded errors |
1 | the run recorded one or more errors (this is what --once reports for CI) |
2 | no Rojo project file was found |
test
Finds the project's specs, gives each file its own world, and reports the result.
microstudio test [dir] [--project <file>] [--include <glob>] [--exclude <glob>]
[--module path=file] [--services a,b] [--isolate]
[--timeout <ms>] [--json] [--watch] [--tsconfig <file>]
[--no-compile] [--state-dir <path>]| Flag | Type | Default | Effect |
|---|---|---|---|
[dir] | positional | working directory | where to look for specs, and the directory a Rojo project is searched from |
--project <file> | path | searched for automatically | the Rojo project to read |
--include <glob> | comma-separated globs | **/*.spec.luau, **/*.spec.lua, **/*.test.luau, **/*.test.lua, and their .ts/.tsx spellings | which files are specs |
--exclude <glob> | comma-separated globs | the compiled output directory and rbxts_include | files the spec walk skips |
--module path=file | repeatable by comma | — | inject a ModuleScript from a file, e.g. --module ReplicatedStorage.Counter=src/counter.luau |
--services <a,b> | comma-separated names | the server-side set | which services to mount when loading the project's instances |
--isolate | boolean | off | rebuild the world from the project before every test |
--timeout <ms> | number | 5000 | per-test watchdog, in milliseconds; 0 disables it |
--json | boolean | off | print the whole report as JSON: { summary, files } |
--watch | boolean | off | re-run everything when a .lua/.luau/.ts file changes |
--tsconfig <file> | path | <root>/tsconfig.json | the config TypeScript specs are compiled with |
--no-compile | boolean | off | skip running the project's rbxtsc; run an existing build |
--state-dir <path> | path | <project>/.microstudio, or in memory | where simulated services keep their JSON |
Exit codes:
| Code | Meaning |
|---|---|
0 | every test passed, was skipped, or is a todo |
1 | at least one test failed, or no spec files were found |
2 | a compile or configuration failure (missing tsconfig.json, no roblox-ts compiler, an uncompiled spec, or a bad --module value) |
See Writing tests for the DSL and the report format.
repl
Loads the project's instances and prompts for Luau, without running the project's scripts.
microstudio repl [dir] [--project <file>] [--services a,b]
[--state-dir <path>]| Flag | Type | Default | Effect |
|---|---|---|---|
[dir] | positional | working directory | the directory a Rojo project is searched from |
--project <file> | path | searched for automatically | the Rojo project file to load; with none, the prompt opens on a fresh world |
--services <a,b> | comma-separated names | the server-side set | which services to mount |
--state-dir <path> | path | <project>/.microstudio | where simulated services keep their JSON |
repl always uses the virtual clock. It exits 0 when the prompt is quit.
Environment
| Variable | Effect |
|---|---|
MICROSTUDIO_RUNTIME_BIN | use this sidecar binary instead of the installed one; it must exist, or the driver fails loudly |
MICROSTUDIO_TARGET_DIR | cargo target directory to search for the sidecar |
CARGO_TARGET_DIR | same, for redirected cargo output |
MICROSTUDIO_STATE_DIR | same as --state-dir |
MICROSTUDIO_PROJECT_DIR | the directory a hand-started sidecar appends .microstudio to |
MICROSTUDIO_SECRET_<NAME> | a secret HttpService:GetSecret can read |