Skip to content

cli.md

Latest commit

 

History

History
362 lines (257 loc) · 12.2 KB

cli.md

File metadata and controls

362 lines (257 loc) · 12.2 KB
Raw
title Command Line Interface
category Getting Started
section 1.3
last_updated July 31, 2026

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:

Command Use
help Show REPL help.
exit, quit Leave the REPL.
.info Show runtime information.
.stats Show execution statistics.
.gc, .gc-info Show garbage collector statistics.
.gc-collect Force a major collection.
.reset-stats Reset execution statistics.
!cmd Run cmd in the platform shell and print stdout/stderr.

Shell escapes are local CLI REPL behavior. A line such as !pwd runs pwd through the host shell without submitting it to the RunMat parser. Non-zero shell exits are reported at the prompt and do not close the REPL. .m scripts and other hosts do not treat leading ! as a shell escape.

The REPL also accepts piped input:

printf "1 + 1\n" | runmat repl
printf "!pwd\n1 + 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 run also runs .fea study and parametric sweep files:

runmat run studies/bracket_static.fea
runmat run --json studies/bracket_static.fea

The default .fea output is a concise run summary with the run_id, quality status, evidence path, and a fea.results("<run_id>") post-processing hint. Use --json when automation needs structured output.

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

% runmat.toml
[entrypoints.main]
path = "src/main.m"
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.

Check

Use runmat check before running a .m script or .fea study:

runmat check analysis.m
runmat check --path ./toolbox analysis.m
runmat check -D warnings analysis.m
runmat check --json analysis.m
runmat check studies/bracket_static.fea
runmat check --json studies/bracket_static.fea

For .m files, check runs the same parser, HIR and MIR lowering, static analysis, source lookup, and compile validation used by editor tooling without executing the script. It reports syntax and semantic errors, proven type or shape incompatibilities, and function calls that cannot be resolved from builtins, the file, or the configured project sources. --path DIRECTORY adds an explicit MATLAB lookup root for the check and may be repeated.

Dynamic MATLAB behavior is reported without being rejected by default. For example, a function that is not present in the static source catalog produces a warning, and a call after addpath identifies that path mutation as the reason the final target must be selected and loaded at runtime. This warning describes a supported dynamic execution boundary, not an execution failure; use [sources].roots or --path when the target should participate in static cross-file analysis. Warnings leave the command successful, while errors return a nonzero exit code. Use -D warnings (or -D warning) when CI should also return nonzero for any warning.

The default output is human-readable and includes diagnostic codes, source locations, related causal locations, notes, and help. For .m files, --json emits the stable schema_version: 1 envelope with an explicit outcome (clean, warnings, or failed), per-domain analysis completeness, structured diagnostics with byte and line/column spans, and summary counts. A failed check still emits that JSON payload before returning nonzero.

For .fea files, check loads geometry, resolves selectors, validates the study or sweep, and builds the solve plan without running the solver.

FEA JSON mode returns structured validation and plan payloads for CI and tooling.

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:

Option Use
--config PATH Load a specific runmat.toml or runmat.json.
--color MODE Control ANSI styling for human output (auto
--debug Enable debug logging.
--log-level LEVEL Set log verbosity.
--verbose Print more execution detail.
--no-jit Use the interpreter only.
--jit-threshold N Set the execution count before JIT tiering.
--jit-opt-level LEVEL Set JIT optimization policy.
--gc-preset PRESET Select a GC tuning preset.
--gc-young-size MB Override young generation size.
--gc-threads N Override GC worker count.
--gc-stats Collect GC statistics.
--plot-mode MODE Select plotting mode (auto
--plot-headless Force headless plotting.
--plot-backend BACKEND Select plotting backend (auto

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

Color and Terminal Output

RunMat uses restrained ANSI styling for human-readable diagnostics, help, headings, status messages, and summaries. The default --color=auto mode checks stdout and stderr independently, styles only streams connected to capable interactive terminals, and stays plain when output is redirected, TERM=dumb, or a non-empty NO_COLOR value is present.

Use the global color option before or after a subcommand:

runmat --color=never check analysis.m
runmat check analysis.m --color=never
runmat --color=always check analysis.m | less -R

An explicit --color=always or --color=never overrides the environment. Without an explicit option, a non-empty NO_COLOR disables color; CLICOLOR=0 also disables it; and CLICOLOR_FORCE or FORCE_COLOR can request color for eligible human output. NO_COLOR takes precedence over those environment force variables. An empty NO_COLOR value is treated as unset.

Structured and byte-oriented output remains plain even under --color=always. This includes JSON, TOML configuration, bytecode, stable tab-separated remote listings, telemetry payloads, and raw remote file contents. RunMat also leaves MATLAB stdout and stderr, displayed MATLAB values, and REPL shell-command output unchanged.

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:

Option Use
--artifacts-dir PATH Directory for run artifacts.
--artifacts-manifest PATH Exact JSON manifest path.
--capture-figures MODE Figure export policy (off
--figure-size WIDTHxHEIGHT Figure export dimensions.
--max-figures N Maximum number of touched figures to export.

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
Command Use
info Print version, runtime configuration, environment, and GC status.
version --detailed Print build details useful for support and bug reports.
gc stats Print current GC counters.
gc minor, gc major Force a minor or major collection.
gc config Print current GC configuration.
accel-info Print acceleration provider and telemetry details.
accel-info --json Emit acceleration details as JSON.

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.

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:

Variable Use
RUNMAT_CONFIG Runtime config path.
RUNMAT_SERVER_URL Remote server URL.
RUNMAT_API_KEY Remote API token.
RUNMAT_ORG_ID Default remote org.
RUNMAT_PROJECT_ID Default remote project.

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.