RunMat Command Line Interface (CLI)

The RunMat CLI is a fast and easy way to run .m files locally, open an interactive REPL, inspect runtime behavior, and work with remote project filesystems.

Install RunMat first if the runmat command is not already on your PATH. See Installation for install options.

To check the version of RunMat, run:

runmat --version

REPL

Run runmat with no command to open the interactive REPL.

runmat

You can also start it explicitly:

runmat repl
runmat repl --verbose

The REPL keeps one session alive, so variables remain available between prompts.

A = magic(3)
sum(A)

REPL commands:

The REPL also accepts piped input:

printf "1 + 1\n" | runmat repl

Run

Run a local .m file by passing the path directly:

runmat analysis.m

The explicit form is:

runmat run analysis.m

RunMat also resolves configured project entrypoints. If a project has runmat.toml with an entrypoint named main, this works:

runmat run main

See Projects for project layout and entrypoint configuration.

For relative source paths, RunMat can infer a missing .m extension:

runmat run src/main

Execution uses the same session pipeline as other hosts: parse, lower, compile, run, emit streams, update workspace, and report structured diagnostics.

Pass Runtime Options

Global options apply to the REPL, local scripts, and most commands.

runmat --no-jit analysis.m
runmat --jit-opt-level aggressive analysis.m
runmat --gc-preset low-latency analysis.m
runmat --plot-headless analysis.m

Common options:

Configuration is resolved from built-in defaults, project files, environment variables, and CLI flags. CLI flags have the highest precedence. See Configuration Reference.

Emit Bytecode

Use bytecode output when debugging the compiler pipeline or checking what a script lowers into before execution.

runmat --emit-bytecode analysis.m

Write the disassembly to a file:

runmat --emit-bytecode bytecode.txt analysis.m

When bytecode emission is enabled, the script is compiled and disassembled instead of being executed.

Capture Artifacts

For batch jobs, CI, and notebook-style hosts, the CLI can write a run manifest and exported figure images.

runmat \
  --artifacts-dir .runmat-artifacts \
  --capture-figures auto \
  --figure-size 1280x720 \
  analysis.m

The manifest records execution metadata, stream sizes, touched figure handles, figure export paths, JIT usage, and any error identifier. Figure capture writes PNG files under the artifact directory when figures are touched or when capture is forced on.

Artifact options:

Inspect Runtime

Use these commands when filing issues, tuning performance, or checking what runtime configuration is active.

runmat info
runmat version --detailed
runmat gc stats
runmat accel-info

Configuration

Generate a starter config:

runmat config generate -o runmat.toml

Inspect resolved configuration:

runmat config show --format toml
runmat config show --format json

Validate and locate config files:

runmat config validate runmat.toml
runmat config paths

config generate writes both project and runtime sections, so the generated file can be used as a starting point for named entrypoints and runtime tuning.

Benchmark

Benchmark a script or named entrypoint with repeated execution in one session.

runmat benchmark analysis.m --iterations 25
runmat benchmark main --iterations 25 --jit

The benchmark command performs warmup runs, then reports total iterations, JIT executions, interpreter executions, total time, average time, and throughput.

Snapshots

Snapshots preload runtime assets so startup does less work.

runmat snapshot create -o stdlib.snapshot --compression zstd -O speed
runmat snapshot info stdlib.snapshot
runmat snapshot validate stdlib.snapshot
runmat snapshot presets

Load a snapshot for a script or REPL:

runmat --snapshot stdlib.snapshot analysis.m
runmat --snapshot stdlib.snapshot

Remote Projects

Remote commands connect the CLI to a RunMat server project. They are useful for hosted workspaces, shared project filesystems, and remote data layouts that should be mounted into local execution.

Authenticate first:

runmat login

# or explicitly specify the server URL

runmat login --server https://api.runmat.com

For automation, pass an API token:

runmat login \
  --server https://api.runmat.com \
  --api-key "$RUNMAT_API_KEY" \
  --project <project-id>

Alternatively, use environment variables to set the server URL and API token:

List and select projects:

runmat org list
runmat project list
runmat project select <project-id>

Use the project filesystem:

runmat project fs ls /data
runmat project fs read /data/input.mat --output input.mat
runmat project fs write /data/input.mat ./input.mat
runmat project fs mkdir /data/results --recursive
runmat project fs rm /data/old.mat

The top-level fs command is a shorthand for the project filesystem namespace:

runmat fs ls /data

Run a script loaded from the remote filesystem:

runmat remote run /scripts/analysis.m
runmat remote run /scripts/analysis.m --project <project-id>

remote run reads the source from the selected remote project, installs the remote filesystem provider for the run, and executes the script locally with the current runtime configuration.

Remote filesystem commands also cover file history, manifest history, snapshots, retention policy, and git-style project sync. Use command help for the full tree:

runmat project fs --help
runmat project retention --help
runmat fs --help

Command Help

Every command and subcommand has built-in help.

runmat --help
runmat run --help
runmat config --help
runmat project fs --help

Use command help as the source of truth for exact flags in the installed version.