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

View as Markdown

Machine-readable: /docs/cli.json is the same document (simforge.cli-surface/v1). stdout: one JSON document (indented with --pretty); stderr: {code, path?, reason, detail?} 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

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

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 · Bounded map discovery without the map package: locations, lanes, movements or the actor catalogue
authoring operations · Every operation with its drafts 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

batch

batch · Sites x draws matrix of a template: instantiate -> simulate -> evaluate per cell, resumable

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 pack actors · Cut the pack's actor closure (only its scenes' catalog entries and models, licences carried) from the SDK's closure
bench pack record · Record the reference (timings, frame hashes, sample frames) into a pack directory on this machine
bench pack seal · Seal a pack directory as a content-addressed closure (writes the closure document and prints its pin)
bench run · Run the benchmark (the default when no subcommand is given)

catalog

catalog batch · Resumable catalog materialisation + simulation with an attempt ledger
catalog create · Reserve exactly 100 deterministic scenario identities per selected installed map (mechanisms no map can host are reported as coverage, exit 0)
catalog verify · Reject catalog identity, cardinality, provenance or evidence gaps (exit 2); uncovered mechanisms are reported as coverage unless --require-full-coverage

cell

cell migrate · Convert a scenario-instance envelope (an archived instance.json) into a cell, one way
cell refresh · Compile a cell's scenario again and rewrite its cell.json and input.json cache

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

cli

cli install · Download and install the staff local CLI with default-feature commands

closed-loop

closed-loop · Run a hosted closed-loop evaluation of a scripted or trajectory policy on a scenario revision

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 the hosted datasets your workspace can read
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: GPU adapter, ffmpeg, cache roots, disk, registry reachability

drafts

drafts apply add-actor · Place a new actor: a road vehicle on a semantic lane, or a pedestrian/free static actor at a scene point.
drafts apply add-lane-change · Add a timed lane change for a mobile lane-bound road actor.
drafts apply add-next-junction-turn · Choose the turn an actor takes at its next junction.
drafts apply duplicate-actor · Copy an actor with its presentation and own events under a new id at a new position.
drafts apply move-actor · Move an actor to a lane station or scene point, keeping identity, class, static state and speed.
drafts apply remove-role · Delete an actor with dependent events, reasoning and ego handoff.
drafts apply set-actor-speed · Set an actor's initial speed.
drafts apply set-actor-static · Make an actor static (clears its route and motion events) or mobile again.
drafts apply set-clip · Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.
drafts 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.
drafts apply set-ego · Make an actor the ego vehicle.
drafts apply set-event-timing · Retime an event's start and optional end.
drafts apply set-waypoint-route · Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).
drafts apply set-weather · Set the scenario weather.
drafts create · Create a workspace draft on an exact map version; prints its receipt (documentId, draftVersion, contentDigest, mapPin)
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
drafts validate · Validate every actor of the draft, optionally with the authoritative preview; exit 2 on findings

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

evidence

evidence verify · Check that a trace is the run of an instance (exit 2 on any mismatch)

export

export · A concrete instance as ASAM OpenSCENARIO XML 1.4, XML 1.3 (esmini) or DSL 2.2, with a capability report

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

instantiate

instantiate · Template x site x draw -> one scenario pinned to them

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)

log

log import · Scaffold and compile a simforge.recording/v1 (or log-scene/v1) recording into a simulated, renderable workspace
log import-many · Run many log import jobs in one process (each map's world loaded once); per job the same workspace and result

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
maps pull · Download a map your signed-in account is entitled to into the local cache, sha256-verified
maps show · One hosted map and its versions

mcp

mcp · Expose this command surface as MCP tools over stdio

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
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 the pinned Alpamayo 1.5 model (requires --cloud, --max-cost and --idempotency-key, also with --dry-run)
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

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

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

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 a pedestrian/free static actor at a scene point.
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 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
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

sites

sites match · Rank the concrete sites a template's anchor matches on installed maps (exit 2 when none)

skills

skills install · Copy the bundled skills into an agent's skill directory
skills list · List the skills bundled with this binary

telemetry

telemetry show · Print the pending usage batches exactly as the runtime will send them

template

template new · Emit a minimal schema-valid v2 template skeleton (deterministic)
template validate · Schema + tier-1 validation; map checks against a matched site with --map (exit 2 on any error)

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

validate

validate · Tier 1 (static) or tier 2 (one engine pass + invariant residuals) validation of an instance or template

variation

variation fork · Portable template x target site -> an executable child variation with lineage

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

whoami

whoami · The signed-in account, organization, workspace and scopes

world

world serve · Serve a persistent local realtime world and its authenticated drive/state endpoints