# simforge command reference

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

Output: stdout: one JSON document (indented with --pretty); stderr: one simforge.error/v1 line {code, path?, reason, hint, detail?, httpStatus?, requestId?} 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; with SIMFORGE_API_KEY set, the key's account, workspace and scopes

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

One page of 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 | The exact map version to look up (`maps list` names them) |
| `--kind KIND` | required; one of locations, lanes, movements, catalogue | lanes, movements (junction connectors), locations (crosswalks, junctions, ...) or catalogue (built-in actors) |
| `--limit N` | default 20 | Records per page (1 to 100) |
| `--near X,Z` |  | Nearest first from this scene point, metres (`x` east, `z` minus north); not with --kind catalogue |
| `--within-m M` |  | Only records within this many metres of --near (> 0) |
| `--road ROAD_ID` |  | Only records on this OpenDRIVE road: its lanes, movements entering, leaving or on it, locations anchored on it; not with --kind catalogue |
| `--type TYPE` | one of junction, junction_movement, driving_corridor, bike_corridor, walking_corridor, midblock_segment, merge_zone, lane_drop, parking_lane, parking_space, parking_area, parking_access_point, driveway, loading_zone, bus_stop, crosswalk, sidewalk, curb, median, refuge_island, building_entrance, school_zone, work_zone_suitable, occlusion_zone, conflict_zone, poi_frontage, address | Only locations of this type (with --kind locations) |
| `--cursor CURSOR` |  | The previous page's `nextCursor`, with the same --map, --kind and filters |

### simforge authoring operations

Every operation with its `scenario 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 | The exact map version to place on |
| `--catalog-id ID` | required | The actor's catalog id (`authoring discover --kind catalogue`) |
| `--lane-rsl RSL` |  | A lane handle from `authoring discover --kind lanes` (with --s) |
| `--s S` |  | Metres along the lane from its start (with --lane-rsl) |
| `--x X` |  | A scene point (with --z) |
| `--z Z` |  | The scene point's z in metres (with --x) |
| `--heading-rad HEADING_RAD` |  | The heading in radians in the scene frame. Default: the lane's direction |
| `--lateral-m LATERAL_M` |  | Sideways offset from the lane centre in metres (positive left) |
| `--opposing` |  | Face against the lane's direction |
| `--static` |  | Place a parked (static) actor |
| `--draft DRAFT_ID` |  | Check overlap against this draft's actors (needs --expected-version and --expected-digest) |
| `--expected-version N` |  | The draftVersion of the receipt the check is based on (with --draft) |
| `--expected-digest SHA256` |  | The contentDigest of the receipt the check is based on (with --draft) |

## 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 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 |

## 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 | The track to submit to: `dev` (scored nightly in closed loop) or `final` (the final-track simulator, a few times a month) |

### 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`) |

## closed-loop

### simforge closed-loop

Run a hosted closed-loop evaluation of a scripted or trajectory policy on a scenario revision; launch requires an allowlisted workspace; contact SimForge. The workspace gate runs before input validation

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, 0 to 2^53-1 |
| `--wait` |  | Wait for the run to finish |
| `--download` |  | Download a succeeded run's artifacts into --out; implies --wait |
| `--out DIR` |  | Wait and download a succeeded run's artifacts here |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents; required for billable cloud jobs |
| `--ego-dynamics MODEL` |  | Ego dynamics model: `dynamic-v1` (today's behaviour) or `full-car-v1` (reserved, refused until admitted). Omitted: the run-mode default, which the result records |
| `--ego-vehicle ACTOR=CATALOG_ID` | repeatable | The vehicle for an ego actor, `ACTOR=CATALOG_ID`, repeatable. Refused `ego_vehicle_unsupported` until pack profiles are enabled |

## 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). This or --new is required, except with --dry-run |
| `--new NEW` |  | Copy into a new dataset of this name. This or --into is required, except with --dry-run |
| `--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 your workspace's hosted datasets and the ones SimForge shares with every workspace (`shared`, `readOnly`, `owner`)

Usage: `simforge datasets list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` | default 20 | At most this many items on the page |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |
| `--shared` |  | Only the datasets SimForge shares with every workspace (read-only; `datasets copy` copies their scenarios) |

### 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, generated (Factory clips); 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: sign-in, the runtime and its disk, the GPU (supported, and free now), ffmpeg, the map cache and the host's map catalogue, each with a fix. Runs without the runtime; with it, also the runtime's own checks (GPU adapter, sky plates, open files, actor assets)

Usage: `simforge doctor [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--offline` |  | Make no network request: the sign-in is read from this machine only and the map-catalogue check is skipped |

## drafts

### 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 | The draft's document id (from its receipt) |
| `--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 | The draft's document id (from its receipt) |
| `--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 | The draft's document id (from its receipt) |

## 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) |
| `--set KEY=VALUE` | repeatable | Renderer overrides, including textureMaxSize=1024\|2048\|4096\|full |
| `--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) |
| `--ego-dynamics MODEL` |  | Ego dynamics model for this run: `dynamic-v1` (the engine's own model, today's behaviour), `kinematic-bicycle` (Helios episodes only) or `full-car-v1` (reserved, refused until admitted). Outranks the scenario's `physics.egoDynamics`. Omitted: the run-mode default, which the result records |
| `--ego-vehicle ACTOR=CATALOG_ID` | repeatable | The vehicle for an ego actor, `ACTOR=CATALOG_ID`, repeatable. A vehicle pack needs pack profiles, which are not enabled yet: refused `ego_vehicle_unsupported`, never run on the class profile |
| `--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. With --cloud: test a model by letting it drive your saved scenarios: simforge evaluate --cloud --model MODEL --dataset NAME [--scenarios A,B] [--yes] [--wait]. It is priced first and starts only once you confirm the total (--yes when nothing can prompt); no TRACE is read

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) |
| `--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` | one of declared-speed-v1, pose-motion-v2 | The motion-plausibility audit to run. Default: `declared-speed-v1` |
| `--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) |
| `--model MODEL` |  | The model that drives, by name (case-insensitive) or id: one of the models the host offers now (run without it to list them). Required |
| `--dataset DATASET` |  | Your dataset of saved scenarios, by name (case-insensitive) or id. Required |
| `--scenarios SCENARIOS` | repeatable | Only these scenarios of the dataset, by name or id (comma-separated). Default: all of them |
| `--param NAME=VALUE` | repeatable | One of the model's parameters, as NAME=VALUE (repeatable): the options' `params` of the model, typed as listed (e.g. --param seed=7). Absent ones take their defaults |
| `--seed SEED` |  | Simulation seed for every scenario, 0 to 2^53-1. Default: 0 |
| `--yes` | one of true, false | Start at the quoted price without asking; required when no one can answer the prompt |
| `--wait` | one of true, false | Follow the run until it finishes |

## 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) |

## factory

### simforge factory batch

Submit every row of a JSON or YAML file as its own run, priced and confirmed once; running the same file again submits nothing new

Usage: `simforge factory batch [OPTIONS] <FILE>`

| Argument / flag | Notes | What |
|---|---|---|
| `<file>` | required | The rows: a JSON or YAML list (or an object with `rows`), each a scenario clip run or a raw generation |
| `--yes` |  | Start without asking (the total is still shown); needed when nothing can prompt |
| `--wait` |  | Wait until every row's clips are done |

### simforge factory clip cancel

Cancel a Factory run or raw generation; clips already checked stay charged

Usage: `simforge factory clip cancel [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The run id (`run_...`) of a Factory run or a raw generation |

### simforge factory clip create

Make clips of scenarios (--scenario or --dataset, with --look or --prompt), or one raw generation from your own control videos (--raw); priced and confirmed first

Usage: `simforge factory clip create [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--scenario ID` | repeatable | A scenario to make clips of (repeatable) |
| `--dataset ID` |  | Every scenario of this dataset of yours |
| `--look ID` | repeatable | A look from `simforge factory looks` (repeatable). Exactly one of --look and --prompt |
| `--prompt TEXT` |  | Your own conditions in place of a look, sent as written; with --raw, the request's overall prompt |
| `--camera-prompt CAMERA=TEXT` | repeatable | One camera's whole prompt, as CAMERA=TEXT (repeatable). A raw generation needs one for every camera |
| `--camera CAMERA` | repeatable | A camera to generate (repeatable): any of the 4-camera rig for scenario clips (default all four), or with --raw each camera you give a control video, in your order |
| `--seed N` | repeatable | The generator's seed (repeatable for scenario clips: a clip per seed; one with --raw). Default: derived from the request, so the same request makes the same clip |
| `--seeds-per-look N` |  | Clips per scenario and look, each on its own seed (default 1). Not with --seed |
| `--mode MODE` | one of positions, simulator | positions: the generator sees the layout and the prompts; simulator: also each camera's first frame, so the clip keeps its lighting |
| `--steps N` |  | Denoising steps (fixed at 4 by the model) |
| `--guidance SCALE` |  | Guidance scale (fixed at 1 by the model) |
| `--frames N` |  | Frames per camera (a scenario clip is fixed at 601 generated, 600 kept: 20 s at 30 fps; with --raw, default the server's own) |
| `--fps FPS` |  | Frame rate (a scenario clip is fixed at 30 fps) |
| `--resolution BUCKET` |  | The generator's resolution bucket (fixed at 480 by the model) |
| `--aspect W,H` |  | The output's aspect bucket, as W,H (16,9 is 832x480; a scenario clip is fixed at 16,9; with --raw, default the bucket closest to the first control video) |
| `--condition-video-as-image BOOL` | one of true, false | Whether a vision image conditions as one image (fixed at true by the model) |
| `--negative-prompt TEXT` |  | A negative prompt (the model takes none) |
| `--model MODEL` |  | The model variant (one is deployed: `simforge factory params` names it) |
| `--raw` |  | One raw generation from your own control videos: no scenario, no labels, no check, charged whatever it shows |
| `--control CAMERA=FILE` | repeatable | With --raw: a camera's control (layout) video, as CAMERA=FILE.mp4 (repeatable, one per camera) |
| `--vision CAMERA=FILE` | repeatable | With --raw in simulator mode: a camera's first frame, as CAMERA=FILE.png or .jpg (repeatable, one per camera) |
| `--from-request FILE` |  | With --raw: a request.json used with a local Sim-Auto server (or one a generation delivered), sent as it is; its files are read beside it |
| `--max-cost-cents CENTS` |  | The most this may charge, in cents. Default: its quote |
| `--yes` |  | Start without asking (the quote is still shown); needed when nothing can prompt |
| `--wait` |  | Wait until every clip is done, as `simforge factory clip wait` |

### simforge factory clip download

Download a run's delivered clips or a raw generation's files, with a manifest of signed links (sha256-checked, resumable)

Usage: `simforge factory clip download [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The run id (`run_...`) of a Factory run or a raw generation |
| `--out OUT` | default . | The folder to download into: the files go under OUT/<id>/. Default: the current folder |
| `--links-only` |  | Write only OUT/<id>/manifest.json, the signed link, sha256 and size of every file, and download nothing |

### simforge factory clip get

One Factory run or raw generation: each clip's status, verdict, prompt, waiting message, warnings and cost

Usage: `simforge factory clip get [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The run id (`run_...`) of a Factory run or a raw generation |

### simforge factory clip list

Your Factory runs and raw generations, newest first, with their clip counts and status

Usage: `simforge factory clip list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` | default 20 | At most this many, newest first |

### simforge factory clip retry

Make a run's failed, cancelled or flagged clips again, or a failed or cancelled raw generation; priced and confirmed first

Usage: `simforge factory clip retry [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The run id (`run_...`) of a Factory run or a raw generation |
| `--flagged` |  | Retry the run's flagged clips, on new seeds |
| `--failed` |  | Retry the run's failed clips, on their own seeds |
| `--cancelled` |  | Retry the run's cancelled clips, on their own seeds |
| `--max-cost-cents CENTS` |  | The most the retry may charge, in cents. Default: its quote |
| `--yes` |  | Start without asking (the quote is still shown); needed when nothing can prompt |

### simforge factory clip wait

Wait until every clip of a run (or a raw generation) is done, showing what each waits for; exits non-zero when any failed

Usage: `simforge factory clip wait [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | The run id (`run_...`) of a Factory run or a raw generation |

### simforge factory looks

The looks a scenario clip can be made with (an experimental look may not apply well)

Usage: `simforge factory looks [OPTIONS]`

### simforge factory params

Every generator parameter: what a scenario clip and a raw generation may set, what is fixed and why, and what one raw generation costs

Usage: `simforge factory params [OPTIONS]`

## feedback

### simforge feedback

Send SimForge a bug report, idea or question, signed in or not: with the last command's failure and doctor's checks attached on request; --dry-run prints exactly what would be sent

Usage: `simforge feedback [OPTIONS] [MESSAGE]`

| Argument / flag | Notes | What |
|---|---|---|
| `<message>` |  | What you tried and what happened (the command, its error code, what you expected). Without it, a terminal asks for one |
| `--kind KIND` | one of bug, idea, question; default bug | What this is |
| `--attach-last-error` |  | Attach the last command's failure on this machine: its command and option names, error code and reason, exit code, map and request id. Default: on when the previous command failed in the last 24 h |
| `--no-attach-last-error` |  | Attach no command failure, even when the previous command failed |
| `--include-doctor` |  | Attach `simforge doctor`'s checks (each check's id, status, summary and fix; never its detail) |
| `--email EMAIL` |  | Signed out: an email SimForge may answer at (optional; a terminal asks). Signed in, SimForge answers the account |

## 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) |
| `--feasibility-report FILE` |  | Also write the opt-in ego feasibility report (simforge.ego-feasibility/v1) to this file: the logged ego track against its class's dynamic-v1 envelope. Never changes the trace or the workspace |
| `--tracked-replay FILE` |  | Opt in to a tracked replay of the ego: instead of placing it on the log, drive its dynamic-v1 plant along the logged path (the engine's timed-path tracker) and write the tracking report (simforge.ego-tracking/v1) to this file. Changes the trace; other actors still replay exactly. Recorded in the package notes |
| `--name NAME` |  | The scenario's name. Default: the file's name |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents |
| `--wait` | one of true, false | Wait for the import to finish and print its scenario |
| `--download` | one of true, false | Download a finished import's scenario document, import report and Event Timeline into --out; implies --wait |
| `--stage` | one of true, false | Upload the log and price its import, starting nothing (the host prices an import from the uploaded log). --dry-run uploads nothing |
| `--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, or hosted with --cloud.

| Argument / flag | Notes | What |
|---|---|---|
| `<file.xosc>` | required | The OpenSCENARIO 1.x XML file; its catalogs and OpenDRIVE are read beside it. With --cloud: The OpenSCENARIO 1.x file (its OpenDRIVE and catalogs are bundled from the paths it names), or a ready .zip bundle |
| `--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) |
| `--map NAME@VERSION\|auto` | default auto | The map: a map version id, a name, `name@vN`, or `auto` (the map whose OpenDRIVE the file names) |
| `--name NAME` |  | The scenario's name. Default: the file's name |
| `--xosc-path PATH` |  | The `.xosc` inside a .zip bundle that holds several |
| `--max-cost CENTS` |  | Explicit maximum cloud cost in cents |
| `--wait` | one of true, false | Wait for the import to finish and print its scenario |
| `--download` | one of true, false | Download a finished import's scenario document, import report and Event Timeline into --out; implies --wait |
| `--stage` | one of true, false | Upload the bundle and price its import, starting nothing: the host resolves the map first, so this shows `osc_map_unknown` for free. --dry-run uploads nothing |

## 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 records (default 25, cap 200) |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |
| `--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) |

## login

### simforge login

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

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

| 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 |
| `--no-wait` |  | With --device: print the URL and code and exit at once instead of waiting; after the approval, `simforge login poll` (from any shell, even after this one closed) stores the login |

### simforge login poll

Finish a device sign-in started by `login --device --no-wait` (or one whose terminal closed while it waited): wait for the approval, then store the login

Usage: `simforge login poll [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 |
| `--no-wait` |  | With --device: print the URL and code and exit at once instead of waiting; after the approval, `simforge login poll` (from any shell, even after this one closed) stores the login |
| `--host HOST` |  | SimForge host the sign-in was started on. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai |
| `--timeout SECONDS` | default 600 | Seconds to wait for the approval; the code stays valid until it expires, so a timeout (`login_pending`) can be polled again |

## 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 (signed out: the public catalogue), each with the packs `maps pull` installs (`packs`: variant, version, download and installed bytes) and what is installed locally (`installed`: `2d`, `3d` or null)

Usage: `simforge maps list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` | default 20 | At most this many items on the page |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |

### 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 |
| `--for LEVEL` | one of 2d, 3d | What to install the map for: `2d` (authoring, simulation and 2D renders: a few MB) or `3d` (also local 3D renders; the whole map, GB). Default: `3d` when this map is already installed for 3D, else `2d`. Cloud renders (`--cloud`) need neither |
| `--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 (signed out: a public one), with its packs' sizes and what is installed locally

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

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

### simforge maps status

The maps installed in the local cache and what each is installed for (`2d` or `3d`). Reads no network

Usage: `simforge maps status [OPTIONS] [MAP]`

| Argument / flag | Notes | What |
|---|---|---|
| `<map>` |  | Only this map |
| `--cache-root CACHE_ROOT` |  | Map cache directory. Default: the SimForge maps cache |

## 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) |
| `--profile PROFILE` | one of core, full; default core | Which tools to list: `core` (the authoring, render and run loop, plus the `simforge` tool that runs any command) or `full` (every command as its own tool) |
| `--only COMMAND` | repeatable | Expose only the commands under these command paths, from the full surface (repeatable, e.g. `--only render --only "scenario apply"`) |
| `--all` |  | Also expose the internal (staff and research) commands that `help` lists only with `--all`; an `--only` naming one exposes it too |

## models

### simforge models delete

Retire one fine-tune

Usage: `simforge models delete [OPTIONS] <ID>`

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | Fine-tune model version id (`mv_...`) |

### simforge models list

List this workspace's fine-tunes

Usage: `simforge models list [OPTIONS]`

### simforge models show

Show one fine-tune

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

| Argument / flag | Notes | What |
|---|---|---|
| `<id>` | required | Fine-tune model version id (`mv_...`) |

### simforge models upload

Register, upload and finalize a safetensors fine-tune directory

Usage: `simforge models upload [OPTIONS] --family <FAMILY> --name <NAME> <DIRECTORY>`

| Argument / flag | Notes | What |
|---|---|---|
| `<directory>` | required | Directory containing the family's declared safetensors files |
| `--family FAMILY` | required | Base model family (for example `qwen-drive-1.0`) |
| `--name NAME` | required | Workspace-unique fine-tune name |
| `--param PARAMS` | repeatable | Override a parameter (`name=value`), repeatable |
| `--wait` |  | Wait for qualification to finish |

## 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 (`run_...`, or `cmpj_...` from before cloud runs) |
| `<artifact_id>` | required | The artifact, by its id in the result manifest |

### simforge open-loop list

List the workspace's evaluations, whichever model ran them

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

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` | default 20 | At most this many items on the page |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |
| `--status STATUS` |  | Only evaluations in these statuses (comma-separated) |
| `--model MODEL` |  | Only one model's evaluations, by name (case-insensitive) or id: a model the host lists (`GET /api/v1/evaluation-options`), or a model version of your own by id. Default: every model's |

### 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 (`run_...`, or `cmpj_...` from before cloud runs) |

### simforge open-loop run

Score a scenario's authored episode with a driving model the host offers for open loop, named by --model (requires --cloud, --model, --max-cost and --idempotency-key, also with --dry-run). The help's `models` lists the host's open-loop models

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

| Argument / flag | Notes | What |
|---|---|---|
| `<scenario_id>` | required | The scenario to evaluate |
| `--model MODEL` |  | The model that predicts, by name (case-insensitive) or id: one of the models the host offers for open loop now (`GET /api/v1/evaluation-options`, each model's `loops.openLoop`; run without it to list them). Required |
| `--seed SEED` |  | Model sampling seed (the model's `seed` parameter). Default: the model's |
| `--samples N` |  | Trajectory samples drawn by the model (its `numTrajSamples` parameter). Default: the model's; a model with a fixed count accepts only that |
| `--param NAME=VALUE` | repeatable | One of the model's parameters, as NAME=VALUE (repeatable): the options' `params` of the model, typed as listed (e.g. --param temperature=0.8). Absent ones take their defaults |
| `--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 (`run_...`, or `cmpj_...` from before cloud runs) |

### 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 (`run_...`, or `cmpj_...` from before cloud runs) |

## oracle

### simforge oracle ask

Ask SimForge Oracle a question about driving videos: uploads them, waits and prints the answer and its cost ($0.05 per second of video, at least $0.50 per clip)

Usage: `simforge oracle ask [OPTIONS] --prompt <TEXT> <VIDEO>...`

| Argument / flag | Notes | What |
|---|---|---|
| `<video>` | required; repeatable | The driving videos to ask about, in order (MP4, QuickTime or WebM, at most 2 GiB each; 1 to 10) |
| `--prompt TEXT` | required | The question about the driving scene (1 to 4,000 characters) |
| `--context TEXT` |  | Facts the answer may use, such as ego speed, route intent or camera names (at most 16,000 characters) |
| `--preset PRESET` | one of driving-qa, causal-chain, hazards, scene-describe | The kind of answer (default driving-qa) |
| `--thinking THINKING` | one of low, medium, high | How long SimForge Oracle reasons before it answers (default medium) |
| `--detail DETAIL` | one of standard, high | How much of each frame SimForge Oracle sees: high reads finer detail (default standard) |
| `--fps N` |  | Frames per second read from every video, 0.1 to 5 (default 1) |
| `--start S` |  | Where every video's clip starts, in seconds (default 0) |
| `--end S` |  | Where every video's clip ends, in seconds (default the video's end) |
| `--schema FILE` |  | A JSON schema file (a JSON object, at most 16 KB): each answer is also returned as JSON of that shape |
| `--samples N` |  | Independent answers to the same question, 1 to 4 (default 1); each is charged |
| `--max-output-tokens N` |  | The longest answer, in tokens, 256 to 16,384 (default 8,192) |
| `--max-cost CENTS` |  | The most this question may charge, in cents: samples x each clip's max(50, 5 per second) |
| `--out DIR` |  | Save the answer's result.json in this folder |
| `--no-wait` |  | Print the submitted run and return; follow it with `simforge runs watch` |

### simforge oracle serve

Serve SimForge Oracle on a local HTTP endpoint (POST /v1/oracle, GET /healthz) with this machine's sign-in; runs until stopped

Usage: `simforge oracle serve [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--bind BIND` | default 127.0.0.1 | The address to listen on; 127.0.0.1 is this machine only |
| `--port PORT` | default 8787 | The port to listen on |
| `--max-cost CENTS` |  | The most one question may charge, in cents, when its request sets no maxCostCents |
| `--concurrency CONCURRENCY` | default 4 | Questions answered at once; later ones wait their turn (1 to 32) |

## 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 |
| `--installed-map-only` |  | Install no map: the package's map must already be in the cache (`--cache-root`), else the import fails with `package_closure_unavailable`. Nothing is pulled into the cache or installed from the package's own blobs; the actor closure and sky plates are still fetched. A cloud worker's job passes it: the worker's parent process is the only writer of its maps cache |
| `--registry URL` |  | Map registry to resolve the package's map from (https:// or file://). Default: SIMFORGE_MAPS_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 | Runtime-specific options; forwarded without shell interpolation |
| `--out OUT` | required | Output file (PNG for a frame, MP4 for a clip) |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d | `2d` (top-down map video on the CPU), `schematic` (the flat OpenDRIVE view, GPU) or `3d` (photoreal camera sensors, GPU) |
| `--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 |
| `--stage` |  | With --cloud: save a scenario file to the workspace as an immutable revision (free) and price the preview on it; starts nothing. --dry-run saves nothing |
| `--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 | Runtime-specific options; forwarded without shell interpolation |
| `--out OUT` | required | Output file (PNG for a frame, MP4 for a clip) |
| `--mode MODE` | one of 2d, schematic, 3d; default 2d | `2d` (top-down map video on the CPU), `schematic` (the flat OpenDRIVE view, GPU) or `3d` (photoreal camera sensors, GPU) |
| `--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 |
| `--stage` |  | With --cloud: save a scenario file to the workspace as an immutable revision (free) and price the preview on it; starts nothing. --dry-run saves nothing |
| `--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 feasibility

Opt-in feasibility report for a recording's ego: the inverse single-track model against the vehicle's dynamic-v1 envelope. Reads only; the recording replays exactly either way

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

Runs on: local runtime.

| Argument / flag | Notes | What |
|---|---|---|
| `<recording>` | required | The recording (simforge.recording/v1 or log-scene/v1, optionally gzipped) |
| `--out FILE` |  | Also write the report here (it is always printed) |

### 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 | `2d` (top-down map video on the CPU), `schematic` (the flat OpenDRIVE view, GPU) or `3d` (photoreal camera sensors, GPU) |
| `--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 |
| `--stage` |  | With --cloud: save a scenario file to the workspace as an immutable revision (free) and price the run on it; starts nothing. --dry-run saves nothing |
| `--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 |
| `--ego-dynamics MODEL` |  | Ego dynamics model for this run: `dynamic-v1` (the engine's own model, today's behaviour), `kinematic-bicycle` (Helios episodes only) or `full-car-v1` (reserved, refused until admitted). Outranks the scenario's `physics.egoDynamics`. Omitted: the run-mode default, which the result records |
| `--ego-vehicle ACTOR=CATALOG_ID` | repeatable | The vehicle for an ego actor, `ACTOR=CATALOG_ID`, repeatable. A vehicle pack needs pack profiles, which are not enabled yet: refused `ego_vehicle_unsupported`, never run on the class profile |
| `--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 |
| `--visual-dynamics` |  | Derive each logged four-wheeler's body pitch and roll from its recorded track (log replays only; any other input is refused `ego_visual_dynamics_input_invalid`). The timeline key changes; without the flag the timeline is unchanged |
| `--vd-rate-hz HZ` |  | With --visual-dynamics: the rate the log's poses were recorded at, Hz. Default: 50. A rate the poses contradict (a resampled lower-rate log declared higher) is refused, and so is a pose-only log below 10 Hz |
| `--passes PASSES` | one of rgb, hdr, id, depth, semantic; default rgb; repeatable | Camera passes, comma-separated. The shared render output contract defaults to RGB only |
| `--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 |
| `--simulate-only` |  | Simulate only (native): the same timeline, scene state, rig schedule and job as a render, each tick applied and observed in a device-free world (`observed-frames.jsonl`, the parity gate, `results.json`), with no frame drawn, no video and no GPU |
| `--first-frame` |  | Render the first frame only (native): tick 0 of the same job, every camera as its RGB PNG (no video). Every camera must capture tick 0 |
| `--attitude ATTITUDE` | one of on, off; default on | Native: `on` (default) lowers each four-wheeler's body pitch and roll and the road attitude into the frames (cameras and sensors on a body mount tilt with it); `off` lowers yaw-only rotations, the rigid twin of the same render. Recorded as `lowering.attitude` |
| `--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 |
| `--progress` |  | Write `render.progress` events to stderr (the step, and frames done of the total while drawing) |
| `--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 | The `simforge.render-rig/v1` file |
| `--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 or as calibrated on one vehicle, 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, physicalai-av-7cam, drone-inspection-wide, drone-inspection-wide-zoom, drone-mapping-nadir, drone-fpv-forward, qwen-drive-3cam | 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; a calibrated rig takes only its own class |
| `--profile PROFILE` | one of training, showcase | The render profile whose capture (size and frame rate) every camera of a fitted rig records, showcase when omitted; a calibrated rig records its native capture and refuses one |
| `--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, newest first, one summary row each

Usage: `simforge runs list [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--limit LIMIT` | default 20 | At most this many items on the page |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |
| `--status STATUS` | one of queued, running, succeeded, partial, failed, cancelled, active | Only runs in this status; `active` is queued or running |
| `--type TYPE` |  | Only runs of this type (`render`, `closed_loop`, `scenario_from_log`, ...) |
| `--mine` |  | Only runs you submitted: none of your teammates' and none published from other workspaces |
| `--full` |  | Full run objects (input, jobs, billing, result) instead of one summary row per run; `runs show ID` reads one |

### 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 host target | The platform to download for (a Rust target triple). Default: this machine's |
| `--version VERSION` |  | The exact runtime release to install. Default: the one this CLI pins |
| `--root ROOT` |  | Where to install the runtime. Default: SIMFORGE_RUNTIME_ROOT, then the root of the last install, then <data home>/simforge/runtime. The root is recorded in the CLI config, so `runtime status`, `doctor` and every local command find it; the download and its unpacking stay inside it |
| `--for LEVEL` | one of 2d, 3d | What to install the runtime for: `2d` (authoring, simulation and 2D renders: the runtime without the 3D actor models and sky, about 1/30 of the download) or `3d` (also local 3D renders). Default: what is installed, else `2d` |
| `--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; `--available` also lists what `runtime install` would download, with sizes

Usage: `simforge runtime status [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--available` |  | Also list the runtime releases this account can install for this machine (`2d`, `3d`), each with its version, download and installed size; works before any runtime is installed |

## scenario

### simforge scenario actors

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

Usage: `simforge scenario actors [OPTIONS]`

### simforge scenario apply add-actor

Place a new actor: a road vehicle on a semantic lane or before a junction movement, 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>|--movement-rsl <MOVEMENT_RSL>> [-- [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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--before-m N` |  | With movementRsl: distance before the junction (default 40). [1..500 m] |
| `--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` |  | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. [>= 0 m] |
| `--x N` |  | Scene-frame x (east). [m] |
| `--z N` |  | Scene-frame z (minus north). [m] |
| `--movement-rsl MOVEMENT_RSL` |  | A junction movement's connecting lane (a junction_movement location's anchor.road.rsl): place the actor beforeM up its approach and turn it through that movement. |

### simforge scenario apply add-encounter

Add an actor that meets the target (the ego by default) the way --kind says, placed and timed from the road graph: lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turn.

Usage: `simforge scenario apply <FILE> add-encounter [OPTIONS] --id <ID> --kind <KIND> [-- [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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--at-s N` |  | Clip time of the moment: lead-brake brake start (default 3), cut-in lane-change start (3), crossing time on the target's lane (4), reversing start (1), pull-out start (2). [>= 0 s] |
| `--catalog-id CATALOG_ID` |  | Built-in actor; default vehicle.sedan (box truck for reversing, pedestrian.adult for crossing). |
| `--decel-mps2 N` |  | lead-brake deceleration (default 5.5, a hard stop that stays within comfort checks). [0.5..12 m/s²] |
| `--gap-m N` |  | Centre-to-centre distance ahead of the target: at the start (lead-brake 20, slow-lead 30, stopped 25, reversing 25, pull-out 30, u-turn 25) or when the cut-in starts (7). [0..500 m] |
| `--id ID` | required | New actor id. |
| `--kind KIND` | required; one of lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turn | lead-brake: ahead in the target's lane, brakes to a stop at atS. slow-lead: ahead, slower. stopped: standing ahead in the lane. cut-in: from the lane on the target's side, into its lane from atS, starting gapM in front. crossing: a pedestrian on the target's path at atS (or at x,z), ttcS before the target. oncoming / cross-traffic: a car on the opposite / a crossing approach of a junction ahead crosses its path ttcS before it (the first junction whose movement enters within 30° of straight against / square to the target's heading, else the nearest to it). reversing: standing ahead, reverses toward the target from atS. pull-out: parked at the side edge of the target's lane gapM ahead, pulls into the lane at atS. u-turn: ahead in the target's lane gapM ahead, makes a U-turn at the first place it can (a mapped U-turn movement, else a path through a junction or across a road wide enough). |
| `--side SIDE` | one of left, right | cut-in: the target's side the car comes from (required). crossing: the side the pedestrian starts on (default right). pull-out: the lane edge the car is parked at (default right). |
| `--speed-kph N` |  | The new actor's speed: lead-brake the target's, slow-lead half of it, cut-in 10 faster, crossing walk 4.5, oncoming/cross-traffic the posted limit, reversing 6, pull-out 20, u-turn the target's within 15-30. [0..160 km/h] |
| `--target TARGET` |  | The actor the encounter is with: a moving road vehicle on a lane. (default "ego") |
| `--ttc-s N` |  | crossing, oncoming, cross-traffic: the target's time to the conflict point when the new actor is on it (crossing default 2, junctions 1.5; negative: after the target). [-10..30 s] |
| `--turn TURN` | one of left, right, straight | oncoming / cross-traffic: the new car's movement through the junction (default straight). |
| `--x N` |  | crossing: a scene point on the target's path where the pedestrian crosses (a crosswalk), with z; replaces atS. [m] |
| `--z N` |  | crossing: the point's scene 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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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 add-speed-change

Change an actor's speed from a clip time: brake to a stop, slow down, speed up or start moving.

Usage: `simforge scenario apply <FILE> add-speed-change [OPTIONS] --actor-id <ACTOR_ID> --id <ID> --start-s <N> --target-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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--end-s N` |  | Clip time the event ends. [>= 0 s] |
| `--id ID` | required | New event id. |
| `--rate-mps2 N` |  | Acceleration or deceleration (default 4, at most the class limit: a car brakes at up to 8, speeds up at up to 3). [0.1..20 m/s²] |
| `--start-s N` | required | Clip time the change starts. [>= 0 s] |
| `--target-kph N` | required | Speed to reach; 0 brakes to a stop. [0..160 km/h] |

### simforge scenario apply add-u-turn

Make an actor (the ego too) turn back the way it came at the first place ahead on its route where it can: a junction's mapped U-turn movement, else a path drawn through a junction or across a road wide enough for its turning circle.

Usage: `simforge scenario apply <FILE> add-u-turn [OPTIONS] --actor-id <ACTOR_ID> --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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--actor-id ACTOR_ID` | required | A moving road vehicle on a lane. |
| `--id ID` | required | New event id. |
| `--movement-rsl MOVEMENT_RSL` |  | A U-turn movement's connecting lane on the actor's route (authoring discover --kind movements, turnRelation UTurnLeft/UTurnRight); default: the first place it can turn. |

### 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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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` |  | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. [>= 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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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` |  | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. [>= 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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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 `X,Z` in metres (x east, z minus north; the height follows the map ground), the actor's current position first. One `--point X,Z` per item (comma-separated numbers), 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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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 and flags an actor the ego never sees or meets. The installed map's own findings (mapDiagnostics) never fail it

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.

| 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.

| 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 |
| `--dataset DATASET_ID` |  | The writable dataset the hosted draft goes in; absent, the credential's default dataset (named in the receipt) |

### simforge scenario ops list

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

Usage: `simforge scenario ops list [OPTIONS]`

### simforge scenario ops show

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

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

| 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 |
| `--stage` |  | With --log: upload the recording and price its import, starting nothing. --dry-run uploads nothing |
| `--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` | default 20 | At most this many items on the page |
| `--cursor CURSOR` |  | The next page: the `nextCursor` of the page before it |

### 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 | `2d` (top-down map video on the CPU), `schematic` (the flat OpenDRIVE view, GPU) or `3d` (photoreal camera sensors, GPU) |
| `--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 |
| `--stage` |  | With --cloud: save a scenario file to the workspace as an immutable revision (free) and price the run on it; starts nothing. --dry-run saves nothing |
| `--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 |
| `--ego-dynamics MODEL` |  | Ego dynamics model for this run: `dynamic-v1` (the engine's own model, today's behaviour), `kinematic-bicycle` (Helios episodes only) or `full-car-v1` (reserved, refused until admitted). Outranks the scenario's `physics.egoDynamics`. Omitted: the run-mode default, which the result records |
| `--ego-vehicle ACTOR=CATALOG_ID` | repeatable | The vehicle for an ego actor, `ACTOR=CATALOG_ID`, repeatable. A vehicle pack needs pack profiles, which are not enabled yet: refused `ego_vehicle_unsupported`, never run on the class profile |
| `--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) |

## skills

### simforge skills install

Copy the bundled skills into an agent's skill directory; agentHost says how to register simforge mcp with that host and which instructions to add

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]`

## 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 |
| `--visual-dynamics` |  | Derive each logged four-wheeler's body pitch and roll from its recorded track (log replays only; any other input is refused `ego_visual_dynamics_input_invalid`). The timeline key changes; without the flag the timeline is unchanged |
| `--vd-rate-hz HZ` |  | With --visual-dynamics: the rate the log's poses were recorded at, Hz. Default: 50. A rate the poses contradict (a resampled lower-rate log declared higher) is refused, and so is a pose-only log below 10 Hz |

## 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` |  | A transfer policy JSON file to transfer with, instead of a registered version |
| `--policy-version VERSION` |  | A registered transfer policy version (sdk/contracts/transfer-policies.json, e.g. `transfer-v2`). Default: the registry's active 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 |
| `--download` | one of true, false | Download a finished transfer's new scenario, report and receipt into --out; implies --wait |
| `--stage` | one of true, false | Save a SOURCE file to the workspace as an immutable revision (free) and price the transfer on it; starts nothing. --dry-run saves nothing |

## 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) |

## 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% |

## wheel

### simforge wheel serve

Hold a Logitech wheel's centring spring for Drive pages on this computer (ws://127.0.0.1:8767/wheel) until Ctrl+C

Usage: `simforge wheel serve [OPTIONS]`

| Argument / flag | Notes | What |
|---|---|---|
| `--listen ADDR` | default 127.0.0.1:8767 | Address to listen on: 127.0.0.1 or [::1], with a port; port 0 picks a free one, which the ready document prints |
| `--token-file FILE` |  | The token a page must present. Default: wheel-token in the CLI config directory, created owner-only on first use; a file named here must already exist with mode 0600. Delete it and restart to revoke every page |
| `--allow-origin ORIGIN` | repeatable | Also allow pages from this exact origin, scheme://host[:port] (repeatable). Always allowed: https://simforge.ai, the configured development host, http://127.0.0.1:5199, http://localhost:5199 |

## whoami

### simforge whoami

The account, workspace and scopes acting here: the signed-in login, or SIMFORGE_API_KEY when it is set

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 | The installed map to serve (its name or directory) |
| `--scenario SCENARIO` |  | A scenario file whose actors start in the world |
| `--seed SEED` |  | The seed for traffic population and every seeded draw |
| `--pacing PACING` | one of realtime, fast, paused | `realtime` advances at 50 Hz wall clock, `fast` unpaced, `paused` only on world.time.advanceTicks |
| `--socket SOCKET` |  | The Unix socket (named pipe on Windows) to serve runtime protocol v1 on |
| `--listen LISTEN` |  | A loopback HOST:PORT for the authenticated /commands and /truth WebSocket endpoints |
| `--token-file TOKEN_FILE` | required | A mode-0600 file of 32-512 bytes holding the host token clients authenticate with |
| `--vehicles VEHICLES` |  | How many population vehicles to keep in the world |
| `--pedestrians PEDESTRIANS` |  | How many population pedestrians to keep in the world |
| `--record RECORD` |  | Record the session as a simforge.recording/v1 file here |
| `--journal-dir JOURNAL_DIR` |  | The durable journal directory (command log segments and checkpoints) |
| `--ready-file READY_FILE` |  | Also write the readiness JSON to this file |
| `--restore RESTORE` |  | Restore a host checkpoint (`*.host-checkpoint.msgpack`) at launch |
| `--cache-root CACHE_ROOT` |  | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps |
| `--allow-no-colliders` |  | Serve a map that ships no colliders (actors can then pass through static geometry) |
| `--allow-origin ALLOW_ORIGIN` | repeatable | Explicit browser origins allowed by the closed host (repeatable) |
