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:
| Option | Behavior |
|---|---|
--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-serve | WASM only: package the browser app without starting its HTTP server. |
--no-open | WASM 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.