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 | Pull the actor-asset closure and its ATTRIBUTION.json, verifying every blob’s sha256 |
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 | 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 apply flags, 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 | 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 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 | Run a hosted closed-loop evaluation of a scripted or trajectory policy on a scenario revision |
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 | 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 | 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 | What this binary is: package version, engine semver, commit and its own sha256 (to record with results) |
env serve | Serve reset/step/observe episodes over a local socket or named pipe |
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 | A concrete instance as ASAM OpenSCENARIO XML 1.4, XML 1.3 (esmini) or DSL 2.2, with a capability report |
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 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 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 | 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 |
logout | Sign out of a host: revoke this machine’s session and delete its stored tokens |
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 | 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 (2d or 3d). Reads no network |
mcp | Expose this command surface as MCP tools over stdio |
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 succeeded cloud scenario render with a driving model the host offers for open loop: —model names one, else the host’s default model runs (requires —cloud, —max-cost and —idempotency-key, also with —dry-run). The help’s models lists 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 |
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 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 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 |
render | Render the same scenario file locally or with —cloud |
results download | Download a hosted run’s artifacts, sha256-checked |
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/v1 file |
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/v1 file as a render reads it; the installed runtime plans a camera lens (cameraModel). Exit 2 with the finding |
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 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; --available also lists what runtime install would download, with sizes |
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 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 |
simulate | Simulate the same scenario file locally or with —cloud |
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 show | Print the pending usage batches exactly as the runtime will send them |
timeline build | Build the render timeline for a workspace’s trace (deterministic, content-keyed) |
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 | Hosted usage and spend of the signed-in workspace |
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 |
whoami | The account, workspace and scopes acting here: the signed-in login, or SIMFORGE_API_KEY when it is set |
world serve | Serve a persistent local realtime world and its authenticated drive/state endpoints |