CLI Overview

The @modelscript/cli package provides two identical binary executables: modelscript and its shorthand alias msx. The command-line interface serves as the primary headless automation driver for compiling, simulating, verifying, linting, rendering, and orchestrating polyglot engineering systems across local workspaces, CI/CD pipelines, and cloud HPC clusters.

Installation

You can run the CLI directly from the monorepo workspace using npx, or install it globally for system-wide access:

# Run directly via npx
npx msx --help

# Install globally
npm install -g @modelscript/cli
msx --version

Global Options & Environment Variables

The CLI parser (apps/cli/src/main.ts) intercepts global execution flags prior to command dispatch and respects standard environment variables for headless CI/CD and enterprise hub integration:

Global Flags

Flag	Type	Description
--daemon	boolean	Route command execution through the persistent background compiler daemon (~/.modelscript/daemon.sock) to bypass cold-start WASM initialization and reuse warm Salsa caches.
--help	boolean	Display usage information and command-specific options.
--version	boolean	Print the installed @modelscript/cli semantic version.

Environment Variables

Variable	Default	Description
NO_COLOR	Unset	When set to any non-empty value, disables ANSI color sequences in terminal diagnostics, tables, and diff output.
ANSATZ_API_URL / MODELSCRIPT_API_URL	http://localhost:3000	Base URL for the Ansatz Platform, Package Registry, and Cloud HPC dispatch API (~/.ansatzrc / ~/.modelscriptrc fallback).
ANSATZ_API_TOKEN / MODELSCRIPT_API_TOKEN	Unset	Bearer token (JWT or ms_bot_* service token) used for non-interactive authentication against the Registry, Cloud HPC, and Hub APIs (also accepts ANSATZ_TOKEN or MODELSCRIPT_TOKEN).
MSX_EDITION	ee	Runtime edition selector (ee for Enterprise Edition, ce for pure AGPL-3.0-or-later Community Edition). Setting MSX_EDITION=ce disables all @modelscript/ee commands and subsystems.
MSX_LICENSE_KEY	Unset	Offline Ed25519-signed Enterprise license token (msx_lic_<payload>.<sig>) unlocking Enterprise CLI commands (cloud, hil, attest, digital-twin, compliance, oslc, sysmlv2-api).
MSX_LICENSE_ENFORCE	false (true in prod)	When true, strictly requires a valid MSX_LICENSE_KEY before executing Enterprise CLI commands (otherwise runs in 30-day local evaluation mode).

Persistent Compiler Daemon (--daemon)

Standard CLI invocations spin up an isolated Node.js process, compile or load .wasm parser binaries, and index workspace dependencies from disk. When iterating rapidly or running hundreds of checks in a pre-commit hook, pass --daemon to any command:

# Start or auto-spawn the background daemon and run lint with warm Salsa caches
msx lint model.mo --daemon

# Explicitly manage the daemon lifecycle
msx daemon status
msx daemon restart
msx daemon stop

When --daemon is passed, msx connects to the local Unix domain socket (~/.modelscript/daemon.sock on Linux/macOS or named pipe \\.\pipe\modelscript-daemon on Windows). If no daemon is running, the CLI automatically spawns one in the background, waits for readiness, and streams the command's stdout, stderr, and exit code back to the terminal.

Complete Command Reference by Category

The msx CLI registers 41 commands (plus ergonomic aliases) organized into six functional domains. See CLI Commands for exhaustive flag tables and examples for every command.

1. Compilation, Simulation & Optimization

Command	Aliases	Summary
compile	flatten	Flatten a Modelica class hierarchy into a canonical Differential-Algebraic Equation (DAE) system.
instantiate	—	Instantiate a Modelica class and print its resolved component and equation structure.
simulate	—	Execute numerical DAE/ODE time-domain or steady-state simulations (JS, Arena, WASM, C, JIT, WebGPU, or Cloud HPC).
optimize	—	Solve nonlinear Dynamic Optimization and Optimal Control Problems (OCP) via direct collocation.
grad	—	Compute forward/adjoint parameter sensitivities ($\partial J/\partial p$) and finite-difference gradients.
surrogate	—	Run Design of Experiments (DoE), train Neural/Polynomial/RBF surrogates, and export ONNX/C/Modelica ROMs.
mc	—	Execute multi-threaded Monte Carlo uncertainty quantification and reliability sweeps.
csg	—	Extract Constructive Solid Geometry (CSG) primitives from Modelica models into 3D CAD meshes.

2. Linting, Formatting, Diffing & Localization

Command	Aliases	Summary
lint	—	Run static syntax, type, structural, and control-flow diagnostics across polyglot workspace files.
parse	—	Parse source files with the native WebAssembly GLR parser and inspect the concrete syntax tree (CST).
format	—	Format source files canonically using CST-preserving pretty-printing.
unparse	—	Round-trip a parsed CST back into source text to verify lossless grammar unparsing.
diff	—	Compute structural AST/CST and semantic DAE diffs between two files or Git revisions.
pr-diff	—	Generate visual SVG/HTML architectural diffs and Markdown PR review comments against a base Git ref.
i18n	—	Extract translatable strings, compile locale catalogs, and translate model identifiers across languages.

3. Formal Verification, Safety & Test Synthesis

Command	Aliases	Summary
verify	—	Verify decision tables, assume-guarantee contracts, and state machines; emit SARIF/JUnit/HTML reports.
falsify	—	Search for Signal Temporal Logic (STL) counterexamples by minimizing robustness $\rho (\varphi ,\mathbf{x},t)$.
export-formal	—	Export SysML v2 models to formal verification formats (smt2, nuxmv, ocra).
verify-decisions	—	Verify architectural decision records (ADRs) and parameter trade-space bounds against formal system models.
decompose	—	Perform assume-guarantee contract decomposition and structural subsystem partitioning.
generate-tests	—	Synthesize MC/DC-complete unit test vectors and stimulus harnesses from formal model constraints.

4. Polyglot Digital Thread, Co-Simulation & Standards Interop

Command	Aliases	Summary
render	—	Render headless SVG diagrams for Modelica icons/schematics, SysML v2 (BDD/IBD/State/Activity), and PSCAD SLDs.
fmu	export-fmu	Package models into FMI 2.0/3.0 Functional Mock-up Units (.fmu) or inspect/import existing FMUs.
import-fmu	fmu-import	Unpack an external .fmu archive and generate typed Modelica wrapper blocks and SSP bindings.
cosim	—	Orchestrate and inspect distributed FMI/SSP Co-Simulation sessions, participants, and adaptive step optimizers.
pscad	—	Lint, render SLDs, diff, simulate EMT transients, verify IEEE 2800 ride-through, and export .pscx/.pswx projects.
polyglot	—	Query cross-language symbol indices, verify digital thread links, and check operational digital twin drift.
align	—	Reconcile Triple Graph Grammar (TGG) correspondences across SysML v2, Modelica, Spice, and STEP artifacts.
sysml	—	Export, import, check, inspect, and bi-directionally synchronize SysML v2 .sysml and Modelica .mo models.
oslc	—	Export OSLC 3.0 RDF/Turtle/JSON-LD catalogs or launch a live OSLC Tracked Resource Set (TRS 3.0) server.
reqif	—	Import and export OMG ReqIF 1.2 (.reqif / .reqifz) requirements exchange archives.
ddp	—	Inspect, pack, and convert ISO/PAS 81346 Digital Data Packages (.ddp) and Asset Administration Shells (.aasx).
dhf	—	Generate, audit, and inspect FDA 21 CFR Part 820 / ISO 13485 Design History File (DHF) compliance dossiers.

5. Language Workbench, Daemon & IDE Tooling

Command	Aliases	Summary
daemon	—	Manage the persistent background compiler daemon (start, stop, status, restart).
build	—	Compile a grammar DSL definition into a native WebAssembly GLR parser (parser.wasm) and TypeScript types.
generate	—	Scaffold new WASM GLR parsers or standalone VS Code language extensions from a grammar module.
language	lang	List, dynamically register, or unregister custom language plugins in the workspace registry.
lsp	—	Launch the multi-language ModelScript Language Server Protocol (LSP) server over stdio or TCP/IPC sockets.
playground	—	Start a local interactive web playground server for testing grammars, CSTs, and DAE compilation.
sandbox	—	Execute untrusted scripts or models inside a resource-capped, capability-isolated WebAssembly sandbox.

6. Package Registry, Cloud HPC & Hub Administration

Command	Aliases	Summary
init	—	Initialize a new modelscript.json package manifest in the current directory.
login	—	Authenticate with the Ansatz Package Registry / Platform and store credentials in ~/.ansatzrc.
logout	—	Remove stored authentication tokens from ~/.ansatzrc / ~/.modelscriptrc.
whoami	—	Display the currently authenticated user, organization roles, and active registry endpoint.
install	i, add	Resolve, verify, and install versioned dependencies from the Ansatz Package Registry into modelica_modules/.
pack	—	Create a deterministic, SHA-256 content-addressed .zip package archive from the workspace.
publish	—	Sign (Ed25519) and publish a package archive to the Ansatz Package Registry.
unpublish	—	Retract or deprecate a published package version from the Ansatz Package Registry.
cloud	—	Dispatch containerized simulation and CAE jobs to remote Slurm HPC clusters and manage compute credits.
hub	ansatz, node	Initialize or check the health status of a self-hosted Ansatz / ModelScript node.
db	—	Inspect, migrate, and cryptographically verify the Hub SQLite/PostgreSQL database schema and audit chains.
archive	—	Request, monitor, and download cold-storage compliance archives from the Hub.

Return Codes & CI/CD Integration

All msx commands return POSIX-compliant exit codes suitable for gating GitHub Actions, GitLab CI, or Jenkins pipelines:

Exit Code	Meaning
0	Command succeeded with zero errors (or all verification obligations proved SAFE).
1	Compilation error, static lint error (severity: "error"), counterexample falsification found, or runtime failure.
2	Invalid CLI arguments, missing required flags, or unreadable input paths.