Command line reference¶
--help output of every naga command, captured live so it cannot drift from the real argument parsers. python -m nagasim is the same program.
| Command | What it does |
|---|---|
naga examples |
list the models that ship in the package |
naga run |
run a model headless |
naga scenarios |
run named scenarios headless and compare them |
naga invest |
payback, NPV and ROI of each scenario against a baseline |
naga fit |
fit an input distribution to CSV data |
naga doe |
design of experiments over model parameters |
naga optimize |
search model parameters for the best KPI within a replication budget |
naga policy-eval |
evaluate a controller against a Policy-mode DECIDE |
naga schema |
JSON Schema of the model file format |
naga validate |
structured validation problems, exit 1 on errors |
naga diff |
semantic diff of two model files by record identity |
naga merge |
three-way merge of model files by record identity |
naga check |
run a model's assertions and reality checks |
naga ci-template |
print a GitHub Actions workflow running 'naga check' |
naga generate |
build a model from Stations/Products/Routings tables |
naga sdimport |
translate an XMILE/Vensim file into a model JSON |
naga viewer |
one HTML file in which the engine re-runs a model in a browser |
naga bind |
resolve a model's data bindings and show what each one read |
naga watch |
print what a model's live data sources send, as it arrives |
naga state |
take a model's state from a run or from a plant, and check one before a start |
naga plant |
map what a plant sends into an observed timeline: check, replay a log, watch |
naga twin |
an operational twin: monitor a plant, forecast from its state, compare, report |
naga calibrate |
fit model parameters to observed KPIs |
naga forecast |
short-horizon forecast with prediction bands |
naga plan |
deterministic plan, optional CP-SAT proposal and risk |
naga loops |
loop dominance (Loops That Matter) of an SD model |
naga mcp |
Model Context Protocol server over stdio |
naga assist |
one headless assistant turn |
naga examples¶
usage: naga examples [-h] [--path]
List the models that ship in the package. A command that takes a model path
also takes one of these names: naga run single_server.
options:
-h, --help show this help message and exit
--path print the folder they are in instead
naga run¶
usage: naga run [-h] [--version] [--replications REPLICATIONS] [--seed SEED]
[--warmup WARMUP] [--run-length RUN_LENGTH] [--start ISO]
[--until ISO] [--timezone IANA] [--workers WORKERS]
[--out OUT] [--report REPORT] [--export FORMAT:PATH]
[--player PATH] [--state FILE] [--no-logs]
model
Run a Naga model headless.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--version show program's version number and exit
--replications REPLICATIONS
default: the model's own 'simulation.replications'
--seed SEED
--warmup WARMUP default: the model's own 'simulation.warmup'
--run-length RUN_LENGTH
0 = run until the queue drains; default: the model's
own 'simulation.time_limit'
--start ISO real instant model time 0 stands for, e.g.
2026-01-05T06:00:00 ; overrides the model's own
'simulation.calendar.start'
--until ISO run until this real instant instead of a length; needs
a calendar start, from the model or from --start
--timezone IANA IANA timezone for --start/--until and for weekday
schedules (default: the model's own, else UTC)
--workers WORKERS replications to run in parallel processes, or 'auto'
(default: 1)
--out OUT write the 10-sheet results workbook here
--report REPORT write an HTML report here
--export FORMAT:PATH write with a registered exporter, e.g. json:out.json;
repeatable. See nagasim.exporters.EXPORTER_REGISTRY
for the built-in formats (xlsx/csv/html/json/player)
plus any plugin ones
--player PATH write a shareable HTML player of the first replication
here: one self-contained file that replays the run in
a browser, with no server (the same as --export
player:PATH)
--state FILE start from this state document (`naga state take` or
`observe`): the run's clock starts where the state was
taken and its statistics cover the run from there
--no-logs do not record the per-event entity/resource/store
logs: faster and much smaller on a long run, and every
summary statistic is unchanged -- only the three flat
log sheets come back empty
naga scenarios¶
usage: naga scenarios [-h] [--scenario SCENARIOS]
[--replications REPLICATIONS] [--run-length RUN_LENGTH]
[--warmup WARMUP] [--seed SEED] [--workers WORKERS]
[--no-crn] [--out OUT] [--report REPORT] [--player PATH]
model
Run named scenarios headless and compare them.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--scenario SCENARIOS scenario name to run (default: all); may repeat
--replications REPLICATIONS
default: the model's own 'simulation.replications'
--run-length RUN_LENGTH
default: the model's own 'simulation.time_limit'
--warmup WARMUP default: the model's own 'simulation.warmup'
--seed SEED
--workers WORKERS replications to run in parallel processes, or 'auto'
(default: 1)
--no-crn disjoint seeds per scenario (Welch's interval) instead
of paired CRN
--out OUT write the comparison table here (.xlsx or .csv)
--report REPORT write an HTML report here
--player PATH write a shareable HTML player here: the first
replication of every scenario, run again with its seed
and recorded, in one self-contained file with a
scenario switch
naga invest¶
usage: naga invest [-h] [--replications REPLICATIONS] [--seed SEED]
[--csv CSV]
model
Run every scenario and print payback, NPV and ROI against the baseline of the
model's investment section.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--replications REPLICATIONS
default: the model's own 'simulation.replications'
--seed SEED
--csv CSV write the table here as CSV
naga fit¶
usage: naga fit [-h] [--column COLUMN] [--top TOP] [--shift] [--json JSON]
data
Fit candidate distributions to a data column.
positional arguments:
data CSV/TSV/TXT or XLSX file
options:
-h, --help show this help message and exit
--column COLUMN default: the first numeric column
--top TOP ranking rows to print
--shift fit a free location offset for positive-support families
--json JSON write the full ranking + best spec here
naga doe¶
usage: naga doe [-h] --factor FACTORS --response RESPONSE
[--replications REPLICATIONS] [--run-length RUN_LENGTH]
[--warmup WARMUP] [--seed SEED] [--workers WORKERS]
[--out OUT] [--report REPORT] [--design DESIGN] [--no-crn]
[--surrogate {linear,quadratic,auto}] [--dataset DATASET]
model
Run a design of experiments over model parameters.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--factor FACTORS a factor, as 'path=kind:low:high[:step]' or
'path=cat:a|b|c'. kind is float/int/cat. Several
comma-separated paths before the '=' are driven with
the same value. May repeat. Example:
'resources.Agents.capacity=int:3:6'
--response RESPONSE the KPI key to analyse, e.g. 'system/Avg Throughput
Time'
--replications REPLICATIONS
replications per design point (default: 5)
--run-length RUN_LENGTH
default: the model's own 'simulation.time_limit'
--warmup WARMUP default: the model's own 'simulation.warmup'
--seed SEED
--workers WORKERS replications to run in parallel processes (default: 1)
--out OUT write the result table here (.xlsx or .csv)
--report REPORT write an HTML report here
--design DESIGN full[:levels] (default full:2), lhs:<n>, or oat
--no-crn give each design point its own seed block instead of
CRN
--surrogate {linear,quadratic,auto}
fit a response surface over the design; included in
--report as its own section
--dataset DATASET write one row per (design point, replication) here, as
factors + responses + seed (.csv, or .parquet if
available)
naga optimize¶
usage: naga optimize [-h] --factor FACTORS --response RESPONSE
[--replications REPLICATIONS] [--run-length RUN_LENGTH]
[--warmup WARMUP] [--seed SEED] [--workers WORKERS]
[--out OUT] [--report REPORT] [--goal {min,max}]
[--budget BUDGET] [--constraint CONSTRAINTS]
[--method {auto,pattern,optuna}]
[--indifference INDIFFERENCE]
[--min-improvement MIN_IMPROVEMENT]
model
Search model parameters for the best KPI within a replication budget.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--factor FACTORS a factor, as 'path=kind:low:high[:step]' or
'path=cat:a|b|c'. kind is float/int/cat. Several
comma-separated paths before the '=' are driven with
the same value. May repeat. Example:
'resources.Agents.capacity=int:3:6'
--response RESPONSE the KPI key to analyse, e.g. 'system/Avg Throughput
Time'
--replications REPLICATIONS
replications per design point (default: 5)
--run-length RUN_LENGTH
default: the model's own 'simulation.time_limit'
--warmup WARMUP default: the model's own 'simulation.warmup'
--seed SEED
--workers WORKERS replications to run in parallel processes (default: 1)
--out OUT write the result table here (.xlsx or .csv)
--report REPORT write an HTML report here
--goal {min,max}
--budget BUDGET total replications the search may spend (default: 300)
--constraint CONSTRAINTS
a KPI constraint, as '<kpi key><=<value>' or '<kpi
key>>=<value>'. May repeat. Example:
'resource/Agents/Usage % (snapshot)<=85'
--method {auto,pattern,optuna}
--indifference INDIFFERENCE
the smallest difference worth detecting in the final
ranking-and-selection step (default: 5% of the best
mean)
--min-improvement MIN_IMPROVEMENT
relative gain a move must reach before the search
widens that factor's step (default: 0.01 = 1% of the
objective). 0 widens on any significant gain
naga policy-eval¶
usage: naga policy-eval [-h] --policy POLICY --controller
{random,roundrobin,shortest}
[--reward {neg_wip,throughput,neg_time_in_system}]
[--episodes EPISODES] --horizon HORIZON [--seed SEED]
model
Evaluate a controller against a Policy-mode DECIDE.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--policy POLICY decision-point name
--controller {random,roundrobin,shortest}
built-in controller to evaluate
--reward {neg_wip,throughput,neg_time_in_system}
--episodes EPISODES
--horizon HORIZON
--seed SEED
naga schema¶
usage: naga schema [-h] [--out OUT]
Print the JSON Schema (draft 2020-12) of the model file format.
options:
-h, --help show this help message and exit
--out OUT write the schema here instead of printing it
naga validate¶
usage: naga validate [-h] [--json] model
Validate a model file and report structured problems (code, severity, path,
hint).
positional arguments:
model path to the model JSON, or a bundled model's name (naga
examples)
options:
-h, --help show this help message and exit
--json emit the problems as a JSON array instead of one line each
naga diff¶
usage: naga diff [-h] [--json] [--all] [--textconv] files [files ...]
Semantic diff between two model files, matched by record identity rather than
list position.
positional arguments:
files two model files, or one with --textconv
options:
-h, --help show this help message and exit
--json emit the changes as a JSON array
--all also report canvas-only 'moved' changes (hidden by default)
--textconv print one file's canonical text form (a git textconv driver)
naga merge¶
usage: naga merge [-h] [-o OUTPUT] [--json] base ours theirs
Three-way merge of model files by record identity; usable as a git merge
driver (naga merge %%O %%A %%B).
positional arguments:
base the common ancestor (git %O)
ours our version (git %A); overwritten unless -o is given
theirs their version (git %B)
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
write the merged model here instead of over OURS
--json also print the conflicts as a JSON array on stdout
naga check¶
usage: naga check [-h] [--junit JUNIT] [--workers WORKERS] [--strict]
models [models ...]
positional arguments:
models model file(s) to check
options:
-h, --help show this help message and exit
--junit JUNIT write a JUnit XML report here
--workers WORKERS
--strict treat an inconclusive assertion (its CI straddles the
bound) as a failure too (exit 1)
naga ci-template¶
usage: naga ci-template [-h] [--path PATH] [--install INSTALL]
options:
-h, --help show this help message and exit
--path PATH directory of *.json models to check (default models/)
--install INSTALL the install step (default "pip install .": the product
package from the repository checkout)
naga generate¶
usage: naga generate [-h] [-o OUTPUT] [--template FILE] [source]
Generate a model from Stations/Products/Routings tables (an .xlsx workbook or
a folder of CSVs).
positional arguments:
source an .xlsx workbook, or a folder of CSVs
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
write the generated model JSON here (default: stdout)
--template FILE write an empty .xlsx workbook with header rows and
exit
naga sdimport¶
usage: naga sdimport [-h] [-o OUT] source
Translate an XMILE (.xmile/.stmx) or Vensim (.mdl) file into a Naga model
JSON.
positional arguments:
source path to the .xmile/.stmx/.mdl file
options:
-h, --help show this help message and exit
-o OUT, --out OUT write the model JSON here instead of stdout
naga viewer¶
usage: naga viewer [-h] [-o OUTPUT] [--title TITLE] [--runtime DIR] [--fetch]
[--freeze] [--allow-network] [--allow-private-network]
[--allow-host HOST] [--connections FILE]
[model]
Write one HTML file in which the engine runs in a browser and re-runs the
model with the inputs its dashboard definition exposes. The file holds the
whole model and the engine's source: whoever receives it can read both. For a
confidential model share a recording instead (`naga run MODEL --player
FILE.html`).
positional arguments:
model the model file, or a bundled model's name (naga
examples)
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
the HTML file to write
--title TITLE the page's title (default: the model file's name)
--runtime DIR the folder of the browser runtime (default:
$NAGASIM_VIEWER_RUNTIME, else the user's own copy)
--fetch download the browser runtime (Pyodide 314.0.7, 29 MB,
from github.com and cdn.jsdelivr.net) into that
folder; nothing is downloaded without this flag
--freeze read the model's data sources once, now, and write the
values read into the copy as plain model data: the
file then names no source, path or address (without it
a model with data sources is refused)
--allow-network permit sql / json_url data sources (refused by
default: opening a model must not make outbound
connections on its own)
--allow-private-network
also permit private/intranet addresses (refused even
with --allow-network)
--allow-host HOST restrict network sources to this hostname; may repeat
--connections FILE the connections a live source (rest, mqtt, opcua) may
name: a JSON file of yours, never the model's; without
it every live source is refused
naga bind¶
usage: naga bind [-h] [--allow-network] [--allow-private-network]
[--allow-host HOST] [--connections FILE] [--write WRITE]
model
Resolve a model's data bindings and show what each one read.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--allow-network permit sql / json_url data sources (refused by
default: opening a model must not make outbound
connections on its own)
--allow-private-network
also permit private/intranet addresses (refused even
with --allow-network)
--allow-host HOST restrict network sources to this hostname; may repeat
--connections FILE the connections a live source (rest, mqtt, opcua) may
name: a JSON file of yours, never the model's; without
it every live source is refused
--write WRITE write the resolved model here
naga watch¶
usage: naga watch [-h] --connections FILE [--source NAME] [--for SECONDS]
[--record FILE] [--check]
model
Print what a model's live data sources (rest, mqtt, opcua) send, as it
arrives, with a summary per source. Read-only: nothing is sent to a plant.
positional arguments:
model path to the model JSON, or a bundled model's name (naga
examples)
options:
-h, --help show this help message and exit
--connections FILE your connections file: where each connection a source
names may connect, and with which credential
--source NAME watch only this source; may repeat (default: every live
source)
--for SECONDS how long to watch (default 30; 0: until Ctrl+C)
--record FILE also write every event as one JSON object per line, with
a {"lost": n} or {"gap": true} line where the log has a
hole
--check print each connection the model uses, connect once and
stop
naga state¶
usage: naga state [-h] {take,observe,check} ...
A model's state as a document: taken from a run, observed from a plant through
the model's data bindings, and checked before a run starts from it (naga run
MODEL --state FILE). Read-only.
positional arguments:
{take,observe,check}
take run the model to a time and write its state
observe read the state a plant reports now, through the
model's bindings into initial_state
check say whether a run of this model may start from this
state; exit 1 with the reasons when not
options:
-h, --help show this help message and exit
naga plant¶
usage: naga plant [-h] {check,init,mock,replay,watch} ...
A plant as a timeline: a plant mapping (*.plantmap.json) says what each key a
plant sends asserts about a model, and the views of a run then show the plant.
Read-only: nothing is sent to a plant.
positional arguments:
{check,init,mock,replay,watch}
check say whether a mapping may be used with a model; exit 1
with the reasons when not
init write a starter mapping that names every block,
resource and level of the model by its own name
mock run the model and write the plant log that run would
have left, through the mapping read backwards
replay map a recorded log (naga watch --record) into an
observed timeline
watch show a model's live sources as an observed timeline,
as they send
options:
-h, --help show this help message and exit
naga twin¶
usage: naga twin [-h] {once,run,status,score,reproduce} ...
An operational twin of a plant: monitor it through a plant mapping, forecast
from its state of now, compare each forecast with what then happened, score
them, and write one result a monitor reads. With --candidates it compares your
candidate actions after each forecast and recommends. Read-only towards the
plant: nothing is sent to it; only the --out directory is written and, with
--outbox, the file you name there.
positional arguments:
{once,run,status,score,reproduce}
once one cycle with its forecast, for the OS scheduler;
exit 1 when the result holds an error
run keep monitoring, with a forecast on its own slower
cadence, until Ctrl+C
status print the latest result of a twin; exit 1 for an error
in it or no result
score compute a twin's stored scores again from a recorded
plant log; exit 1 for any difference. Nothing is
written
reproduce compute a twin's stored recommendations again from
their stored states and seeds; exit 1 for any
difference. Nothing is written
options:
-h, --help show this help message and exit
naga calibrate¶
usage: naga calibrate [-h] --factor FACTORS --target TARGETS [--budget BUDGET]
[--replications REPLICATIONS] [--run-length RUN_LENGTH]
[--warmup WARMUP] [--seed SEED] [--workers WORKERS]
[--out OUT] [--report REPORT]
[--write-scenario WRITE_SCENARIO]
model
Tune model parameters until the model reproduces observed KPIs.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--factor FACTORS a factor, as 'path=kind:low:high[:step]' or
'path=cat:a|b|c'. kind is float/int/cat. Several
comma-separated paths before the '=' are driven with
the same value. May repeat. Example:
'resources.Agents.capacity=int:3:6'
--target TARGETS an observed KPI, as '<kpi key>=<value>[:<tolerance>]'.
May repeat. Example: 'system/Avg Throughput
Time=8.4:0.5'
--budget BUDGET total replications the search may spend (default: 200)
--replications REPLICATIONS
replications per candidate point (default: 5)
--run-length RUN_LENGTH
default: the model's own 'simulation.time_limit'
--warmup WARMUP default: the model's own 'simulation.warmup'
--seed SEED
--workers WORKERS replications to run in parallel processes (default: 1)
--out OUT write the target table here (.xlsx or .csv)
--report REPORT write an HTML report here
--write-scenario WRITE_SCENARIO
write the model back here with the tuned values as a
scenario
naga forecast¶
usage: naga forecast [-h] --horizon HORIZON [--replications REPLICATIONS]
[--event EVENTS] [--kpi KPIS] [--seed SEED]
[--workers WORKERS] [--no-bind] [--allow-network]
[--allow-private-network] [--allow-host HOST]
[--connections FILE] [--out OUT] [--report REPORT]
model
Forecast a short horizon from the model's current state, with prediction bands
and event probabilities. Schedule repeated runs with the OS scheduler (Task
Scheduler, cron); this command is the unit of work, not a daemon.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--horizon HORIZON run length in base time units
--replications REPLICATIONS
--event EVENTS an event to report the probability of, as '<kpi
key><op><value>' with op one of > >= < <=. May repeat.
Example: 'timeseries/system/WIP/max>8'
--kpi KPIS KPI key to report; may repeat (default: all)
--seed SEED
--workers WORKERS replications to run in parallel processes (default: 1)
--no-bind skip the model's data bindings (they resolve by
default here)
--allow-network permit sql / json_url data sources (refused by
default: opening a model must not make outbound
connections on its own)
--allow-private-network
also permit private/intranet addresses (refused even
with --allow-network)
--allow-host HOST restrict network sources to this hostname; may repeat
--connections FILE the connections a live source (rest, mqtt, opcua) may
name: a JSON file of yours, never the model's; without
it every live source is refused
--out OUT write the forecast tables here (.xlsx or .csv)
--report REPORT write an HTML report here
naga plan¶
usage: naga plan [-h] [--orders ORDERS]
[--propose {makespan,weighted_tardiness}]
[--time-limit TIME_LIMIT] [--risk N] [--workers WORKERS]
[--seed SEED] [--export EXPORT] [--report REPORT]
model
What is the plan, is there a better one, and how risky is it -- the
deterministic schedule, an optional CP-SAT proposal, and optional risk.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--orders ORDERS CSV replacing the model's "orders" section
--propose {makespan,weighted_tardiness}
propose a plan with CP-SAT instead of the as-is layout
(needs the optional 'ortools' package: pip install
"nagasim[plan]")
--time-limit TIME_LIMIT
CP-SAT time limit in seconds (default: 10)
--risk N score the plan with N stochastic replications
--workers WORKERS risk replications run in parallel
--seed SEED
--export EXPORT write the plan here: .csv or .json by extension
--report REPORT write an HTML report (Gantt + risk table) here
naga loops¶
usage: naga loops [-h] [--seed SEED] [--run-length RUN_LENGTH] [--limit LIMIT]
[--csv FILE]
model
Loop dominance (Loops That Matter) of an SD model: which feedback loop drives
the behaviour and when. Needs simulation.sd.
positional arguments:
model path to the model JSON, or a bundled model's name
(naga examples)
options:
-h, --help show this help message and exit
--seed SEED
--run-length RUN_LENGTH
run length in base time units (default: the model's
own)
--limit LIMIT elementary circuits enumerated before the strongest-
path search takes over (default: 1000)
--csv FILE write the loop table to FILE and the per-step scores
to FILE's stem + '_dominance.csv'
naga mcp¶
usage: naga mcp [-h] [--root ROOT] [--allow-network] [--allow-private-network]
[--allow-host HOST] [--connections FILE]
[--tools {all,compact}] [--twin DIR]
Run the MCP server over stdio. File access is confined to --root, and network
access is off unless you allow it here.
options:
-h, --help show this help message and exit
--root ROOT workspace root: the only directory models may be read
from or written to (default: the current directory)
--allow-network permit sql / json_url data sources (refused by
default: opening a model must not make outbound
connections on its own)
--allow-private-network
also permit private/intranet addresses (refused even
with --allow-network)
--allow-host HOST restrict network sources to this hostname; may repeat
--connections FILE the connections a live source (rest, mqtt, opcua) may
name: a JSON file of yours, never the model's; without
it every live source is refused
--tools {all,compact}
all: every tool (default); compact: only what
building, running and saving a model needs
(get_model_format, write_model, run_model, ...), so a
client pays for fewer tool descriptions
--twin DIR the result directory of a twin you started (naga twin
run --out DIR): two read-only tools then answer from
it. No tool can start a twin or choose this directory
naga assist¶
usage: naga assist [-h] [--provider {anthropic,openai}] [--base-url BASE_URL]
[--model-id MODEL_ID]
[--reasoning {none,low,medium,high,omit}]
[--max-tool-rounds MAX_TOOL_ROUNDS]
model prompt
Run one assistant turn against a model file, with a local model or your own
API key.
positional arguments:
model path to the model .json file, or a bundled model's
name (naga examples)
prompt what to ask the assistant to do
options:
-h, --help show this help message and exit
--provider {anthropic,openai}
anthropic, or openai for any OpenAI-compatible server
(Ollama, LM Studio); default: anthropic when
ANTHROPIC_API_KEY is set, else a local Ollama
--base-url BASE_URL default http://localhost:11434/v1
--model-id MODEL_ID the provider's model name (for Ollama, one from
`ollama list`)
--reasoning {none,low,medium,high,omit}
--max-tool-rounds MAX_TOOL_ROUNDS