// Reference
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.9.
Machine-readable: /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
0ok1command error: the command could not run2findings: the command ran and found something wrong with its input
Commands
assets
- assets pull · Pull the actor-asset closure and its ATTRIBUTION.json, verifying every blob's sha256
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
- authoring capabilities · What this credential may do on this host: operation, host-operation, feature and worker status
- authoring catalogue · The host's operation catalogue (simforge.authoring-operations/v1)
- authoring discover · One page of map discovery without the map package: locations, lanes, movements or the actor catalogue
- authoring operations · Every operation with its
scenario applyflags, result schema and the host's status for this credential - authoring spawn · Whether an actor can be placed at a lane position or scene point, optionally against a draft's actors
bench
- bench · Benchmark the renderer on this machine: the Helios Score, per-factor sub-scores, frame correctness
- bench compare · Compare two results: per-scene time deltas against the noise of both runs, and frame identity
- bench run · Run the benchmark (the default when no subcommand is given)
challenge
- challenge eval · Evaluate a driver image in the final-track simulator on scenes you downloaded (
--local) - challenge status · Your team, the submissions you have left and your registry repository
- challenge submissions · Your team's submissions, their status and scores
- challenge submit · Push a driver image to your team's repository and submit it for the next nightly batch
- challenge validate · Validate a driver image against the submission contract, in the nightly batch's sandbox
closed-loop
- 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
datasets
- datasets copy · Copy scenarios of a dataset shared with every workspace (SIMLOG-25k) into one of your datasets
- datasets copy-status · One copy: its state and counts (copied, skipped as already there, failed)
- datasets list · List your workspace's hosted datasets and the ones SimForge shares with every workspace (
shared,readOnly,owner) - datasets pull · Download a dataset, a filter of it or chosen scenarios as files (resumable; --dry-run sizes it)
- datasets show · One hosted dataset
- datasets verify · Check a pulled folder against its manifest.json and SHA256SUMS (offline)
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
- drafts freeze · Freeze the draft as an immutable revision (revisionId, revisionContentDigest) for simulate/render
- drafts save · Save the draft through the workspace store at an explicit version and digest
- drafts show · The draft's current receipt and content: version, digest, map/actor/recording pins
engine-info
- engine-info · What this binary is: package version, engine semver, commit and its own sha256 (to record with results)
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
- export · A concrete instance as ASAM OpenSCENARIO XML 1.4, XML 1.3 (esmini) or DSL 2.2, with a capability report
factory
- 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
- factory clip cancel · Cancel a Factory run or raw generation; clips already checked stay charged
- 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
- factory clip download · Download a run's delivered clips or a raw generation's files, with a manifest of signed links (sha256-checked, resumable)
- factory clip get · One Factory run or raw generation: each clip's status, verdict, prompt, waiting message, warnings and cost
- factory clip list · Your Factory runs and raw generations, newest first, with their clip counts and status
- factory clip retry · Make a run's failed, cancelled or flagged clips again, or a failed or cancelled raw generation; priced and confirmed first
- 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
- factory looks · The looks a scenario clip can be made with (an experimental look may not apply well)
- 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
feedback
- 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
import
- import log · A recording (simforge.recording/v1 or log-scene/v1) as a scenario package: scenario, recording, trace, import report
- 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
- keys create · Create an API key for this workspace; its secret is printed once
- keys list · List the workspace's API keys (never their secrets)
- keys revoke · Revoke an API key now; requests with it stop resolving immediately
locations
- locations find · Structured query: type, subtype, tags, affordances, facts, proximity
- locations get · One location by handle or id (optionally with a description paragraph)
- locations resolve · Free text -> ranked handles (exit 2 when nothing matched)
login
- login · Sign in to a SimForge host (browser approval, or --device for a URL and code)
- 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
maps
- maps list · List the hosted maps your workspace can use (signed out: the public catalogue), each with the packs
maps pullinstalls (packs: variant, version, download and installed bytes) and what is installed locally (installed:2d,3dor null) - maps pull · Download a map your signed-in account is entitled to into the local cache, sha256-verified
- maps show · One hosted map (signed out: a public one), with its packs' sizes and what is installed locally
- maps status · The maps installed in the local cache and what each is installed for (
2dor3d). Reads no network
models
- models delete · Retire one fine-tune
- models list · List this workspace's fine-tunes
- models show · Show one fine-tune
- models upload · Register, upload and finalize a safetensors fine-tune directory
open-loop
- open-loop artifacts · A download grant ({url, sha256, bytes, ...}) for one artifact of the evaluation's result
- open-loop list · List the workspace's evaluations, whichever model ran them
- open-loop result · The evaluation's result manifest: scored metrics, artifacts, model/render/source pins and compute cost
- 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
modelslists the host's open-loop models - open-loop show · One evaluation: status, cost and attempts
- open-loop watch · Follow an evaluation until it succeeds, is partial, fails or is cancelled
oracle
- 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)
- oracle serve · Serve SimForge Oracle on a local HTTP endpoint (POST /v1/oracle, GET /healthz) with this machine's sign-in; runs until stopped
package
- package import · Verify, then unpack into a local workspace
- package inspect · Print a package's manifest, producer and members without unpacking it
- package verify · Verify the manifest and every member digest; exit 2 on any mismatch
preview
- preview clip · A short clip of a scenario from --at for --seconds (MP4), locally or with --cloud
- preview frame · One still frame of a scenario at --at seconds (PNG), locally or with --cloud
recording
- 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
- recording from-trace · Save a simulation's trace (a rollout) as a simforge.recording/v1 recording
- recording inspect · Read a recording through the contract: its digest, map, size and lineage
- 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
results
- results download · Download a hosted run's artifacts, sha256-checked
rig
- rig capabilities · Print the generated native camera declaration; support tiers do not imply device qualification
- rig consumer-schema · Print the v2 consumer acquisition sidecar schema; timestamps are scheduled render instants
- rig consumer-video-schema · Print the legacy v1 consumer video sidecar schema, which has no acquisition timestamps
- rig effective-config · Resolve camera identity and required features without executing a renderer
- 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/v1file - rig reported-schema · Print the reported-only calibration JSON Schema; hash integrity is checked by the consumer parser
- rig schema · Print the Platform-generated render-rig/v1 JSON Schema; cross-field checks also run in validate
- 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 · Check a
simforge.render-rig/v1file as a render reads it; the installed runtime plans a camera lens (cameraModel). Exit 2 with the finding
runs
- runs cancel · Cancel a hosted run; artifacts it already produced are kept
- runs list · List your workspace's hosted runs, newest first, one summary row each
- runs show · One hosted run: status, cost, jobs and artifacts
- runs watch · Follow a hosted run until it succeeds, fails, is partial or is cancelled
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 · Read the runtime license (PolyForm Noncommercial 1.0.0) and SimForge's account and download terms without accepting them
- runtime status · Report the installed runtime's protocol and engine identity;
--availablealso lists whatruntime installwould download, with sizes
scenario
- scenario actors · The built-in actors operations place: class, dimensions, ego and static eligibility
- 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 · 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 · Add a timed lane change for a mobile lane-bound road actor.
- scenario apply add-next-junction-turn · Choose the turn an actor takes at its next junction.
- 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 · 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 · Copy an actor with its presentation and own events under a new id at a new position.
- 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 · Delete an actor with dependent events, reasoning and ego handoff.
- scenario apply set-actor-speed · Set an actor's initial speed.
- scenario apply set-actor-static · Make an actor static (clears its route and motion events) or mobile again.
- scenario apply set-clip · Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.
- 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 · Make an actor the ego vehicle.
- scenario apply set-event-timing · Retime an event's start and optional end.
- 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 · Set the scenario weather.
- 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 · Run the editor preview's engine pass over a scenario and report how each road vehicle drove
- scenario motion · Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes)
- scenario new · Create an empty scenario on an installed map (revision 0)
- scenario ops list · Every authoring operation: id, command, summary, required map context
- scenario ops show · One operation: input and result schemas, flags, applicability and refusal codes
- scenario pull · Download a hosted scenario document as a local scenario JSON file
scenarios
- scenarios copy · Copy a hosted scenario to edit: its current draft as a new scenario; renders and runs stay
- scenarios create · Create a hosted scenario from a recording or a template on a map
- scenarios list · List the hosted scenarios of your workspace
- scenarios show · One hosted scenario and its revisions
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 · List the skills bundled with this binary
telemetry
- telemetry show · Print the pending usage batches exactly as the runtime will send them
timeline
- timeline build · Build the render timeline for a workspace's trace (deterministic, content-keyed)
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 pulldoes not install yet: run it with --cloud
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 · The vehicles a scenario can bind by catalogId: the shared catalog's and, signed in, the workspace's own (
workspace.<id>) - 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
wheel
- 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
whoami
- whoami · The account, workspace and scopes acting here: the signed-in login, or SIMFORGE_API_KEY when it is set
world
- world serve · Serve a persistent local realtime world and its authenticated drive/state endpoints