# simforge command reference

CLI version 0.2.0-rc.5. Generated from `simforge --help --json`; the same document is at /docs/cli.json.

Output: stdout: one JSON document (indented with --pretty); stderr: {code, path?, reason, detail?} on failure.

## Global flags

| Flag | Notes | What |
|---|---|---|
| `--pretty` |  | Indent the JSON result for humans (the same document, never a different one) |
| `--json` |  | Explicit machine-readable JSON output (also the default) |
| `--cloud` |  | Execute locally by default; submit the same input as an authenticated cloud job |
| `--workspace cloud_workspace` | env SIMFORGE_WORKSPACE_ID | With --cloud: the workspace you expect the login to act in; a different one is refused (workspace_mismatch) |
| `--idempotency-key IDEMPOTENCY_KEY` |  | With --cloud: a key that makes resending a lost submission safe (the host answers with the original run and charges once) |
| `--dry-run` |  | With --cloud: price the job (costEstimateCents) and start nothing |
| `--api-url API_URL` |  | Hosted API base URL for API-key use. Default: SIMFORGE_API_URL, then the signed-in host's /api/v1 |
| `--map-version MAP_VERSION` |  | Exact hosted map version for a scenario file. Default: the installed release's, else the one hosted version carrying the file's OpenDRIVE digest |
| `--help` |  | Print machine-readable command help. |

## Exit codes

| Exit | Meaning |
|---|---|
| 0 | ok |
| 1 | command error: the command could not run |
| 2 | findings: the command ran and found something wrong with its input |

## assets

### simforge assets pull

Pull the actor-asset closure and its ATTRIBUTION.json, verifying every blob's sha256

Usage: `simforge assets pull [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--only ONLY` | one of actors, sky | Pull only this closure. Default: both the actor closure and the sky plates |
| `--closure SHA256` |  | The actor closure digest (sha256). Default: the closure this build is pinned to |
| `--base-url URL` |  | Asset store base URL (https:// or file://). Default: SIMFORGE_ACTOR_ASSETS_BASE_URL, then the public store |
| `--root DIR` |  | Local asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--timeout SECONDS` | default 60 | Seconds to wait for a connection or for a response to start |

## auth

### simforge auth status

The account, organization, scopes, expiry, host and credential store of this machine's login, checked with the host (tokenValid), and the account's email verification

Usage: `simforge auth status [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--host HOST` |  | SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai |

## authoring

### simforge authoring capabilities

What this credential may do on this host: operation, host-operation, feature and worker status

Usage: `simforge authoring capabilities [OPTIONS]`

### simforge authoring catalogue

The host's operation catalogue (simforge.authoring-operations/v1)

Usage: `simforge authoring catalogue [OPTIONS]`

### simforge authoring discover

Bounded map discovery without the map package: locations, lanes, movements or the actor catalogue

Usage: `simforge authoring discover [OPTIONS] --map <MAP_VERSION_ID> --kind <KIND>`

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP_VERSION_ID` | required |  |
| `--kind KIND` | required; one of locations, lanes, movements, catalogue |  |
| `--limit N` |  |  |

### simforge authoring operations

Every operation with its `drafts apply` flags, result schema and the host's status for this credential

Usage: `simforge authoring operations [OPTIONS] [OP_ID]`

| Argument / flag | Notes | What |
|---|---|---|
| `<op_id>` |  | One operation id (camelCase or its kebab-case command); absent, every operation |

### simforge authoring spawn

Whether an actor can be placed at a lane position or scene point, optionally against a draft's actors

Usage: `simforge authoring spawn [OPTIONS] --map <MAP_VERSION_ID> --catalog-id <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP_VERSION_ID` | required |  |
| `--catalog-id ID` | required |  |
| `--lane-rsl RSL` |  | A lane handle from `authoring discover --kind lanes` (with --s) |
| `--s S` |  |  |
| `--x X` |  | A scene point (with --z) |
| `--z Z` |  |  |
| `--heading-rad HEADING_RAD` |  |  |
| `--lateral-m LATERAL_M` |  |  |
| `--opposing` |  |  |
| `--static` |  |  |
| `--draft DRAFT_ID` |  | Check overlap against this draft's actors (needs --expected-version and --expected-digest) |
| `--expected-version N` |  |  |
| `--expected-digest SHA256` |  |  |

## batch

### simforge batch

Sites x draws matrix of a template: instantiate -> simulate -> evaluate per cell, resumable

Usage: `simforge batch [OPTIONS] --out <DIR> <TEMPLATE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<template>` | required | The v2 template |
| `--map MAP` |  | One installed map |
| `--maps MAPS` | repeatable | Several installed maps, comma-separated, in this order |
| `--all-maps` |  | Every installed map |
| `--draws N` |  | Parameter draws per site |
| `--out DIR` | required | The batch directory (cells and batch-summary.json) |
| `--min-score SCORE` |  | Drop sites scoring below this |
| `--max-sites N` |  | Keep at most this many sites per map |
| `--concurrency N` |  | Worker threads (default min(4, cpus - 1)) |
| `--no-trace` |  | Do not write the per-cell traces |
| `--filter MODE` |  | Reject filters: critical \| negative-control \| all |
| `--trivial-ttc S` |  | The trivially-safe TTC threshold, seconds |
| `--force` |  | Re-run every cell, even one whose results still hold |
| `--ambient PRESET` |  | Generated background traffic: off \| light \| moderate \| city \| heavy |
| `--ambient-density N` |  | Ambient density override, vehicles per km of eligible lane |
| `--ambient-max-actors N` |  | Ambient actor cap |
| `--ambient-radius-m M` |  | Ambient candidate radius around the choreography, metres |
| `--ambient-seed SEED` |  | Ambient population seed |
| `--ambient-settle S` |  | Seconds of ambient-only warm-up before t = 0 (default 20 with --ambient) |

## bench

### simforge bench

Benchmark the renderer on this machine: the Helios Score, per-factor sub-scores, frame correctness

Usage: `simforge bench [OPTIONS]
       simforge bench <COMMAND>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |

### simforge bench compare

Compare two results: per-scene time deltas against the noise of both runs, and frame identity

Usage: `simforge bench compare [OPTIONS] <A.json> <B.json>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<a.json>` | required | The baseline result |
| `<b.json>` | required | The candidate result |
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |

### simforge bench pack actors

Cut the pack's actor closure (only its scenes' catalog entries and models, licences carried) from the SDK's closure

Usage: `simforge bench pack actors [OPTIONS] --out <DIR> <PACK_DIR>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<pack_dir>` | required | The pack directory (its scenarios' traces name the catalog ids) |
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--out DIR` | required | Write the closure root (closures/<digest>.json, blobs/sha256/..) here, ready to publish |
| `--base SHA256:BYTES` |  | The closure to cut from (sha256 and byte size of its document). Default: the SDK's pinned actor closure |

### simforge bench pack record

Record the reference (timings, frame hashes, sample frames) into a pack directory on this machine

Usage: `simforge bench pack record [OPTIONS] --label <LABEL> <PACK_DIR>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<pack_dir>` | required | The pack directory (pack.json, scenarios, rigs); reference/ is (re)written |
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--label LABEL` | required | A label for the reference machine (e.g. "RTX 3080 desktop") |
| `--gpu N` |  |  |
| `--cache-root DIR` |  |  |
| `--assets-root DIR` |  |  |
| `--from-result RESULT.json` |  | Record from this result of a run kept in `<PACK_DIR>/reference/.record` instead of running |
| `--scenes ID` | repeatable | Record only these scenes (comma-separated); the others keep their reference |

### simforge bench pack seal

Seal a pack directory as a content-addressed closure (writes the closure document and prints its pin)

Usage: `simforge bench pack seal [OPTIONS] --out <DIR> <PACK_DIR>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<pack_dir>` | required | The pack directory |
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--out DIR` | required | Write the closure root (closures/<digest>.json, blobs/sha256/..) here, ready to publish |

### simforge bench run

Run the benchmark (the default when no subcommand is given)

Usage: `simforge bench run [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--suite SUITE` | one of quick, full; default quick | Which scenes to run |
| `--scenes ID` | repeatable | Only these scene ids (comma-separated), from the suite's pack |
| `--set KEY=VALUE` | repeatable | Diagnostics: a render-config override (`simforge render --set` keys) on every scene. It changes the workload, so the result is recorded with its overrides and has no score (status `modified`) |
| `--gpu N` |  | The GPU to benchmark: its index in `nvidia-smi` (NVIDIA) or in the adapter list `simforge doctor` prints. Default: the renderer's choice (the first discrete GPU) |
| `--out FILE` |  | Write the result JSON here too (default: `simforge-bench-<time>.json` in the current directory) |
| `--pack DIR` |  | A local pack directory instead of the pinned pack (maintainers; also SIMFORGE_BENCH_PACK) |
| `--keep DIR` |  | Keep every sampled frame and the session logs in this directory |
| `--download-only` |  | Download and verify the suite's inputs (pack, map tier, actors, sky), then exit without rendering |
| `--allow-busy` |  | Run even when another process is using the GPU (the result is flagged `gpu-shared`) |
| `--stall-timeout-s SECONDS` | default 300 | Kill a scene session that makes no progress for this long (a hung GPU submission); the scene is reported failed and the remaining scenes run in a new session |
| `--quiet` |  | No progress or table on stderr (the JSON result on stdout is unchanged) |
| `--cache-root DIR` |  | Map cache root. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |

## catalog

### simforge catalog batch

Resumable catalog materialisation + simulation with an attempt ledger

Usage: `simforge catalog batch [OPTIONS] <CATALOG>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<catalog>` | required | The catalog manifest (its slot statuses are updated in place) |
| `--ledger FILE` |  | The attempt ledger (default: catalog-execution-ledger.json beside the catalog) |
| `--slots IDS` |  | Only these slot identities, comma-separated |
| `--map MAP` |  | Only slots on this map |
| `--maps MAPS` |  | Only slots on these maps, comma-separated |
| `--mechanisms IDS` |  | Only these incident mechanisms, comma-separated |
| `--attempts N` |  | Attempts per slot, 1 to 100 (default 3) |
| `--concurrency N` |  | Parallel slots, 1 to 32 (default: min(4, CPUs)) |
| `--force` |  | Start a fresh ledger instead of resuming |
| `--filter MODE` |  | Evaluation filter: critical \| negative-control \| all |
| `--trivial-ttc SECONDS` |  | Time-to-collision (s) below which a conflict counts as trivial |
| `--allow-collisions` |  | Accept attempts whose simulation collided |
| `--require-full-coverage` |  | Refuse a catalog that does not cover every taxonomy mechanism (default: run it and report the gap as `coverage`) |

### simforge catalog create

Reserve exactly 100 deterministic scenario identities per selected installed map (mechanisms no map can host are reported as `coverage`, exit 0)

Usage: `simforge catalog create [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--out FILE` |  | Write the catalog manifest here |
| `--map MAP` |  | One installed map |
| `--maps MAPS` |  | Several installed maps, comma-separated, in this order (default: every installed map) |
| `--dev-assets DIR` |  | The installed-maps directory (default: SCEN_DEV_ASSETS, else <maps root>/dev-assets) |
| `--namespace NAME` |  | Identity namespace mixed into every seed |
| `--evidence-root DIR` |  | Evidence directory, relative to the catalog file (default: evidence) |
| `--require-full-coverage` |  | Fail (exit 2, incomplete_mechanism_coverage) when the maps cannot cover every taxonomy mechanism. Default: write the catalog and report the gap as `coverage` |

### simforge catalog verify

Reject catalog identity, cardinality, provenance or evidence gaps (exit 2); uncovered mechanisms are reported as `coverage` unless --require-full-coverage

Usage: `simforge catalog verify [OPTIONS] <CATALOG>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<catalog>` | required | The catalog manifest |
| `--evidence-root DIR` |  | Where the evidence tree physically is (default: beside the manifest) |
| `--require-evidence` |  | Require every evidence file, not only those implied by slot status |
| `--require-full-coverage` |  | Fail (exit 2, insufficient_taxonomy_breadth) when the catalog does not cover every taxonomy mechanism. Default: report the gap as `coverage` |

## cell

### simforge cell migrate

Convert a scenario-instance envelope (an archived instance.json) into a cell, one way

Usage: `simforge cell migrate [OPTIONS] --out <DIR> <INSTANCE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<instance>` | required | The scenario-instance envelope |
| `--out DIR` | required | The directory to write cell.json, input.json (and scenario.json) into |
| `--template FILE` |  | The template the instance was compiled from (checked against its templateDigest), to recover the pinned scenario |

### simforge cell refresh

Compile a cell's scenario again and rewrite its cell.json and input.json cache

Usage: `simforge cell refresh [OPTIONS] <CELL>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<cell>` | required | The cell (`cell.json` or `<stem>.cell.json`, beside its scenario) |

## challenge

### simforge challenge eval

Evaluate a driver image in the final-track simulator on scenes you downloaded (`--local`)

Usage: `simforge challenge eval [OPTIONS] [ARGV]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<argv>` | repeatable | Arguments for `simforge-challenge` (see `simforge-challenge --help`) |

### simforge challenge status

Your team, the submissions you have left and your registry repository

Usage: `simforge challenge status [OPTIONS]`

### simforge challenge submissions

Your team's submissions, their status and scores

Usage: `simforge challenge submissions [OPTIONS]`

### simforge challenge submit

Push a driver image to your team's repository and submit it for the next nightly batch

Usage: `simforge challenge submit [OPTIONS] <IMAGE>`

| Argument / flag | Notes | What |
|---|---|---|
| `<image>` | required | A local docker image (name:tag or id) implementing the challenge driver interface |
| `--track TRACK` | one of dev, final; default dev |  |

### simforge challenge validate

Validate a driver image against the submission contract, in the nightly batch's sandbox

Usage: `simforge challenge validate [OPTIONS] [ARGV]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<argv>` | repeatable | Arguments for `simforge-challenge` (see `simforge-challenge --help`) |

## cli

### simforge cli install

Download and install the staff local CLI with default-feature commands

Usage: `simforge cli install [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--target TARGET` | default x86_64-unknown-linux-gnu | The platform to download for (a Rust target triple). Default: this machine's |
| `--version VERSION` |  |  |
| `--prefix PREFIX` |  | Where to install `simforge`. Default: ~/.local/bin, or %LOCALAPPDATA%\SimForge\bin on Windows |

## closed-loop

### simforge closed-loop

Run a hosted closed-loop evaluation of a scripted or trajectory policy on a scenario revision

Usage: `simforge closed-loop [OPTIONS] --revision <REVISION_ID> <SCENARIO_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<scenario_id>` | required | The hosted scenario |
| `--revision REVISION_ID` | required | Its immutable revision |
| `--policy POLICY` | one of scripted, trajectory; default scripted | The policy that drives the ego |
| `--steps STEPS` |  | Simulation steps to run |
| `--seed SEED` |  | Simulation seed |
| `--wait` |  | Wait for the run to finish |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |

## datasets

### simforge datasets copy

Copy scenarios of a dataset shared with every workspace (SIMLOG-25k) into one of your datasets

Usage: `simforge datasets copy [OPTIONS] <DATASET>`

| Argument / flag | Notes | What |
|---|---|---|
| `<dataset>` | required | The dataset id |
| `--filter FILTER` |  | Library filters as `key:value` (repeat a key or comma-separate values), e.g. 'grade:A tag:cut-in' |
| `--q Q` |  | Free-text search, as in the library's search box |
| `--source-log SOURCE_LOG` |  | Only the scenarios of one recorded drive (its recording digest or source id) |
| `--ids IDS` | repeatable | Exactly these scenarios (document ids, comma-separated) |
| `--into INTO` |  | Copy into this dataset of your workspace (its id) |
| `--new NEW` |  | Copy into a new dataset of this name |
| `--detach` |  | Start the copy and print it without waiting |

### simforge datasets copy-status

One copy: its state and counts (copied, skipped as already there, failed)

Usage: `simforge datasets copy-status [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

### simforge datasets list

List the hosted datasets your workspace can read

Usage: `simforge datasets list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` |  | At most this many items |
| `--status STATUS` |  | Only items in this status |
| `--type TYPE` |  | Only items of this type |

### simforge datasets pull

Download a dataset, a filter of it or chosen scenarios as files (resumable; --dry-run sizes it)

Usage: `simforge datasets pull [OPTIONS] <DATASET>`

| Argument / flag | Notes | What |
|---|---|---|
| `<dataset>` | required | The dataset id (`simforge datasets list`) |
| `--filter FILTER` |  | Library filters as `key:value` (repeat a key or comma-separate values), e.g. 'grade:A tag:cut-in' |
| `--q Q` |  | Free-text search, as in the library's search box |
| `--source-log SOURCE_LOG` |  | Only the scenarios of one recorded drive (its recording digest or source id) |
| `--ids IDS` | repeatable | Exactly these scenarios (document ids, comma-separated) |
| `--include INCLUDE` | repeatable | Beside each scenario's document, OpenSCENARIO, trace and resolution: renders[:training\|showcase\|schematic], labels, gt, recordings (default renders:training; `scenarios` alone for nothing else) |
| `--passes PASSES` | repeatable | Keep only these render modalities: rgb, depth, semantic, instance, lidar, radar |
| `--out OUT` |  | The folder to pull into (required unless --dry-run). Pulling again into it resumes |
| `--jobs JOBS` | default 8 | Parallel downloads |
| `--wait-pending WAIT_PENDING` | default 1800 | Seconds to wait for files the platform is still preparing before giving up on them |

### simforge datasets show

One hosted dataset

Usage: `simforge datasets show [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

### simforge datasets verify

Check a pulled folder against its manifest.json and SHA256SUMS (offline)

Usage: `simforge datasets verify [OPTIONS] <DIR>`

| Argument / flag | Notes | What |
|---|---|---|
| `<dir>` | required | The pulled folder |

## doctor

### simforge doctor

Check this machine: GPU adapter, ffmpeg, cache roots, disk, registry reachability

Usage: `simforge doctor [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--offline` |  | Do not probe the registry (the check is reported as skipped, never as ok) |
| `--registry URL` |  | Registry to probe. Default: SIMFORGE_MAPS_REGISTRY, then the staff map registry (AWS credentials required) |
| `--timeout SECONDS` | default 10 | Network timeout for the registry probe |

## drafts

### simforge drafts apply add-actor

Place a new actor: a road vehicle on a semantic lane, or a pedestrian/free static actor at a scene point.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--body-color BODY_COLOR` |  | Presentation body colour `#rrggbb`. |
| `--catalog-id CATALOG_ID` | required | Built-in actor (`simforge scenario actors`): vehicle.sedan, pedestrian.adult, ... |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | New actor id (never allocated implicitly). |
| `--label LABEL` |  | Display label. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--opposing` |  | Snap to the nearest genuinely opposing lane. |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--speed-kph N` |  | Initial speed; default: posted limit for road vehicles. [0..160 km/h] |
| `--static` |  | Place as a static actor (no motion, zero speed). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge drafts apply add-lane-change

Add a timed lane change for a mobile lane-bound road actor.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-lane-change [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--direction DIRECTION` | required; one of left, right | Target lane side. |
| `--duration-s N` |  | Lane-change duration. [> 0 s] (default 3) |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--start-s N` | required | Clip time the change starts. [>= 0 s] |

### simforge drafts apply add-next-junction-turn

Choose the turn an actor takes at its next junction.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-next-junction-turn [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--direction DIRECTION` | required; one of left, right, straight | Movement at the next junction. |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--start-s N` | required | Clip time the choice applies from. [>= 0 s] |

### simforge drafts apply duplicate-actor

Copy an actor with its presentation and own events under a new id at a new position.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> duplicate-actor [OPTIONS] --id <ID> --new-id <NEW_ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | Source actor. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--new-id NEW_ID` | required | New actor id. |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge drafts apply move-actor

Move an actor to a lane station or scene point, keeping identity, class, static state and speed.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> move-actor [OPTIONS] --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | Actor to move. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge drafts apply remove-role

Delete an actor with dependent events, reasoning and ego handoff.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> remove-role [OPTIONS] --id <ID> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--id ID` | required | Actor to delete. |

### simforge drafts apply set-actor-speed

Set an actor's initial speed.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-actor-speed [OPTIONS] --id <ID> --speed-kph <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--id ID` | required | Actor. |
| `--speed-kph N` | required | Initial speed. [0..160 km/h] |

### simforge drafts apply set-actor-static

Make an actor static (clears its route and motion events) or mobile again.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-actor-static [OPTIONS] --id <ID> --static <BOOL> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--id ID` | required | Actor. |
| `--static BOOL` | required; one of true, false | true: static; false: mobile. |

### simforge drafts apply set-clip

Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-clip [OPTIONS] <--clip-seconds <N>|--warmup-seconds <N>> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--clip-seconds N` |  | Clip length. [3..120 s] |
| `--warmup-seconds N` |  | Warm-up before the clip. [0..30 s] |

### simforge drafts apply set-clock

Set the precise scene clock; the time of day becomes the label of the sun at the map's site on the scenario's day.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-clock [OPTIONS] --minutes <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--minutes N` | required | Minutes after local midnight. [0..1439 min] |

### simforge drafts apply set-ego

Make an actor the ego vehicle.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-ego [OPTIONS] --role-id <ROLE_ID> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--role-id ROLE_ID` | required | Actor to make ego. |

### simforge drafts apply set-event-timing

Retime an event's start and optional end.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-event-timing [OPTIONS] --id <ID> --start-s <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--end-s N` |  | End clip time. [>= 0 s] |
| `--id ID` | required | Event. |
| `--start-s N` | required | Start clip time. [>= 0 s] |

### simforge drafts apply set-waypoint-route

Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-waypoint-route [OPTIONS] --actor-id <ACTOR_ID> --duration-s <N> --id <ID> --point <X,Z> --start-s <N> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--duration-s N` | required | Route duration. [> 0 s] |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--point X,Z` | required; repeatable | Scene points, the actor's start first. Repeat once per item, at least 2. |
| `--start-s N` | required | Clip time the route starts. [>= 0 s] |

### simforge drafts apply set-weather

Set the scenario weather.

Usage: `simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-weather [OPTIONS] --weather <WEATHER> [-- [OPERATION]...]`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--weather WEATHER` | required; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleet | Canonical scenario weather. |

### simforge drafts create

Create a workspace draft on an exact map version; prints its receipt (documentId, draftVersion, contentDigest, mapPin)

Usage: `simforge drafts create [OPTIONS] --map <MAP_VERSION_ID> --name <NAME>`

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP_VERSION_ID` | required | The map version id the draft is pinned to |
| `--name NAME` | required |  |
| `--dataset DATASET_ID` |  | The writable dataset; absent, the credential's default dataset (named in the receipt) |
| `--clip-seconds S` |  |  |

### simforge drafts freeze

Freeze the draft as an immutable revision (revisionId, revisionContentDigest) for simulate/render

Usage: `simforge drafts freeze [OPTIONS] --expected-version <N> --expected-digest <SHA256> <DRAFT_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |
| `--name NAME` |  | The revision's name |

### simforge drafts save

Save the draft through the workspace store at an explicit version and digest

Usage: `simforge drafts save [OPTIONS] --expected-version <N> --expected-digest <SHA256> <DRAFT_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `--expected-version N` | required | The draftVersion of the receipt this change is based on |
| `--expected-digest SHA256` | required | The contentDigest of the receipt this change is based on |

### simforge drafts show

The draft's current receipt and content: version, digest, map/actor/recording pins

Usage: `simforge drafts show [OPTIONS] <DRAFT_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |

### simforge drafts validate

Validate every actor of the draft, optionally with the authoritative preview; exit 2 on findings

Usage: `simforge drafts validate [OPTIONS] <DRAFT_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<draft_id>` | required |  |
| `--strict` |  | Warnings are findings too |
| `--preview` |  | Run the authoritative materializer/engine preview (every actor, collisions, quality issues) |

## engine-info

### simforge engine-info

What this binary is: package version, engine semver, commit and its own sha256 (to record with results)

Usage: `simforge engine-info [OPTIONS]`

Runs on: local runtime.

## env

### simforge env serve

Serve reset/step/observe episodes over a local socket or named pipe

Usage: `simforge env serve [OPTIONS] --socket <PATH> <WORKSPACE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<workspace>` | required | The scenario package or workspace directory (a package without a simulation is compiled from its document and recordings) |
| `--socket PATH` | required | Local endpoint path; Windows derives a same-user named pipe from this path |
| `--rig RIG.JSON` |  | The sensor rig (`simforge.render-rig/v1`, as `simforge render` takes it) |
| `--no-sensors` |  | Serve the episode without a renderer (observations are the engine's only) |
| `--observation-profile OBSERVATION_PROFILE` | one of state, sensors, both | Restrict observations to state, sensors, or both; omission preserves the native layout |
| `--preset PRESET` | one of training, showcase; default training | The render preset for observations (`schematic` is offline `simforge render` only) |
| `--passes PASSES` | one of rgb, hdr, id, depth, semantic; default rgb; repeatable | Camera passes rendered per observation, comma-separated |
| `--textures TEXTURES` | one of uastc-full, bc7-512; default uastc-full | The staged texture tier |
| `--episode EPISODE.JSON` |  | Episode configuration (camelCase `EpisodeConfig`, as the gym's episode specs carry it) |
| `--decision-hz HZ` |  | Policy decisions per second (overrides the episode's `decisionHz`) |
| `--max-objects N` | default 64 | Rows of the `objects` observation |
| `--allow-software-adapter` |  | Render on a software (CPU) Vulkan adapter such as lavapipe, explicitly |
| `--map-dir DIR` |  | Use this map directory instead of the installed map found by content |
| `--cache-root DIR` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure to bind, instead of the workspace's `catalog.actorClosureDigest` |
| `--actor-layer SHA256` |  | The workspace's private model layer (an actor closure in the same store) for `workspace.*` models, instead of the workspace's `simforge.actorLayer` extension |
| `--vram-budget BYTES` |  | A texture budget in bytes; without it admission is skipped (reported) |
| `--log FILE` |  | Where the renderer's diagnostics go. Default: `<socket>.log` |
| `--allow-map-drift` |  | Render on the installed map release even where its members differ from the workspace's map closure (recorded; the default refuses) |
| `--max-sessions N` | default 8 | Maximum concurrent client sessions sharing one prewarmed renderer. Training defaults to eight sessions per map renderer |
| `--shm-size-mb MIB` | default 512 | Size of the renderer's shared-memory frame ring, MiB |

## evaluate

### simforge evaluate

The reject filters (and an optional intent rubric) over a trace; exit 2 when it rejects

Usage: `simforge evaluate [OPTIONS] <TRACE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<trace>` | required | The trace (`.trace.json` or `.trace.json.gz`, any released format). With --cloud: The hosted scenario to evaluate |
| `--filter MODE` |  | Reject filters: critical \| negative-control \| all |
| `--trivial-ttc S` |  | The trivially-safe TTC threshold, seconds |
| `--reject-collisions` |  | Reject any collision |
| `--motion-audit-version MOTION_AUDIT_VERSION` |  |  |
| `--rubric FILE` |  | An intent rubric (IntentRubric JSON) evaluated alongside criticality |
| `--blind-review-out FILE` |  | Write the context-blind review packet here (needs --rubric) |
| `--traffic-law MAP_DIR` |  | Measure red-light and stop-bar compliance on this installed map directory (`map.xodr`, `derived/odr/locations-v2.json.gz`); reported as `trafficLaw` |
| `--traffic-law-actor ACTOR` | repeatable | An actor to measure (repeatable; default: the trace's metric subject) |
| `--revision REVISION_ID` |  | The scenario's immutable revision Required with --cloud. |
| `--mode MODE` |  | The evaluation mode |
| `--wait` | one of true, false | Wait for the run to finish |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required unless --dry-run |

## evidence

### simforge evidence verify

Check that a trace is the run of an instance (exit 2 on any mismatch)

Usage: `simforge evidence verify [OPTIONS] <INSTANCE> <TRACE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<instance>` | required | The instance: a scenario cell, a pinned scenario (compiled), or a bare SimScenarioInput |
| `<trace>` | required | The trace (`.trace.json` or `.trace.json.gz`) |

## export

### simforge export

A concrete instance as ASAM OpenSCENARIO XML 1.4, XML 1.3 (esmini) or DSL 2.2, with a capability report

Usage: `simforge export [OPTIONS] --format <FORMAT> --out <FILE> <INSTANCE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<instance>` | required | The instance: a scenario cell, a pinned scenario, a bare SimScenarioInput, or a `log import` workspace directory (XML formats replay its recorded trace) |
| `--format FORMAT` | required | xosc-1.4 \| xosc-1.3-esmini \| osc-2.2 |
| `--out FILE` | required | Write the document here |
| `--road-file FILE` |  | The road-network file the document references (default `<mapId>.xodr`) |
| `--author NAME` |  | FileHeader author |
| `--description TEXT` |  | FileHeader description |
| `--route-sample-m M` |  | Maximum distance between exported route waypoints, metres (default 20) |
| `--trajectory-tolerance-m M` |  | XML: omit trajectory vertices that interpolation reproduces within this many metres, 0.1 deg and 0.1 m/s (default: every sample) |

## import

### simforge import log

A recording (simforge.recording/v1 or log-scene/v1) as a scenario package: scenario, recording, trace, import report

Usage: `simforge import log [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <RECORDING>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<recording>` | required | The recording (JSON, optionally gzipped). With --cloud: The log: a recording (JSON, optionally gzipped) or a ROS 2 MCAP lidar log |
| `--map DIR\|NAME@VERSION` | required | The installed map: a map directory, or name[@version] under the maps cache (semantic profile) |
| `--out DIR` | required | The package directory to write (created; must be empty if it exists) |
| `--report REPORT.JSON` |  | The register step's import report (`simforge.import-report/v1` fields: methods, registration, laneMatch, droppedActors), merged into the package's |
| `--cache-root DIR` |  | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure the package pins (default: this CLI's pinned public closure) |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded; the default refuses) |
| `--name NAME` |  | The scenario's name. Default: the file's name |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents |
| `--lidar-topic TOPIC` |  | MCAP only: the lidar topic, when the log has several |
| `--gnss-topic TOPIC` |  | MCAP only: the GNSS topic, when the log has several |
| `--ego-dims L,W,H` | repeatable | MCAP only: the ego's box in metres, length,width,height (perceive's default otherwise) |
| `--ego-rear-axle-to-centre METRES` |  | MCAP only: how far the ego box's centre is ahead of base_link (the rear axle), metres |

### simforge import openscenario

An OpenSCENARIO 1.x XML file as a scenario package; its map is found by the OpenDRIVE's sha256, and every element it cannot represent is refused by name

Usage: `simforge import openscenario [OPTIONS] --out <DIR> <FILE.xosc>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<file.xosc>` | required | The OpenSCENARIO 1.x XML file; its catalogs and OpenDRIVE are read beside it |
| `--out DIR` | required | The package directory to write (created; must be empty if it exists) |
| `--map-version DIR\|NAME@VERSION` |  | The map version: a map directory, or name[@version] under the maps cache. It must hold the file's OpenDRIVE. Default: the installed map whose OpenDRIVE has the file's sha256 |
| `--ego ENTITY` |  | The ego entity (default: one named ego or hero, else the first vehicle) |
| `--clip-seconds S` |  | The clip, when the storyboard does not stop at a simulation time |
| `--cache-root DIR` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure the package pins (default: this CLI's pinned public closure) |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded; the default refuses) |

## instantiate

### simforge instantiate

Template x site x draw -> one scenario pinned to them

Usage: `simforge instantiate [OPTIONS] --map <MAP> --site <SITE> <TEMPLATE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<template>` | required | The v2 template |
| `--map MAP` | required | The installed map |
| `--site SITE` | required | A site id from `simforge sites match` |
| `--seed SEED` |  | The scenario's seed identity (`simulation.seed`), from which the cell seed derives |
| `--draw N` |  | The parameter draw index (a batch cell); pinned with the parameter block's frozen version |
| `--out FILE` |  | Also write the pinned scenario here |

## keys

### simforge keys create

Create an API key for this workspace; its secret is printed once

Usage: `simforge keys create [OPTIONS] --name <NAME>`

| Argument / flag | Notes | What |
|---|---|---|
| `--name NAME` | required | A name to recognize the key by (1-200 characters) |
| `--scope SCOPE` | repeatable | A scope the key holds (repeatable). Default: maps:read scenarios:read scenarios:write datasets:read runs:read runs:write artifacts:read usage:read |
| `--expires-in-days DAYS` |  | Expire the key after this many days (1-3650). Default: no expiry |

### simforge keys list

List the workspace's API keys (never their secrets)

Usage: `simforge keys list [OPTIONS]`

### simforge keys revoke

Revoke an API key now; requests with it stop resolving immediately

Usage: `simforge keys revoke [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The key's id (`key_…`, from `simforge keys list`) |

## locations

### simforge locations find

Structured query: type, subtype, tags, affordances, facts, proximity

Usage: `simforge locations find [OPTIONS] --map <MAP>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP` | required | The installed map |
| `--type TYPES` | repeatable | Location types, comma-separated (any of) |
| `--subtype SUBTYPES` | repeatable | Subtypes, comma-separated (any of) |
| `--tags TAGS` | repeatable | Tags, comma-separated (any of) |
| `--affordances AFFORDANCES` | repeatable | Affordances, comma-separated (any of) |
| `--facts FACTS` | repeatable | Fact predicates, comma-separated, all of: `k=v`, `k>=v`, `k<=v`, `k!=v`, `k>v`, `k<v`, `k~v`, `k=?`, `k=!?` |
| `--near HANDLE` |  | Only locations within --within-m of this handle or id, nearest first |
| `--within-m M` |  | Radius for --near, metres (default 250) |
| `--limit N` |  | At most this many results (default 25, cap 200) |
| `--diversity-m M` |  | Drop results within this many metres of an already selected one |

### simforge locations get

One location by handle or id (optionally with a description paragraph)

Usage: `simforge locations get [OPTIONS] --map <MAP> <HANDLE_OR_ID>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<handle_or_id>` | required | A handle (`junction/rd-38-rd-34`) or id (`loc_...`) |
| `--map MAP` | required | The installed map |
| `--describe` |  | Add the natural-language description an agent reads before authoring |

### simforge locations resolve

Free text -> ranked handles (exit 2 when nothing matched)

Usage: `simforge locations resolve [OPTIONS] --map <MAP> [TEXT]...`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<text>` | repeatable | Free text ("the crosswalk by the school") |
| `--map MAP` | required | The installed map |
| `--limit N` |  | At most this many results (default 8) |

## log

### simforge log import

Scaffold and compile a simforge.recording/v1 (or log-scene/v1) recording into a simulated, renderable workspace

Usage: `simforge log import [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <SCENE.JSON>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<scene.json>` | required | The recording (simforge.recording/v1, or simforge.log-scene/v1; JSON, optionally gzipped) |
| `--map DIR\|NAME@VERSION` | required | The installed map: a map directory, or name[@version] under the maps cache (semantic profile) |
| `--out DIR` | required | The workspace to write (created; must be empty if it exists) |
| `--mode MODE` | one of replay; default replay |  |
| `--cache-root DIR` |  | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure the workspace pins (default: this CLI's pinned public closure) |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded; the default refuses) |

### simforge log import-many

Run many `log import` jobs in one process (each map's world loaded once); per job the same workspace and result

Usage: `simforge log import-many [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--jobs JOBS.JSON` |  | The jobs: `{"jobs": [{"scene": SCENE.JSON, "map": DIR\|NAME@VERSION, "out": DIR}, ...]}`, run in order |
| `--stream` |  | Read one job object per stdin line and write one result line per job to stdout as it ends (until EOF) |
| `--mode MODE` | one of replay; default replay |  |
| `--cache-root DIR` |  | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure every workspace pins (default: this CLI's pinned public closure) |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded; the default refuses) |

## login

### simforge login

Sign in to a SimForge host (browser approval, or --device for a URL and code)

Usage: `simforge login [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--host HOST` |  | SimForge host to sign in to. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai. Later commands use the host signed in to |
| `--device` |  | Sign in with a code instead of a local browser: print a URL and a short code to approve from any browser (SSH, headless machines) |
| `--scope SCOPE` | repeatable | A scope to request on top of the defaults (repeatable), such as keys:admin to manage API keys. The defaults cover map/runtime downloads and scenario/cloud jobs |
| `--credential-store STORE` | one of auto, keyring, file | Where to keep the tokens. Default: SIMFORGE_CREDENTIAL_STORE, then auto (the OS keychain, else a 0600 file; the output says which and why) |
| `--device-name NAME` |  | The name the approval page and the CLI sessions list show for this machine. Default: the host name |
| `--timeout SECONDS` | default 600 | Seconds to wait for the approval |

## logout

### simforge logout

Sign out of a host: revoke this machine's session and delete its stored tokens

Usage: `simforge logout [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--host HOST` |  | SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai |

## maps

### simforge maps list

List the hosted maps your workspace can use

Usage: `simforge maps list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` |  | At most this many items |
| `--status STATUS` |  | Only items in this status |
| `--type TYPE` |  | Only items of this type |

### simforge maps pull

Download a map your signed-in account is entitled to into the local cache, sha256-verified

Usage: `simforge maps pull [OPTIONS] <MAP>`

| Argument / flag | Notes | What |
|---|---|---|
| `<map>` | required | SimForge-owned map name, optionally pinned as NAME@VERSION |
| `--cache-root CACHE_ROOT` |  | Map cache directory. Default: the SimForge maps cache |
| `--accept-license` |  | Explicitly accept the current license and terms, which include the map pack terms, before downloading |

### simforge maps show

One hosted map and its versions

Usage: `simforge maps show [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

## mcp

### simforge mcp

Expose this command surface as MCP tools over stdio

Usage: `simforge mcp [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--cwd DIR` |  | Working directory for tool calls that do not pass `cwd` (default: this process's) |
| `--only COMMAND` | repeatable | Expose only the commands under these command paths (repeatable, e.g. `--only render --only "scenario apply"`) |

## open-loop

### simforge open-loop artifacts

A download grant ({url, sha256, bytes, ...}) for one artifact of the evaluation's result

Usage: `simforge open-loop artifacts [OPTIONS] <EVALUATION_ID> <ARTIFACT_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<evaluation_id>` | required | The evaluation (`cmpj_...`) |
| `<artifact_id>` | required | The artifact, by its id in the result manifest |

### simforge open-loop list

List the workspace's evaluations

Usage: `simforge open-loop list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` |  | At most this many evaluations (1-100) |
| `--status STATUS` |  | Only evaluations in these statuses (comma-separated) |
| `--cursor CURSOR` |  | The page after this cursor (`nextCursor` of the previous page) |

### simforge open-loop result

The evaluation's result manifest: scored metrics, artifacts, model/render/source pins and compute cost

Usage: `simforge open-loop result [OPTIONS] <EVALUATION_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<evaluation_id>` | required | The evaluation (`cmpj_...`) |

### simforge open-loop run

Score a succeeded cloud scenario render with the pinned Alpamayo 1.5 model (requires --cloud, --max-cost and --idempotency-key, also with --dry-run)

Usage: `simforge open-loop run [OPTIONS] --max-cost <CENTS> <RENDER_RUN_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<render_run_id>` | required | The succeeded cloud scenario render run to evaluate |
| `--prediction-interval-s SECONDS` | default 0.5 | Seconds between scored prediction instants across the whole render; an exact multiple of 0.1 (0.5 = 2 Hz) |
| `--seed SEED` | default 1 | Model sampling seed |
| `--samples N` | default 1 | Trajectory samples drawn by the model |
| `--max-cost CENTS` | required | Explicit maximum cloud cost in cents; required, also with --dry-run |
| `--wait` |  | Wait for the evaluation to finish |

### simforge open-loop show

One evaluation: status, cost and attempts

Usage: `simforge open-loop show [OPTIONS] <EVALUATION_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<evaluation_id>` | required | The evaluation (`cmpj_...`) |

### simforge open-loop watch

Follow an evaluation until it succeeds, is partial, fails or is cancelled

Usage: `simforge open-loop watch [OPTIONS] <EVALUATION_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<evaluation_id>` | required | The evaluation (`cmpj_...`) |

## package

### simforge package import

Verify, then unpack into a local workspace

Usage: `simforge package import [OPTIONS] --into <DIR> <PACKAGE.ZIP>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<package.zip>` | required | The package file |
| `--into DIR` | required | The workspace directory to create (must not exist, or be empty) |
| `--cache-root DIR` |  | Map cache root to check for the package's map. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root to check for the package's actor closure. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--offline` |  | Fetch nothing: report the map and actor closure this machine still lacks |
| `--registry URL` |  | Map registry to resolve the package's map from. Staff local builds support s3:// with AWS credentials. Default: SIMFORGE_MAPS_REGISTRY, then the staff map registry |
| `--profile PROFILE` | one of full, planar; default full | How to install a map the cache lacks: `full` (every profile) or `planar` (`maps pull --profile planar --with ground`: the road network, its planar derivatives, the static colliders and the ground, enough to simulate and render in 2D; a 3D render needs `full`). Either satisfies a planar import; only a full install satisfies a full one |
| `--assets-base-url URL` |  | Asset store for the actor closure. Default: SIMFORGE_ACTOR_ASSETS_BASE_URL, then the public store |

### simforge package inspect

Print a package's manifest, producer and members without unpacking it

Usage: `simforge package inspect [OPTIONS] <PACKAGE.ZIP>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<package.zip>` | required | The package file |

### simforge package verify

Verify the manifest and every member digest; exit 2 on any mismatch

Usage: `simforge package verify [OPTIONS] <PACKAGE.ZIP>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<package.zip>` | required | The package file |

## preview

### simforge preview clip

A short clip of a scenario from --at for --seconds (MP4), locally or with --cloud

Usage: `simforge preview clip [OPTIONS] --out <OUT> <TARGET> [EXTRA]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<target>` | required | Scenario JSON file or materialized workspace; identical input for local and cloud |
| `<extra>` | repeatable |  |
| `--out OUT` | required | Output file (PNG for a frame, MP4 for a clip) |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d |  |
| `--rig RIG` |  | Sensor rig JSON (`simforge rig init`). Default: the `basic-dash-camera` rig on the ego |
| `--camera CAMERA` |  | The rig camera to look through |
| `--at AT` | default 0 | Scenario time in seconds |
| `--seconds SECONDS` |  | Clip length in seconds |
| `--preset PRESET` | one of training, showcase, schematic | Render preset |
| `--force` |  | Overwrite an existing output file |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--revision REVISION` |  | Immutable revision for an existing hosted scenario target |
| `--wait` |  | Wait for a submitted cloud job to finish |
| `--download` |  | Download a succeeded cloud job into --out; implies --wait |
| `--map-dir DIR` |  | Render on this native map directory (`.corpus/<map>`) instead of the installed map found by content |
| `--ego ACTOR_ID` |  | The 2D camera's ego actor; otherwise the workspace or scenario selects it |
| `--textures TEXTURES` | one of uastc-full, bc7-512 | The staged texture tier of a photoreal preview (as `render --textures`). Default: uastc-full |

### simforge preview frame

One still frame of a scenario at --at seconds (PNG), locally or with --cloud

Usage: `simforge preview frame [OPTIONS] --out <OUT> <TARGET> [EXTRA]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<target>` | required | Scenario JSON file or materialized workspace; identical input for local and cloud |
| `<extra>` | repeatable |  |
| `--out OUT` | required | Output file (PNG for a frame, MP4 for a clip) |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d |  |
| `--rig RIG` |  | Sensor rig JSON (`simforge rig init`). Default: the `basic-dash-camera` rig on the ego |
| `--camera CAMERA` |  | The rig camera to look through |
| `--at AT` | default 0 | Scenario time in seconds |
| `--seconds SECONDS` |  | Clip length in seconds |
| `--preset PRESET` | one of training, showcase, schematic | Render preset |
| `--force` |  | Overwrite an existing output file |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--revision REVISION` |  | Immutable revision for an existing hosted scenario target |
| `--wait` |  | Wait for a submitted cloud job to finish |
| `--download` |  | Download a succeeded cloud job into --out; implies --wait |
| `--map-dir DIR` |  | Render on this native map directory (`.corpus/<map>`) instead of the installed map found by content |
| `--ego ACTOR_ID` |  | The 2D camera's ego actor; otherwise the workspace or scenario selects it |
| `--textures TEXTURES` | one of uastc-full, bc7-512 | The staged texture tier of a photoreal preview (as `render --textures`). Default: uastc-full |

## recording

### simforge recording from-trace

Save a simulation's trace (a rollout) as a simforge.recording/v1 recording

Usage: `simforge recording from-trace [OPTIONS] --out <FILE> --producer <PRODUCER> <TRACE|DIR>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<trace\|dir>` | required | The trace (`trace.json[.gz]`), or a workspace/package directory (its `simulation/trace.json.gz`) |
| `--out FILE` | required | The recording to write (gzipped canonical JSON; the conventional name is `<sha256>.rec.json.gz`) |
| `--producer PRODUCER` | required | The producer recorded in `source.producer` (id and version) |
| `--clip-ref CLIP_REF` | default  | An opaque reference to the rollout (`source.clipRef`) |
| `--license LICENSE` |  | The licence of the rollout's inputs, when it carries one |
| `--ego EGO` |  | The ego actor id (default: the trace's metricSubject) |
| `--map-version MAP_VERSION` |  | The map release version the trace ran on (`map.version`), when known |

### simforge recording inspect

Read a recording through the contract: its digest, map, size and lineage

Usage: `simforge recording inspect [OPTIONS] <RECORDING>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<recording>` | required | The recording (simforge.recording/v1 or log-scene/v1, optionally gzipped) |

### simforge recording scaffold

A registered recording as a scenario package that carries no simulation: the scaffolded scenario, the recording it pins and the report of the operation that made it

Usage: `simforge recording scaffold [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <RECORDING>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<recording>` | required | The recording (simforge.recording/v1 or log-scene/v1, optionally gzipped); registered on the map |
| `--map DIR\|NAME@VERSION` | required | The map the recording was registered on: a map directory, or name[@version] under the maps cache (semantic profile) |
| `--out DIR` | required | The package directory to write (created; must be empty if it exists) |
| `--title NAME` |  | The scenario's name (`meta.name`; default "<producer> <clipRef>") |
| `--report REPORT.JSON` |  | The report the recording's `derivedFrom.reportSha256` names, packaged byte for byte (`transfer-report.json` or `import-report.json`, by its schema) |
| `--cache-root DIR` |  | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure the package pins (default: this CLI's pinned public closure) |

## render

### simforge render

Render the same scenario file locally or with --cloud

Usage: `simforge render [OPTIONS] <TARGET> [EXTRA]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<target>` | required | Scenario JSON file or materialized workspace; identical input for local and cloud |
| `<extra>` | repeatable | Runtime-specific options; forwarded without shell interpolation |
| `--out OUT` |  | Output folder; local requires it, cloud waits and downloads when it is given |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d |  |
| `--rig RIG` |  | Sensor rig JSON (`simforge rig init`). Default: the `basic-dash-camera` rig on the ego |
| `--preset PRESET` | one of training, showcase, schematic | Render preset |
| `--camera-detector FILE` |  | Local native render only: authored instantaneous HDR detector response JSON |
| `--camera-temporal FILE` |  | Local native render only: bounded exact-time HDR exposure request JSON |
| `--camera-delivery FILE` |  | Local bounded offline measurement delivery or controlled delivery-only resume |
| `--fps FPS` |  | Frame rate every camera records (2d: the video's), over the render preset's own rate; 3d takes 5 to 60 |
| `--wait` |  | Wait for a submitted cloud job to finish |
| `--download` |  | Download a succeeded cloud job into --out; implies --wait |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--revision REVISION` |  | Immutable revision for an existing hosted scenario target |
| `--replay-of RUN_ID` |  | Cloud 3d render: the drive a succeeded closed_loop run scored (its episode timeline), rendered on the target's revision that run drove |
| `--camera CAMERA` | one of follow-ego, overview; default follow-ego | 2d engine: the camera |
| `--north-up` |  | 2d engine, follow-ego: keep north up (looking ahead of the ego) instead of turning the view with it |
| `--debug-signals` |  | 2d engine: also draw signal heads the timeline has no phases for (hollow grey rings) |
| `--no-hud` |  | 2d engine: no HUD (header, legend, clock, speed); the map fills the whole frame |
| `--actor-labels LABELS.JSON` |  | 2d engine: tags to draw next to actors, a JSON object `{actorId: text}` (e.g. a labelling page's candidate numbers). An id that is not an actor of the timeline fails the render |
| `--legibility LEGIBILITY` | one of standard, high; default standard | 2d engine: icon legibility; `high` is for labelling clips (larger props, light people, faint untagged parked vehicles, no edge chevrons or collision marks, non-overlapping tag badges) |
| `--px-per-m PX` |  | 2d engine: a fixed map scale in pixels per metre. Default: 14 to 9 by the ego's speed (follow-ego); the scenario actors fitted, 5 to 12 (overview) |
| `--size WxH` | default 1280x720 | 2d engine: the frame size |
| `--ego ACTOR_ID` |  | 2d engine: the ego actor. Default: the workspace's metric subject |
| `--timeline TIMELINE.JSON` |  | Render a timeline instead of simulating the workspace, on the same map |
| `--clip START:END` |  | 2d engine: the clip, `START:END` seconds of the timeline. Default: the whole timeline |
| `--buildings` |  | 2d engine: draw building footprints when the map has them |
| `--title TEXT` |  | 2d engine: the header's title. Default: the map's name (its id in words) and the scenario's title from the package (else the workspace directory); render.json keeps the ids |
| `--lidar-model LIDAR_MODEL` | one of legacy, physical; default legacy | Native LiDAR model. `legacy` is the byte-identical default |
| `--lidar-profile NAME\|FILE` |  | Physical profile name (built-in) or a JSON profile file |
| `--lidar-seed LIDAR_SEED` | default 0 | Physical-model deterministic noise seed |
| `--lidar-motion-compensated` |  | Express physical returns in the sensor pose at sweep start |
| `--passes PASSES` | one of rgb, hdr, id, depth, semantic; default rgb,id,depth,semantic; repeatable | Camera passes, comma-separated |
| `--camera-capture-stage CAMERA_CAPTURE_STAGE` | one of scene-pre-postprocess/v1 | Capture renderer-relative HDR before postprocess, with capture-owned provenance |
| `--set KEY=VALUE` | repeatable | Render-config overrides on the preset (`key=value`, e.g. `aa.mode=fxaa`); repeatable |
| `--textures TEXTURES` | one of uastc-full, bc7-512 | The staged texture tier (photoreal presets). Default: uastc-full |
| `--video VIDEO` | one of auto, required, off; default auto | Encode videos with ffmpeg |
| `--vram-budget BYTES` |  | A texture budget in bytes; without it the device capacity is unmeasured and admission is skipped (reported) |
| `--allow-software-adapter` |  | Render on a software (CPU) Vulkan adapter such as lavapipe, explicitly. Slow; pixels differ from a GPU's |
| `--map-dir DIR` |  | Use this native map directory (`.corpus/<map>`) instead of the installed map found by content |
| `--cache-root DIR` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--assets-root DIR` |  | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets |
| `--actor-closure SHA256` |  | The actor closure to bind, instead of the workspace's `catalog.actorClosureDigest` |
| `--actor-layer SHA256` |  | The workspace's private model layer (an actor closure in the same store) for `workspace.*` models, instead of the workspace's `simforge.actorLayer` extension |
| `--allow-map-drift` |  | Render on the installed map release even where its members differ from the workspace's map closure (recorded in the result; the default refuses) |

## results

### simforge results download

Download a hosted run's artifacts, sha256-checked

Usage: `simforge results download [OPTIONS] <RUN_ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<run_id>` | required | The hosted run |
| `--out OUT` | default . | Directory to write the artifacts into |

## rig

### simforge rig capabilities

Print the generated native camera declaration; support tiers do not imply device qualification

Usage: `simforge rig capabilities [OPTIONS]`

### simforge rig consumer-schema

Print the v2 consumer acquisition sidecar schema; timestamps are scheduled render instants

Usage: `simforge rig consumer-schema [OPTIONS]`

### simforge rig consumer-video-schema

Print the legacy v1 consumer video sidecar schema, which has no acquisition timestamps

Usage: `simforge rig consumer-video-schema [OPTIONS]`

### simforge rig effective-config

Resolve camera identity and required features without executing a renderer

Usage: `simforge rig effective-config [OPTIONS] <RIG.JSON>`

| Argument / flag | Notes | What |
|---|---|---|
| `<rig.json>` | required |  |
| `--require CAMERA.FEATURE` | repeatable | Require a camera feature; repeat for each requirement. Unsupported combinations fail closed |

### simforge rig init

Write a built-in rig fitted to a carrier class's default box as a `simforge.render-rig/v1` file

Usage: `simforge rig init [OPTIONS] --preset <PRESET> --out <FILE>`

| Argument / flag | Notes | What |
|---|---|---|
| `--preset PRESET` | required; one of basic-dash-camera, tesla-hw3, waymo-5th-gen, surround-7cam-1lidar, roof-8cam-6lidar-4radar, alpamayo-2cam, alpamayo-4cam, alpamayo-6cam, alpamayo-6cam-vqa, front-4cam-wide-cross-tele, drone-inspection-wide, drone-inspection-wide-zoom, drone-mapping-nadir, drone-fpv-forward | The built-in rig |
| `--class CLASS` | one of car, truck, van, drone; default car | The carrier class whose default box the mounts are fitted to: car, truck or van for a road rig, drone for a drone rig |
| `--profile PROFILE` | one of training, showcase; default showcase | The render profile whose capture (size and frame rate) every camera of the rig records |
| `--actor ID` | default ego | The actor named in the file (every source's `actorId`); a render re-hosts a placeholder on the scenario's ego and refuses a file naming another of its roles |
| `--out FILE` | required | Where to write the rig |
| `--force` |  | Overwrite an existing file |

### simforge rig reported-schema

Print the reported-only calibration JSON Schema; hash integrity is checked by the consumer parser

Usage: `simforge rig reported-schema [OPTIONS]`

### simforge rig schema

Print the Platform-generated render-rig/v1 JSON Schema; cross-field checks also run in validate

Usage: `simforge rig schema [OPTIONS]`

### simforge rig show

What a rig captures: each source's mount, the way it faces and its field of view, and the cameras' horizontal coverage; the installed runtime shows a rig with a camera lens

Usage: `simforge rig show [OPTIONS] <RIG.JSON>`

| Argument / flag | Notes | What |
|---|---|---|
| `<rig.json>` | required | A `simforge.render-rig/v1` file |

### simforge rig validate

Check a `simforge.render-rig/v1` file as a render reads it; the installed runtime plans a camera lens (cameraModel). Exit 2 with the finding

Usage: `simforge rig validate [OPTIONS] <RIG.JSON>`

| Argument / flag | Notes | What |
|---|---|---|
| `<rig.json>` | required | A `simforge.render-rig/v1` file |

## runs

### simforge runs cancel

Cancel a hosted run; artifacts it already produced are kept

Usage: `simforge runs cancel [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

### simforge runs list

List your workspace's hosted runs

Usage: `simforge runs list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` |  | At most this many items |
| `--status STATUS` |  | Only items in this status |
| `--type TYPE` |  | Only items of this type |

### simforge runs show

One hosted run: status, cost, jobs and artifacts

Usage: `simforge runs show [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

### simforge runs watch

Follow a hosted run until it succeeds, fails, is partial or is cancelled

Usage: `simforge runs watch [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

## runtime

### simforge runtime install

Download and install the closed runtime (PolyForm Noncommercial 1.0.0) after accepting its license and SimForge's account and download terms

Usage: `simforge runtime install [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--target TARGET` | default x86_64-unknown-linux-gnu | The platform to download for (a Rust target triple). Default: this machine's |
| `--version VERSION` |  |  |
| `--root ROOT` |  |  |
| `--accept-license` |  | Explicitly accept the current license and terms (agreement version and SHA) before downloading |

### simforge runtime license

Read the runtime license (PolyForm Noncommercial 1.0.0) and SimForge's account and download terms without accepting them

Usage: `simforge runtime license [OPTIONS]`

### simforge runtime status

Report the installed runtime's protocol and engine identity

Usage: `simforge runtime status [OPTIONS]`

## scenario

### simforge scenario actors

The built-in actors operations place: class, dimensions, ego and static eligibility

Usage: `simforge scenario actors [OPTIONS]`

Runs on: local runtime, or hosted with --cloud.

### simforge scenario apply add-actor

Place a new actor: a road vehicle on a semantic lane, or a pedestrian/free static actor at a scene point.

Usage: `simforge scenario apply <FILE> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--body-color BODY_COLOR` |  | Presentation body colour `#rrggbb`. |
| `--catalog-id CATALOG_ID` | required | Built-in actor (`simforge scenario actors`): vehicle.sedan, pedestrian.adult, ... |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | New actor id (never allocated implicitly). |
| `--label LABEL` |  | Display label. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--opposing` |  | Snap to the nearest genuinely opposing lane. |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--speed-kph N` |  | Initial speed; default: posted limit for road vehicles. [0..160 km/h] |
| `--static` |  | Place as a static actor (no motion, zero speed). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge scenario apply add-lane-change

Add a timed lane change for a mobile lane-bound road actor.

Usage: `simforge scenario apply <FILE> add-lane-change [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--direction DIRECTION` | required; one of left, right | Target lane side. |
| `--duration-s N` |  | Lane-change duration. [> 0 s] (default 3) |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--start-s N` | required | Clip time the change starts. [>= 0 s] |

### simforge scenario apply add-next-junction-turn

Choose the turn an actor takes at its next junction.

Usage: `simforge scenario apply <FILE> add-next-junction-turn [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--direction DIRECTION` | required; one of left, right, straight | Movement at the next junction. |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--start-s N` | required | Clip time the choice applies from. [>= 0 s] |

### simforge scenario apply duplicate-actor

Copy an actor with its presentation and own events under a new id at a new position.

Usage: `simforge scenario apply <FILE> duplicate-actor [OPTIONS] --id <ID> --new-id <NEW_ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | Source actor. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--new-id NEW_ID` | required | New actor id. |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge scenario apply move-actor

Move an actor to a lane station or scene point, keeping identity, class, static state and speed.

Usage: `simforge scenario apply <FILE> move-actor [OPTIONS] --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--heading-rad N` |  | Heading in the scene frame; default: the lane heading or the actor class default. [rad] |
| `--id ID` | required | Actor to move. |
| `--lateral-m N` |  | Lateral offset in the lane, positive to the left of travel. [m] |
| `--overlap-override` |  | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). |
| `--y N` |  | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] |
| `--lane-rsl LANE_RSL` |  | Semantic lane `road:section:lane` (with s). |
| `--s N` |  | Station along laneRsl in storage direction. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |

### simforge scenario apply remove-role

Delete an actor with dependent events, reasoning and ego handoff.

Usage: `simforge scenario apply <FILE> remove-role [OPTIONS] --id <ID> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--id ID` | required | Actor to delete. |

### simforge scenario apply set-actor-speed

Set an actor's initial speed.

Usage: `simforge scenario apply <FILE> set-actor-speed [OPTIONS] --id <ID> --speed-kph <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--id ID` | required | Actor. |
| `--speed-kph N` | required | Initial speed. [0..160 km/h] |

### simforge scenario apply set-actor-static

Make an actor static (clears its route and motion events) or mobile again.

Usage: `simforge scenario apply <FILE> set-actor-static [OPTIONS] --id <ID> --static <BOOL> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--id ID` | required | Actor. |
| `--static BOOL` | required; one of true, false | true: static; false: mobile. |

### simforge scenario apply set-clip

Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.

Usage: `simforge scenario apply <FILE> set-clip [OPTIONS] <--clip-seconds <N>|--warmup-seconds <N>> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--clip-seconds N` |  | Clip length. [3..120 s] |
| `--warmup-seconds N` |  | Warm-up before the clip. [0..30 s] |

### simforge scenario apply set-clock

Set the precise scene clock; the time of day becomes the label of the sun at the map's site on the scenario's day.

Usage: `simforge scenario apply <FILE> set-clock [OPTIONS] --minutes <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--minutes N` | required | Minutes after local midnight. [0..1439 min] |

### simforge scenario apply set-ego

Make an actor the ego vehicle.

Usage: `simforge scenario apply <FILE> set-ego [OPTIONS] --role-id <ROLE_ID> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--role-id ROLE_ID` | required | Actor to make ego. |

### simforge scenario apply set-event-timing

Retime an event's start and optional end.

Usage: `simforge scenario apply <FILE> set-event-timing [OPTIONS] --id <ID> --start-s <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--end-s N` |  | End clip time. [>= 0 s] |
| `--id ID` | required | Event. |
| `--start-s N` | required | Start clip time. [>= 0 s] |

### simforge scenario apply set-waypoint-route

Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).

Usage: `simforge scenario apply <FILE> set-waypoint-route [OPTIONS] --actor-id <ACTOR_ID> --duration-s <N> --id <ID> --point <X,Z> --start-s <N> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--duration-s N` | required | Route duration. [> 0 s] |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--point X,Z` | required; repeatable | Scene points, the actor's start first. Repeat once per item, at least 2. |
| `--start-s N` | required | Clip time the route starts. [>= 0 s] |

### simforge scenario apply set-weather

Set the scenario weather.

Usage: `simforge scenario apply <FILE> set-weather [OPTIONS] --weather <WEATHER> [-- [OPERATION]...]`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically) |
| `<operation>` | repeatable | Further operations of the same transaction, each after `--`. |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |
| `--transaction-label TEXT` |  | The transaction's undo label (default: the operations' summaries) |
| `--weather WEATHER` | required; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleet | Canonical scenario weather. |

### simforge scenario check

Full validation on the document's map (exit 2 per --strictness); --preview also runs every actor on the engine

Usage: `simforge scenario check [OPTIONS] --strictness <STRICTNESS> <FILE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document |
| `--strictness STRICTNESS` | required; one of errors, warnings | What fails the check (exit 2) |
| `--preview` |  | Also materialize and run every actor on the engine (collisions, quality, input identity) |

### simforge scenario drive

Run the editor preview's engine pass over a scenario and report how each road vehicle drove

Usage: `simforge scenario drive [OPTIONS] <FILE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document |
| `--map MAP` |  | Run on this installed map instead of the document's own |
| `--ambient AMBIENT` | one of document, off; default document | Generated traffic |
| `--strict` |  | Exit 2 when any road vehicle has a driving finding |

### simforge scenario motion

Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes)

Usage: `simforge scenario motion [OPTIONS] --actor <ID> --to <TO> <FILE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The scenario document (edited in place, atomically, as the next revision) |
| `--actor ID` | required | The actor (role id) to convert |
| `--to TO` | required; one of follow-path, behave, reset-to-recording | The motion to convert it to |
| `--recording FILE` | repeatable | A recording the document pins (plain or gzipped; log-scene/v1 reads as one). Repeatable |
| `--map MAP` |  | Use this installed map instead of the document's own |
| `--expect-version N` |  | Refuse unless the document is at this revision (`stale_version`) |
| `--expect-digest SHA256` |  | Refuse unless the document content has this digest (`stale_digest`); also accepts an edit made outside simforge |

### simforge scenario new

Create an empty scenario on an installed map (revision 0)

Usage: `simforge scenario new [OPTIONS] --map <MAP> --out <FILE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP` | required | The installed map (`simforge maps pull <map>@<version>`) |
| `--out FILE` | required | Where to write the scenario document |
| `--name NAME` | default Untitled scenario | Scenario name |
| `--clip-seconds S` | default 20 | Clip length, seconds (3 to 120) |
| `--created-at TIME` |  | Creation timestamp `YYYY-MM-DDTHH:MM:SS.mmmZ` (default: now), for reproducible documents |
| `--force` |  | Overwrite an existing file |

### simforge scenario ops list

Every authoring operation: id, command, summary, required map context

Usage: `simforge scenario ops list [OPTIONS]`

Runs on: local runtime, or hosted with --cloud.

### simforge scenario ops show

One operation: input and result schemas, flags, applicability and refusal codes

Usage: `simforge scenario ops show [OPTIONS] <OPERATION>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<operation>` | required | Operation id (`addActor`) or command (`add-actor`) |

### simforge scenario pull

Download a hosted scenario document as a local scenario JSON file

Usage: `simforge scenario pull [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `id` | required | The hosted scenario document id |
| `--out OUT` |  | Output file. Default: <ID>.scenario.json |
| `--host HOST` |  | SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai |
| `--force` |  | Overwrite an existing output file |
| `--help` |  | Print help |

## scenarios

### simforge scenarios copy

Copy a hosted scenario to edit: its current draft as a new scenario; renders and runs stay

Usage: `simforge scenarios copy [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The hosted scenario to copy |
| `--dataset DATASET_ID` |  | The dataset to copy into. Default: the scenario's own, else your default dataset |
| `--name NAME` |  | The copy's name. Default: "<name> (copy)", or "(copy 2)", ... when taken |

### simforge scenarios create

Create a hosted scenario from a recording or a template on a map

Usage: `simforge scenarios create [OPTIONS] --map <MAP> --name <NAME>`

| Argument / flag | Notes | What |
|---|---|---|
| `--log LOG` |  | A recording (`simforge.recording/v1`, or a `simforge.log-scene/v1` file), JSON or gzipped |
| `--template TEMPLATE` |  | A scenario template, instantiated at a site of the map |
| `--map MAP` | required | The map: a map version id, a map name or `name@vN` |
| `--site SITE` |  | The site to instantiate a template at; absent, its own pin or the first intent-preserving match |
| `--seed SEED` |  | `simulation.seed` of the instantiated scenario |
| `--name NAME` | required | The new scenario's name |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--lidar-topic TOPIC` |  | MCAP only: the lidar topic, when the log has several |
| `--gnss-topic TOPIC` |  | MCAP only: the GNSS topic, when the log has several |
| `--ego-dims L,W,H` | repeatable | MCAP only: the ego's box in metres, length,width,height (perceive's default otherwise) |
| `--ego-rear-axle-to-centre METRES` |  | MCAP only: how far the ego box's centre is ahead of base_link (the rear axle), metres |

### simforge scenarios list

List the hosted scenarios of your workspace

Usage: `simforge scenarios list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` |  | At most this many items |
| `--status STATUS` |  | Only items in this status |
| `--type TYPE` |  | Only items of this type |

### simforge scenarios show

One hosted scenario and its revisions

Usage: `simforge scenarios show [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The id |

## simulate

### simforge simulate

Simulate the same scenario file locally or with --cloud

Usage: `simforge simulate [OPTIONS] <TARGET> [EXTRA]...`

| Argument / flag | Notes | What |
|---|---|---|
| `<target>` | required | Scenario JSON file or materialized workspace; identical input for local and cloud |
| `<extra>` | repeatable | Runtime-specific options; forwarded without shell interpolation |
| `--out OUT` |  | Output folder; local requires it, cloud waits and downloads when it is given |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d |  |
| `--rig RIG` |  | Sensor rig JSON (`simforge rig init`). Default: the `basic-dash-camera` rig on the ego |
| `--preset PRESET` | one of training, showcase, schematic | Render preset |
| `--camera-detector FILE` |  | Local native render only: authored instantaneous HDR detector response JSON |
| `--camera-temporal FILE` |  | Local native render only: bounded exact-time HDR exposure request JSON |
| `--camera-delivery FILE` |  | Local bounded offline measurement delivery or controlled delivery-only resume |
| `--fps FPS` |  | Frame rate every camera records (2d: the video's), over the render preset's own rate; 3d takes 5 to 60 |
| `--wait` |  | Wait for a submitted cloud job to finish |
| `--download` |  | Download a succeeded cloud job into --out; implies --wait |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--revision REVISION` |  | Immutable revision for an existing hosted scenario target |
| `--replay-of RUN_ID` |  | Cloud 3d render: the drive a succeeded closed_loop run scored (its episode timeline), rendered on the target's revision that run drove |
| `--seed SEED` |  | Override the resolution's seed (the trace is then expected to differ) |
| `--map-dir DIR` |  | Use this map directory instead of the installed map found by content (map.xodr[.gz] sha256 = the manifest's map.xodrSha256) |
| `--cache-root DIR` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--trace FILE` |  | Instance mode (the positional is an instance file): also write the trace here (gzip JSON) |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded in the result; the default refuses) |

## sites

### simforge sites match

Rank the concrete sites a template's anchor matches on installed maps (exit 2 when none)

Usage: `simforge sites match [OPTIONS] <TEMPLATE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<template>` | required | The v2 template |
| `--map MAP` |  | One installed map |
| `--maps MAPS` | repeatable | Several installed maps, comma-separated, in this order |
| `--all-maps` |  | Every installed map |
| `--min-score SCORE` |  | Drop sites scoring below this |
| `--max-sites N` |  | Keep at most this many sites per map (reported as maxSitesPerMap) |
| `--rejected` |  | Also list up to 25 rejected sites per map, with why |
| `--site-spacing-m M` |  | Dense site index: corridor origins every M metres of road instead of one per (road, 200 m cell, direction) |

## skills

### simforge skills install

Copy the bundled skills into an agent's skill directory

Usage: `simforge skills install [OPTIONS] <--claude|--codex|--dir <PATH>>`

| Argument / flag | Notes | What |
|---|---|---|
| `--claude` |  | Install into ~/.claude/skills (Claude Code) |
| `--codex` |  | Install into $CODEX_HOME/skills, else ~/.codex/skills (Codex) |
| `--dir PATH` |  | Install into this directory |
| `--force` |  | Overwrite files that differ from what an earlier install wrote |

### simforge skills list

List the skills bundled with this binary

Usage: `simforge skills list [OPTIONS]`

## telemetry

### simforge telemetry show

Print the pending usage batches exactly as the runtime will send them

Usage: `simforge telemetry show [OPTIONS]`

## template

### simforge template new

Emit a minimal schema-valid v2 template skeleton (deterministic)

Usage: `simforge template new [OPTIONS]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `--out FILE` |  | Also write the template here |
| `--map MAP` |  | Pre-bind the skeleton to an installed map (`anchor.pin`, `sourceMap`) |
| `--site SITE` |  | Pin a site id too (requires --map) |

### simforge template validate

Schema + tier-1 validation; map checks against a matched site with --map (exit 2 on any error)

Usage: `simforge template validate [OPTIONS] <FILE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The v2 template |
| `--map MAP` |  | Run the map checks against the best site on this installed map |
| `--site SITE` |  | Bind this site instead of the best one (with --map) |

## timeline

### simforge timeline build

Build the render timeline for a workspace's trace (deterministic, content-keyed)

Usage: `simforge timeline build [OPTIONS] [WORKSPACE]`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<workspace>` |  | The workspace directory (an imported scenario package). Omit it and pass --trace instead |
| `--trace FILE` |  | A trace file (JSON or gzip; any released trace format) instead of a workspace |
| `--recorded-trace-sha256 SHA256` |  | The identity recorded next to the stored trace (bound to an upgraded trace; checked against a current one) |
| `--catalog-digest SHA256` |  | Actor-catalog closure digest to key the timeline by (a workspace supplies its own) |
| `--height HEIGHT` | one of auto, ground, flat; default auto | The height source |
| `--flat-z METRES` |  | Elevation of the plane for --height flat |
| `--map-dir DIR` |  | Use this map directory (map.xodr + derived/ground/ground-mesh.bin) instead of the installed map found by content |
| `--cache-root DIR` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--out FILE` |  | Write the canonical timeline here (`.gz` compresses). Default: the workspace's timeline/<sha256>.json; with --trace, nothing is written |

## transfer

### simforge transfer

Move a scenario or recording onto another map: recorded tracks warped through lane frames, behaviour re-bound by the matcher; simulated and gated, with a transfer report. Locally it needs the map's odr derivative, which `simforge maps pull` does not install yet: run it with --cloud

Usage: `simforge transfer [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <SOURCE>`

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<source>` | required | The source: a recording (simforge.recording/v1 or log-scene/v1, optionally gzipped), a v2 scenario, or a package directory holding one |
| `--map DIR\|NAME@VERSION` | required | The target map: a map directory, or name[@version] under the maps cache (semantic profile) |
| `--source-map DIR\|NAME@VERSION\|FILE.xodr` |  | The source's map (default: the map the source names): a map directory, name[@version], or a bare OpenDRIVE file for a recording |
| `--recording FILE` | repeatable | A recording the scenario's replay routes pin (repeatable) |
| `--from-root` |  | Transfer from the source's root: follow its recording's `derivedFrom` (a transfer's warped recording, a scenario's rollout of the one recording it replays) through the `--recording` files to the recording it started from, and transfer that onto the map. The source's own scenario content (its edits) is not carried; the report records the chain in `source.root` |
| `--sites SITES` | one of network, corridor, same; default network | Where recorded motion looks for sites |
| `--profile PROFILE` | one of pure, generalized, key-only; default pure | Which recorded actors transfer |
| `--crossing CROSSING` | one of any, faithful; default any | How a crosswalk crossing must land |
| `--max-try N` |  | Sites tried (transferred, gated and simulated) before giving up [default: 6 per --max-sites] |
| `--max-sites N` | default 1 | Distinct accepted sites to transfer onto (recorded motion), ranked; more than one writes each to site-<rank>/ under --out |
| `--site-cell-m M` |  | With --max-sites: one site per cell of this size (metres) and heading quadrant [default: 200]. Smaller admits near-copies of the same drive |
| `--min-path-separation-m M` |  | With --max-sites: no two placements whose egos' target paths come within this distance (metres) [default: 10] |
| `--out DIR` | required | The output directory (created; must be empty if it exists) |
| `--cache-root DIR` |  | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--allow-no-colliders` |  | Simulate without map colliders when the map publishes none (recorded; the default refuses) |
| `--budget-s SECONDS` | default 32400 | Last-resort wall-clock limit, seconds: a transfer still running then fails whole (`transfer_budget_exceeded`, nothing written). Set far above any healthy transfer (about 10x the slowest seen); what a transfer tries is bounded by --max-try and the import's rounds, never by time, so its result does not depend on the machine |
| `--mode MODE` | one of motion, semantic; default motion | How the scenario moves to the target map |
| `--experimental` |  | Allow an experimental --mode |
| `--target-control CLASS,...\|as-source` | default as-source | Semantic mode: the target approach classes accepted, comma separated (two_way_stop_minor, two_way_stop_major, all_way_stop, signal, yield_minor, yield_major, stop_line_only, uncontrolled, mixed), or `as-source`. A class other than the source's is recorded as a requested substitution |
| `--t-junction` |  | Semantic mode: also fit a four-arm source onto a T-junction whose stem is the ego's approach; the roles on the source's opposite arm are left out (recorded), and each such placement is tagged `t_junction` |
| `--policy FILE` |  |  |
| `--policy-version VERSION` |  |  |
| `--revision REVISION_ID` |  | The immutable revision of a hosted scenario SOURCE |
| `--name NAME` |  | The new scenario's name. Default: `<source title> · <target map>` |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents |
| `--wait` | one of true, false | Wait for the transfer to finish |

## usage

### simforge usage

Hosted usage and spend of the signed-in workspace

Usage: `simforge usage [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--from FROM` |  | Start of the period (ISO 8601 date or time) |
| `--to TO` |  | End of the period (ISO 8601 date or time) |

## validate

### simforge validate

Tier 1 (static) or tier 2 (one engine pass + invariant residuals) validation of an instance or template

Usage: `simforge validate [OPTIONS] <INSTANCE|TEMPLATE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<instance\|template>` | required | A v2 template or an instance (a scenario cell, a pinned scenario or a bare SimScenarioInput) |
| `--tier N` |  | 1: static checks (default); 2: one engine pass with invariant residuals |
| `--map MAP` |  | The installed map (tier-1 map checks; required for a tier-2 template) |
| `--site SITE` |  | Bind this site instead of the best one |
| `--draw N` |  | The parameter draw index (tier 2, template) |
| `--seed SEED` |  | Override the per-cell parameter seed (tier 2, template) |

## variation

### simforge variation fork

Portable template x target site -> an executable child variation with lineage

Usage: `simforge variation fork [OPTIONS] --map <MAP> --site <SITE> --out <DIR> <TEMPLATE>`

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<template>` | required | The portable v2 template |
| `--map MAP` | required | The installed target map |
| `--site SITE` | required | A site id from `simforge sites match` |
| `--seed SEED` |  | The scenario's seed identity (`simulation.seed`) |
| `--draw N` |  | The parameter draw index |
| `--out DIR` | required | The variation directory to write |

## vehicle

### simforge vehicle import

Validate a .glb here, upload it and store it as the workspace's own `workspace.<id>` (private to the workspace); the licence and attribution travel with every render

Usage: `simforge vehicle import [OPTIONS] --id <ID> --license <SPDX> --attribution <TEXT> <MODEL.GLB>`

| Argument / flag | Notes | What |
|---|---|---|
| `<model.glb>` | required | The model, a binary glTF (.glb) |
| `--id ID` | required | Its id within the workspace: scenarios bind it as `workspace.<id>` (lowercase letters, digits, `_`, `-`; at most 48) |
| `--license SPDX` | required | Its licence: an SPDX id (`CC-BY-4.0`) or `LicenseRef-<name>` with --license-text |
| `--license-text FILE` |  | The licence's text, for a `LicenseRef-*` licence |
| `--attribution TEXT` | required | The credit the licence asks for (author, title, link) |
| `--source TEXT` |  | Where the model came from (URL or text) |
| `--name TEXT` |  | Its display name. Default: the id |
| `--class CLASS` | default car | The road-vehicle class it drives as: car, van, truck or bus |
| `--dims L,W,H` |  | Its real length, width and height in metres; the model must match within 10% |

### simforge vehicle list

The vehicles a scenario can bind by catalogId: the shared catalog's and, signed in, the workspace's own (`workspace.<id>`)

Usage: `simforge vehicle list [OPTIONS]`

### simforge vehicle validate

Check a .glb against the vehicle model contract (frame, size, wheel and body nodes, triangle budget, materials, textures); exit 2 on any error

Usage: `simforge vehicle validate [OPTIONS] <MODEL.GLB>`

| Argument / flag | Notes | What |
|---|---|---|
| `<model.glb>` | required | The model, a binary glTF (.glb) |
| `--class CLASS` | default car | The road-vehicle class it will drive as: car, van, truck or bus (sets the plausible size) |
| `--dims L,W,H` |  | Its real length, width and height in metres (`4.6,1.85,1.45`); the model must match within 10% |

## whoami

### simforge whoami

The signed-in account, organization, workspace and scopes

Usage: `simforge whoami [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--host HOST` |  | SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai |

## world

### simforge world serve

Serve a persistent local realtime world and its authenticated drive/state endpoints

Usage: `simforge world serve [OPTIONS] --map <MAP> --token-file <TOKEN_FILE>`

| Argument / flag | Notes | What |
|---|---|---|
| `--map MAP` | required |  |
| `--scenario SCENARIO` |  |  |
| `--seed SEED` |  |  |
| `--pacing PACING` | one of realtime, fast, paused |  |
| `--socket SOCKET` |  |  |
| `--listen LISTEN` |  |  |
| `--token-file TOKEN_FILE` | required |  |
| `--vehicles VEHICLES` |  |  |
| `--pedestrians PEDESTRIANS` |  |  |
| `--record RECORD` |  |  |
| `--journal-dir JOURNAL_DIR` |  |  |
| `--ready-file READY_FILE` |  |  |
| `--restore RESTORE` |  |  |
| `--cache-root CACHE_ROOT` |  |  |
| `--allow-no-colliders` |  |  |
| `--allow-origin ALLOW_ORIGIN` | repeatable | Explicit browser origins allowed by the closed host (repeatable) |