Docs menu

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

View as Markdown

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

FlagNotesWhat
--prettyIndent the JSON result for humans (the same document, never a different one)
--jsonExplicit machine-readable JSON output (also the default)
--cloudExecute locally by default; submit the same input as an authenticated cloud job
--workspace cloud_workspaceenv SIMFORGE_WORKSPACE_IDWith --cloud: the workspace you expect the login to act in; a different one is refused (workspace_mismatch)
--idempotency-key IDEMPOTENCY_KEYWith --cloud: a key that makes resending a lost submission safe (the host answers with the original run and charges once)
--dry-runWith --cloud: price the job (costEstimateCents) and start nothing
--api-url API_URLHosted API base URL for API-key use. Default: SIMFORGE_API_URL, then the signed-in host's /api/v1
--map-version MAP_VERSIONExact hosted map version for a scenario file. Default: the installed release's, else the one hosted version carrying the file's OpenDRIVE digest
--helpPrint machine-readable command help.

Exit codes

  • 0 ok
  • 1 command error: the command could not run
  • 2 findings: 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 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
  • 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)
env
  • env serve · Serve reset/step/observe episodes over a local socket or named pipe
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
logout
  • logout · Sign out of a host: revoke this machine's session and delete its stored tokens
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 · 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
  • mcp · Expose this command surface as MCP tools over stdio
models
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 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
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
render
  • render · Render the same scenario file locally or with --cloud
results
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/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
  • 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; --available also lists what runtime install would 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
simulate
  • simulate · Simulate the same scenario file locally or with --cloud
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 pull does not install yet: run it with --cloud
usage
  • usage · Hosted usage and spend of the signed-in workspace
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