CLI Reference

The CLI loads a config, validates it, runs diagnostics, then simulates, visualizes, or serves. Flags must come before the YAML filename.

go run main.go [flags] scenarios/<Name>/<Name>.yaml

Flags

Flag	Description
--run <turns>	Run an experiment for N turns.
--seedCount <n>	Seed entities per root machine (default: 100).
--noSeedFiles	Ignore load_file declarations; seed every type from --seedCount.
--step	Advance the experiment by exactly one turn.
--request <event>	Request <event> on the first active instance of --target. A request concentrates the probability row on that event for a single step; if its conditions fail it is masked and nothing fires (the instance stays).
--target <Machine>	Machine type whose first active instance --request targets.
--clock <mode>	Override the scheduling clock for this run: tick or event (run-scoped; the deployed config keeps its declared clock).
--analyze	Static analysis report — spawn/message graphs, partitions, parallelism verdict (exits early).
--dump	Export the fully-resolved config as a JSON diagnostic dump (exits early).
--print	Print a configuration summary to the terminal.
--saveJson	Export the config as JSON to the working/ directory.
--eventLog	Write the JSONL event log during the run (default: true).
--decisionLog	Write the per-entity decision log (JSONL; default: false).
--png	Generate PNG state diagrams via Graphviz (requires dot).
--html	Generate a single HTML report with embedded SVG charts.
--duckdb	Convert the exported Parquet files into a single DuckDB database in the experiment dir.
--osi	Generate the OSI semantic-model YAML; with --run it is written into the experiment directory, otherwise printed to stdout.
--runDir <path>	Store root for experiment output (default: the mock-machines-root store).
--logLevel <level>	Log level: debug, info, warn, error (default: info).

Examples

# End-to-end smoke test
go run main.go -run 50 scenarios/PaymentProcessor/PaymentProcessor.yaml

# Event clock vs turn-locked tick clock for the same model
go run main.go -run 200 scenarios/OnlineShoppingEvents/OnlineShoppingEvents.yaml
go run main.go -run 200 -clock tick scenarios/OnlineShoppingEvents/OnlineShoppingEvents.yaml

# Static analysis report, also written to a file
go run main.go -analyze -runDir /tmp/debug scenarios/PaymentProcessor/PaymentProcessor.yaml

Note

Reproduction comes from replaying the captured event log, not from re-running with a fixed RNG seed — randomness uses a non-deterministic per-goroutine source.