Command Line Basics

While the Web UI is the recommended way to use Net Worth Navigator, the command line gives you quick access to run scenarios, switch data sources, and check your version.

Basic Usage

Windows (PowerShell)

.venv\Scripts\python.exe run.py

Linux / macOS

.venv/bin/python run.py

Running run.py without any arguments does a full run: it pulls live Monarch balances (if configured), runs all discovered scenarios, generates all render modes, writes output files and analysis sidecars, and updates the scenario index.

Key Flags

–scenario <slug>

Run a single scenario by its slug. The slug is the filename of your scenario TOML (without the .toml extension).

.venv/bin/python run.py --scenario sample      # Run sample scenario
.venv/bin/python run.py --scenario myplan      # Run your custom scenario

–offline

Skip the Monarch balance fetch and use cached balances instead. Much faster — useful for quick re-renders after editing config.

.venv/bin/python run.py --offline              # Re-render all scenarios from cache
.venv/bin/python run.py --scenario myplan --offline  # Re-render one scenario

–version or -V

Print the version number and exit.

.venv/bin/python run.py --version

Data Source Modes

The CLI respects the [data_source] section in your scenario TOML. No flag needed — the mode is set per scenario:

data_source.mode	What happens when you run run.py
"monarch" (default)	Pulls live Monarch balances via MCP subprocess
"synthetic"	Uses balances from [synthetic_start] in the TOML
"csv_import"	Uses balances imported from CSV via the Setup Panel

When --offline is used, Monarch mode reads from output/balances_cache.json instead of calling the MCP.

Output Files

Each run generates output in the output/ directory:

output/
├── projection.html                  ← Shell entry page
├── compare.html                     ← Compare page
├── definitions.html                 ← Definitions reference
├── scenarios/
│   └── <slug>/
│       ├── deterministic/projection.html
│       ├── historical/projection.html
│       ├── monte_carlo/projection.html
│       └── sidecars/
│           ├── projection_yearly.csv
│           ├── event_flows.csv
│           ├── scenario_manifest.json
│           ├── accounts_snapshot.json
│           └── tax_breakdown_yearly.csv
└── balances_cache.json             ← Cached Monarch data

Verification

Run the installation health check at any time:

Windows (PowerShell)

.venv\Scripts\python.exe scripts/verify_install.py

Linux / macOS

.venv/bin/python scripts/verify_install.py

This checks Python version, dependencies, TOML parsing, and imports.