> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every simforge command, argument and flag, generated from the CLI's own -⁠-help -⁠-json, so it always matches the binary it documents.

CLI 0.2.0-rc.5. Machine-readable: [/docs/cli.json](https://simforge.ai/docs/cli.json) is the same document (`simforge.cli-surface/v1`). 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 |

## Commands

| Command | What |
| - | - |
| [`assets pull`](/cli/assets#assets-pull) | Pull the actor-asset closure and its ATTRIBUTION.json, verifying every blob's sha256 |
| [`auth status`](/cli/auth#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 |
| [`authoring capabilities`](/cli/authoring#authoring-capabilities) | What this credential may do on this host: operation, host-operation, feature and worker status |
| [`authoring catalogue`](/cli/authoring#authoring-catalogue) | The host's operation catalogue (simforge.authoring-operations/v1) |
| [`authoring discover`](/cli/authoring#authoring-discover) | One page of map discovery without the map package: locations, lanes, movements or the actor catalogue |
| [`authoring operations`](/cli/authoring#authoring-operations) | Every operation with its `scenario apply` flags, result schema and the host's status for this credential |
| [`authoring spawn`](/cli/authoring#authoring-spawn) | Whether an actor can be placed at a lane position or scene point, optionally against a draft's actors |
| [`bench`](/cli/bench#bench) | Benchmark the renderer on this machine: the Helios Score, per-factor sub-scores, frame correctness |
| [`bench compare`](/cli/bench#bench-compare) | Compare two results: per-scene time deltas against the noise of both runs, and frame identity |
| [`bench run`](/cli/bench#bench-run) | Run the benchmark (the default when no subcommand is given) |
| [`challenge eval`](/cli/challenge#challenge-eval) | Evaluate a driver image in the final-track simulator on scenes you downloaded (`--local`) |
| [`challenge status`](/cli/challenge#challenge-status) | Your team, the submissions you have left and your registry repository |
| [`challenge submissions`](/cli/challenge#challenge-submissions) | Your team's submissions, their status and scores |
| [`challenge submit`](/cli/challenge#challenge-submit) | Push a driver image to your team's repository and submit it for the next nightly batch |
| [`challenge validate`](/cli/challenge#challenge-validate) | Validate a driver image against the submission contract, in the nightly batch's sandbox |
| [`closed-loop`](/cli/closed-loop#closed-loop) | Run a hosted closed-loop evaluation of a scripted or trajectory policy on a scenario revision |
| [`datasets copy`](/cli/datasets#datasets-copy) | Copy scenarios of a dataset shared with every workspace (SIMLOG-25k) into one of your datasets |
| [`datasets copy-status`](/cli/datasets#datasets-copy-status) | One copy: its state and counts (copied, skipped as already there, failed) |
| [`datasets list`](/cli/datasets#datasets-list) | List your workspace's hosted datasets and the ones SimForge shares with every workspace (`shared`, `readOnly`, `owner`) |
| [`datasets pull`](/cli/datasets#datasets-pull) | Download a dataset, a filter of it or chosen scenarios as files (resumable; --dry-run sizes it) |
| [`datasets show`](/cli/datasets#datasets-show) | One hosted dataset |
| [`datasets verify`](/cli/datasets#datasets-verify) | Check a pulled folder against its manifest.json and SHA256SUMS (offline) |
| [`doctor`](/cli/doctor#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) |
| [`drafts freeze`](/cli/drafts#drafts-freeze) | Freeze the draft as an immutable revision (revisionId, revisionContentDigest) for simulate/render |
| [`drafts save`](/cli/drafts#drafts-save) | Save the draft through the workspace store at an explicit version and digest |
| [`drafts show`](/cli/drafts#drafts-show) | The draft's current receipt and content: version, digest, map/actor/recording pins |
| [`engine-info`](/cli/engine-info#engine-info) | What this binary is: package version, engine semver, commit and its own sha256 (to record with results) |
| [`env serve`](/cli/env#env-serve) | Serve reset/step/observe episodes over a local socket or named pipe |
| [`evaluate`](/cli/evaluate#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 |
| [`export`](/cli/export#export) | A concrete instance as ASAM OpenSCENARIO XML 1.4, XML 1.3 (esmini) or DSL 2.2, with a capability report |
| [`import log`](/cli/import#import-log) | A recording (simforge.recording/v1 or log-scene/v1) as a scenario package: scenario, recording, trace, import report |
| [`import openscenario`](/cli/import#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 |
| [`keys create`](/cli/keys#keys-create) | Create an API key for this workspace; its secret is printed once |
| [`keys list`](/cli/keys#keys-list) | List the workspace's API keys (never their secrets) |
| [`keys revoke`](/cli/keys#keys-revoke) | Revoke an API key now; requests with it stop resolving immediately |
| [`locations find`](/cli/locations#locations-find) | Structured query: type, subtype, tags, affordances, facts, proximity |
| [`locations get`](/cli/locations#locations-get) | One location by handle or id (optionally with a description paragraph) |
| [`locations resolve`](/cli/locations#locations-resolve) | Free text -> ranked handles (exit 2 when nothing matched) |
| [`login`](/cli/login#login) | Sign in to a SimForge host (browser approval, or --device for a URL and code) |
| [`login poll`](/cli/login#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 |
| [`logout`](/cli/logout#logout) | Sign out of a host: revoke this machine's session and delete its stored tokens |
| [`maps list`](/cli/maps#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) |
| [`maps pull`](/cli/maps#maps-pull) | Download a map your signed-in account is entitled to into the local cache, sha256-verified |
| [`maps show`](/cli/maps#maps-show) | One hosted map (signed out: a public one), with its packs' sizes and what is installed locally |
| [`maps status`](/cli/maps#maps-status) | The maps installed in the local cache and what each is installed for (`2d` or `3d`). Reads no network |
| [`mcp`](/cli/mcp#mcp) | Expose this command surface as MCP tools over stdio |
| [`open-loop artifacts`](/cli/open-loop#open-loop-artifacts) | A download grant (\{url, sha256, bytes, ...}) for one artifact of the evaluation's result |
| [`open-loop list`](/cli/open-loop#open-loop-list) | List the workspace's evaluations, whichever model ran them |
| [`open-loop result`](/cli/open-loop#open-loop-result) | The evaluation's result manifest: scored metrics, artifacts, model/render/source pins and compute cost |
| [`open-loop run`](/cli/open-loop#open-loop-run) | Score a succeeded cloud scenario render 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 |
| [`open-loop show`](/cli/open-loop#open-loop-show) | One evaluation: status, cost and attempts |
| [`open-loop watch`](/cli/open-loop#open-loop-watch) | Follow an evaluation until it succeeds, is partial, fails or is cancelled |
| [`package import`](/cli/package#package-import) | Verify, then unpack into a local workspace |
| [`package inspect`](/cli/package#package-inspect) | Print a package's manifest, producer and members without unpacking it |
| [`package verify`](/cli/package#package-verify) | Verify the manifest and every member digest; exit 2 on any mismatch |
| [`preview clip`](/cli/preview#preview-clip) | A short clip of a scenario from --at for --seconds (MP4), locally or with --cloud |
| [`preview frame`](/cli/preview#preview-frame) | One still frame of a scenario at --at seconds (PNG), locally or with --cloud |
| [`recording from-trace`](/cli/recording#recording-from-trace) | Save a simulation's trace (a rollout) as a simforge.recording/v1 recording |
| [`recording inspect`](/cli/recording#recording-inspect) | Read a recording through the contract: its digest, map, size and lineage |
| [`recording scaffold`](/cli/recording#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 |
| [`render`](/cli/render#render) | Render the same scenario file locally or with --cloud |
| [`results download`](/cli/results#results-download) | Download a hosted run's artifacts, sha256-checked |
| [`rig capabilities`](/cli/rig#rig-capabilities) | Print the generated native camera declaration; support tiers do not imply device qualification |
| [`rig consumer-schema`](/cli/rig#rig-consumer-schema) | Print the v2 consumer acquisition sidecar schema; timestamps are scheduled render instants |
| [`rig consumer-video-schema`](/cli/rig#rig-consumer-video-schema) | Print the legacy v1 consumer video sidecar schema, which has no acquisition timestamps |
| [`rig effective-config`](/cli/rig#rig-effective-config) | Resolve camera identity and required features without executing a renderer |
| [`rig init`](/cli/rig#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 |
| [`rig reported-schema`](/cli/rig#rig-reported-schema) | Print the reported-only calibration JSON Schema; hash integrity is checked by the consumer parser |
| [`rig schema`](/cli/rig#rig-schema) | Print the Platform-generated render-rig/v1 JSON Schema; cross-field checks also run in validate |
| [`rig show`](/cli/rig#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 |
| [`rig validate`](/cli/rig#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 |
| [`runs cancel`](/cli/runs#runs-cancel) | Cancel a hosted run; artifacts it already produced are kept |
| [`runs list`](/cli/runs#runs-list) | List your workspace's hosted runs, newest first, one summary row each |
| [`runs show`](/cli/runs#runs-show) | One hosted run: status, cost, jobs and artifacts |
| [`runs watch`](/cli/runs#runs-watch) | Follow a hosted run until it succeeds, fails, is partial or is cancelled |
| [`runtime install`](/cli/runtime#runtime-install) | Download and install the closed runtime (PolyForm Noncommercial 1.0.0) after accepting its license and SimForge's account and download terms |
| [`runtime license`](/cli/runtime#runtime-license) | Read the runtime license (PolyForm Noncommercial 1.0.0) and SimForge's account and download terms without accepting them |
| [`runtime status`](/cli/runtime#runtime-status) | Report the installed runtime's protocol and engine identity; `--available` also lists what `runtime install` would download, with sizes |
| [`scenario actors`](/cli/scenario#scenario-actors) | The built-in actors operations place: class, dimensions, ego and static eligibility |
| [`scenario apply add-actor`](/cli/scenario#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. |
| [`scenario apply add-encounter`](/cli/scenario#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. |
| [`scenario apply add-lane-change`](/cli/scenario#scenario-apply-add-lane-change) | Add a timed lane change for a mobile lane-bound road actor. |
| [`scenario apply add-next-junction-turn`](/cli/scenario#scenario-apply-add-next-junction-turn) | Choose the turn an actor takes at its next junction. |
| [`scenario apply add-speed-change`](/cli/scenario#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. |
| [`scenario apply add-u-turn`](/cli/scenario#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. |
| [`scenario apply duplicate-actor`](/cli/scenario#scenario-apply-duplicate-actor) | Copy an actor with its presentation and own events under a new id at a new position. |
| [`scenario apply move-actor`](/cli/scenario#scenario-apply-move-actor) | Move an actor to a lane station or scene point, keeping identity, class, static state and speed. |
| [`scenario apply remove-role`](/cli/scenario#scenario-apply-remove-role) | Delete an actor with dependent events, reasoning and ego handoff. |
| [`scenario apply set-actor-speed`](/cli/scenario#scenario-apply-set-actor-speed) | Set an actor's initial speed. |
| [`scenario apply set-actor-static`](/cli/scenario#scenario-apply-set-actor-static) | Make an actor static (clears its route and motion events) or mobile again. |
| [`scenario apply set-clip`](/cli/scenario#scenario-apply-set-clip) | Set the clip length and/or warm-up; out-of-clip events are refused, never truncated. |
| [`scenario apply set-clock`](/cli/scenario#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. |
| [`scenario apply set-ego`](/cli/scenario#scenario-apply-set-ego) | Make an actor the ego vehicle. |
| [`scenario apply set-event-timing`](/cli/scenario#scenario-apply-set-event-timing) | Retime an event's start and optional end. |
| [`scenario apply set-waypoint-route`](/cli/scenario#scenario-apply-set-waypoint-route) | Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing). |
| [`scenario apply set-weather`](/cli/scenario#scenario-apply-set-weather) | Set the scenario weather. |
| [`scenario check`](/cli/scenario#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 |
| [`scenario drive`](/cli/scenario#scenario-drive) | Run the editor preview's engine pass over a scenario and report how each road vehicle drove |
| [`scenario motion`](/cli/scenario#scenario-motion) | Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes) |
| [`scenario new`](/cli/scenario#scenario-new) | Create an empty scenario on an installed map (revision 0) |
| [`scenario ops list`](/cli/scenario#scenario-ops-list) | Every authoring operation: id, command, summary, required map context |
| [`scenario ops show`](/cli/scenario#scenario-ops-show) | One operation: input and result schemas, flags, applicability and refusal codes |
| [`scenario pull`](/cli/scenario#scenario-pull) | Download a hosted scenario document as a local scenario JSON file |
| [`scenarios copy`](/cli/scenarios#scenarios-copy) | Copy a hosted scenario to edit: its current draft as a new scenario; renders and runs stay |
| [`scenarios create`](/cli/scenarios#scenarios-create) | Create a hosted scenario from a recording or a template on a map |
| [`scenarios list`](/cli/scenarios#scenarios-list) | List the hosted scenarios of your workspace |
| [`scenarios show`](/cli/scenarios#scenarios-show) | One hosted scenario and its revisions |
| [`simulate`](/cli/simulate#simulate) | Simulate the same scenario file locally or with --cloud |
| [`skills install`](/cli/skills#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 |
| [`skills list`](/cli/skills#skills-list) | List the skills bundled with this binary |
| [`telemetry show`](/cli/telemetry#telemetry-show) | Print the pending usage batches exactly as the runtime will send them |
| [`timeline build`](/cli/timeline#timeline-build) | Build the render timeline for a workspace's trace (deterministic, content-keyed) |
| [`transfer`](/cli/transfer#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`](/cli/usage#usage) | Hosted usage and spend of the signed-in workspace |
| [`vehicle import`](/cli/vehicle#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 |
| [`vehicle list`](/cli/vehicle#vehicle-list) | The vehicles a scenario can bind by catalogId: the shared catalog's and, signed in, the workspace's own (`workspace.<id>`) |
| [`vehicle validate`](/cli/vehicle#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 |
| [`whoami`](/cli/whoami#whoami) | The account, workspace and scopes acting here: the signed-in login, or SIMFORGE\_API\_KEY when it is set |
| [`world serve`](/cli/world#world-serve) | Serve a persistent local realtime world and its authenticated drive/state endpoints |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.