Skip to main content

Simulator CLI

The sim command-line tool creates and checks simulation workspaces, compiles simulation artifacts, and runs scenarios.

Install and get help​

Install the CLI from the Sedaro Cargo registry, preserving its reviewed lockfile:

cargo install --locked --registry sedaro-crates sim_cli

If you wish to use Sedaro's Artifact Storage client as an output target, you must install the CLI with the net feature as follows:

cargo install --locked --registry sedaro-crates sim_cli --features net

The Cargo package is named sim_cli; its executable is sim.

sim --help
sim --version
sim build --help
sim run --help
sim plugin new --help
sim plugin build --help

Create and check a workspace​

Create a new workspace or scaffold into an existing directory:

sim new ./my-simulation
sim init .

sim new creates a workspace at the supplied path. sim init adds the workspace scaffold to an existing (usually empty) directory; its path defaults to the current directory. Both commands create Rust and Python workspaces by default. Use --no-rust or --no-python to omit those workspaces, or --vcs none to skip Git initialization.

Check the workspace's SimPL models and any Rust and Python trees that are present:

sim check
sim check --sim
sim check --rust
sim check --python

With no selection flags, sim check checks every tree present. Selecting one or more flags checks only those trees. The optional positional path selects a workspace; otherwise sim searches the current directory and its parents for the workspace Sim.toml.

Build a reusable simulation workspace​

Use sim build to compile a simulation without starting it. It accepts either a build-input document or a Python model, just like a source-based sim run:

sim build --buildinput scenario.json --output built-scenario
SCF_PATH=/path/to/sedaro-or-scf sim build \
--model models.workflows.example --output built-model

The output directory defaults to generated/. A build prepares the scenario, compiles its artifacts into that directory, and exits. Use the directory later with sim run --prebuilt-workspace:

sim run --prebuilt-workspace built-scenario --target native \
--plugin /path/to/libmy_plugin.so

The build's resolved duration is saved with the workspace and used by a prebuilt run unless --duration is supplied to override it. sim build accepts --target to check the input against the selected runtime's requirements; it defaults to native.

Run a Python model​

sim run --model accepts a dotted Python module name, not a path to a .py file. The module must be importable by the Python environment selected by sim. If you are not running this from the sedaro repo, set SCF_PATH to the root of the sedaro repo.

SCF_PATH=/path/to/sedaro-or-scf sim run \
--model models.workflows.example \
--plugin /path/to/plugin/target/release/libmy_plugin.so

The sedaro repo's Python environment is used: if it has .venv, the CLI selects that environment's Python; otherwise it uses python from PATH.

When the module runs, it must create/run a Sedaro Simulation and call its simulate method.

The default output directory for a run is generated/.

Run a build-input document​

Use --buildinput to run a simulator build-input JSON file instead of a Python model. The two input options are mutually exclusive.

sim run --buildinput scenario.json --plugin /path/to/libmy_plugin.so

If neither input has a duration, a build-input run defaults to 0.0001 days. The default output directory is generated/; set --output to choose a different directory.

To run artifacts that were already compiled, pass their directory instead of --buildinput or --model:

sim run --prebuilt-workspace built-scenario --target native \
--duration 2 --plugin /path/to/libmy_plugin.so

Prebuilt runs accept the usual runtime options, including --target, --duration, and --plugin. The duration defaults to the value saved when the workspace was built; --duration overrides it. --prebuilt-workspace cannot be combined with source inputs or --output. Custom sim builds that omit the compiler feature can run prebuilt workspaces; sim build and source-based runs require that feature.

Choose a runtime and options​

--target native is the default and runs on the host. --target wasm packages the browser runtime and serves it locally. Runtime options are target-specific:

OptionBehavior
--plugin <FILE>Add a precompiled plugin; repeat the option to load multiple plugins. Native runs accept .so or .dylib; browser runs accept .wasm.
--duration <DAYS>Override the run duration.
--output <DIR>Choose output directory; defaults to generated/ for either target.
--target-config <NAME>Native only: select the native output target configuration.
--no-serveWASM only: package the browser app without starting its HTTP server.
--no-openWASM only: serve the app without opening a browser.
--port <PORT>WASM only: HTTP port (default 8000; 0 selects an available port).

Native output uses JsonLinesVerboseTarget by default. WASM output is a browser application. A plugin's file extension selects its binary kind, but does not select the runtime: a .wasm plugin still requires --target wasm. A run cannot mix native and WASM plugins. See the Rust Plugins guide to create, build, and implement plugins.

The current sim run loader does not accept .dll plugin paths. Build native plugins on a host that emits .so or .dylib files for the native run path.

# Native run, with the default output target
sim run --target native --buildinput scenario.json \
--plugin ./out/libmy_plugin.so

# Build browser files without serving them
sim run --target wasm --buildinput scenario.json \
--plugin ./out/my_plugin.wasm --no-serve

# Run a model in the browser and serve it on an automatically selected port
SCF_PATH=/path/to/sedaro-or-scf sim run --target wasm \
--model models.workflows.example \
--plugin ./out/my_plugin.wasm --port 0

--target-config is native-only. --no-serve, --no-open, and --port are WASM-only; the CLI reports an error if they are used with the other target.

How builds and runs use compiled artifacts​

sim build and source-based sim run compile the scenario in-process. A run with --prebuilt-workspace skips scenario compilation and uses the artifacts already in that directory. Native runs use the static interpreter linked into sim; WASM runs build the browser interpreter with wasm-pack. The CLI does not invoke Cargo on the plugin crate. For each run it loads the already-built plugin files passed through --plugin; a plugin directory or Rust source file is not accepted. Build plugins separately with sim plugin build.