// Command reference
simforge scenario
Generated from the CLI's own help (CLI 0.2.0-rc.5). Global flags and exit codes are on the reference index.
simforge scenario actors
The built-in actors operations place: class, dimensions, ego and static eligibility
simforge scenario actors [OPTIONS]
Runs on: local runtime, or hosted with --cloud
simforge 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.
simforge scenario apply <FILE> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --body-color BODY_COLOR | Presentation body colour #rrggbb. | |
| --catalog-id CATALOG_ID | required | Built-in actor (simforge scenario actors): vehicle.sedan, pedestrian.adult, ... |
| --heading-rad N | Heading in the scene frame; default: the lane heading or the actor class default. [rad] | |
| --id ID | required | New actor id (never allocated implicitly). |
| --label LABEL | Display label. | |
| --lateral-m N | Lateral offset in the lane, positive to the left of travel. [m] | |
| --opposing | Snap to the nearest genuinely opposing lane. | |
| --overlap-override | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). | |
| --speed-kph N | Initial speed; default: posted limit for road vehicles. [0..160 km/h] | |
| --static | Place as a static actor (no motion, zero speed). | |
| --y N | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] | |
| --lane-rsl LANE_RSL | Semantic lane road:section:lane (with s). | |
| --s N | Station along laneRsl in storage direction. [>= 0 m] | |
| --x N | Scene-frame x (east). [m] | |
| --z N | Scene-frame z (minus north). [m] |
simforge scenario apply add-lane-change
Add a timed lane change for a mobile lane-bound road actor.
simforge scenario apply <FILE> add-lane-change [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --actor-id ACTOR_ID | required | Actor. |
| --direction DIRECTION | required; one of left, right | Target lane side. |
| --duration-s N | Lane-change duration. [> 0 s] (default 3) | |
| --end-s N | Clip time the event ends. [>= 0 s] | |
| --id ID | required | New event id. |
| --start-s N | required | Clip time the change starts. [>= 0 s] |
simforge scenario apply add-next-junction-turn
Choose the turn an actor takes at its next junction.
simforge scenario apply <FILE> add-next-junction-turn [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --actor-id ACTOR_ID | required | Actor. |
| --direction DIRECTION | required; one of left, right, straight | Movement at the next junction. |
| --end-s N | Clip time the event ends. [>= 0 s] | |
| --id ID | required | New event id. |
| --start-s N | required | Clip time the choice applies from. [>= 0 s] |
simforge scenario apply duplicate-actor
Copy an actor with its presentation and own events under a new id at a new position.
simforge scenario apply <FILE> duplicate-actor [OPTIONS] --id <ID> --new-id <NEW_ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --heading-rad N | Heading in the scene frame; default: the lane heading or the actor class default. [rad] | |
| --id ID | required | Source actor. |
| --lateral-m N | Lateral offset in the lane, positive to the left of travel. [m] | |
| --new-id NEW_ID | required | New actor id. |
| --overlap-override | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). | |
| --y N | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] | |
| --lane-rsl LANE_RSL | Semantic lane road:section:lane (with s). | |
| --s N | Station along laneRsl in storage direction. [>= 0 m] | |
| --x N | Scene-frame x (east). [m] | |
| --z N | Scene-frame z (minus north). [m] |
simforge scenario apply move-actor
Move an actor to a lane station or scene point, keeping identity, class, static state and speed.
simforge scenario apply <FILE> move-actor [OPTIONS] --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --heading-rad N | Heading in the scene frame; default: the lane heading or the actor class default. [rad] | |
| --id ID | required | Actor to move. |
| --lateral-m N | Lateral offset in the lane, positive to the left of travel. [m] | |
| --overlap-override | Accept overlap with another actor (free/static actors only; refused for moving road vehicles). | |
| --y N | Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m] | |
| --lane-rsl LANE_RSL | Semantic lane road:section:lane (with s). | |
| --s N | Station along laneRsl in storage direction. [>= 0 m] | |
| --x N | Scene-frame x (east). [m] | |
| --z N | Scene-frame z (minus north). [m] |
simforge scenario apply remove-role
Delete an actor with dependent events, reasoning and ego handoff.
simforge scenario apply <FILE> remove-role [OPTIONS] --id <ID> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --id ID | required | Actor to delete. |
simforge scenario apply set-actor-speed
Set an actor's initial speed.
simforge scenario apply <FILE> set-actor-speed [OPTIONS] --id <ID> --speed-kph <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --id ID | required | Actor. |
| --speed-kph N | required | Initial speed. [0..160 km/h] |
simforge scenario apply set-actor-static
Make an actor static (clears its route and motion events) or mobile again.
simforge scenario apply <FILE> set-actor-static [OPTIONS] --id <ID> --static <BOOL> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --id ID | required | Actor. |
| --static BOOL | required; one of true, false | true: static; false: mobile. |
simforge scenario apply set-clip
Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.
simforge scenario apply <FILE> set-clip [OPTIONS] <--clip-seconds <N>|--warmup-seconds <N>> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --clip-seconds N | Clip length. [3..120 s] | |
| --warmup-seconds N | Warm-up before the clip. [0..30 s] |
simforge 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.
simforge scenario apply <FILE> set-clock [OPTIONS] --minutes <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --minutes N | required | Minutes after local midnight. [0..1439 min] |
simforge scenario apply set-ego
Make an actor the ego vehicle.
simforge scenario apply <FILE> set-ego [OPTIONS] --role-id <ROLE_ID> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --role-id ROLE_ID | required | Actor to make ego. |
simforge scenario apply set-event-timing
Retime an event's start and optional end.
simforge scenario apply <FILE> set-event-timing [OPTIONS] --id <ID> --start-s <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --end-s N | End clip time. [>= 0 s] | |
| --id ID | required | Event. |
| --start-s N | required | Start clip time. [>= 0 s] |
simforge scenario apply set-waypoint-route
Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).
simforge scenario apply <FILE> set-waypoint-route [OPTIONS] --actor-id <ACTOR_ID> --duration-s <N> --id <ID> --point <X,Z> --start-s <N> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --actor-id ACTOR_ID | required | Actor. |
| --duration-s N | required | Route duration. [> 0 s] |
| --end-s N | Clip time the event ends. [>= 0 s] | |
| --id ID | required | New event id. |
| --point X,Z | required; repeatable | Scene points, the actor's start first. Repeat once per item, at least 2. |
| --start-s N | required | Clip time the route starts. [>= 0 s] |
simforge scenario apply set-weather
Set the scenario weather.
simforge scenario apply <FILE> set-weather [OPTIONS] --weather <WEATHER> [-- [OPERATION]...]
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically) |
| <operation> | repeatable | Further operations of the same transaction, each after --. |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge | |
| --transaction-label TEXT | The transaction's undo label (default: the operations' summaries) | |
| --weather WEATHER | required; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleet | Canonical scenario weather. |
simforge scenario check
Full validation on the document's map (exit 2 per --strictness); --preview also runs every actor on the engine
simforge scenario check [OPTIONS] --strictness <STRICTNESS> <FILE>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document |
| --strictness STRICTNESS | required; one of errors, warnings | What fails the check (exit 2) |
| --preview | Also materialize and run every actor on the engine (collisions, quality, input identity) |
simforge scenario drive
Run the editor preview's engine pass over a scenario and report how each road vehicle drove
simforge scenario drive [OPTIONS] <FILE>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document |
| --map MAP | Run on this installed map instead of the document's own | |
| --ambient AMBIENT | one of document, off; default document | Generated traffic |
| --strict | Exit 2 when any road vehicle has a driving finding |
simforge scenario motion
Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes)
simforge scenario motion [OPTIONS] --actor <ID> --to <TO> <FILE>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file> | required | The scenario document (edited in place, atomically, as the next revision) |
| --actor ID | required | The actor (role id) to convert |
| --to TO | required; one of follow-path, behave, reset-to-recording | The motion to convert it to |
| --recording FILE | repeatable | A recording the document pins (plain or gzipped; log-scene/v1 reads as one). Repeatable |
| --map MAP | Use this installed map instead of the document's own | |
| --expect-version N | Refuse unless the document is at this revision (stale_version) | |
| --expect-digest SHA256 | Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge |
simforge scenario new
Create an empty scenario on an installed map (revision 0)
simforge scenario new [OPTIONS] --map <MAP> --out <FILE>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| --map MAP | required | The installed map (simforge maps pull <map>@<version>) |
| --out FILE | required | Where to write the scenario document |
| --name NAME | default Untitled scenario | Scenario name |
| --clip-seconds S | default 20 | Clip length, seconds (3 to 120) |
| --created-at TIME | Creation timestamp YYYY-MM-DDTHH:MM:SS.mmmZ (default: now), for reproducible documents | |
| --force | Overwrite an existing file |
simforge scenario ops list
Every authoring operation: id, command, summary, required map context
simforge scenario ops list [OPTIONS]
Runs on: local runtime, or hosted with --cloud
simforge scenario ops show
One operation: input and result schemas, flags, applicability and refusal codes
simforge scenario ops show [OPTIONS] <OPERATION>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <operation> | required | Operation id (addActor) or command (add-actor) |
simforge scenario pull
Download a hosted scenario document as a local scenario JSON file
simforge scenario pull [OPTIONS] <ID>
| Argument / flag | Notes | What |
|---|---|---|
| id | required | The hosted scenario document id |
| --out OUT | Output file. Default: <ID>.scenario.json | |
| --host HOST | SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai | |
| --force | Overwrite an existing output file | |
| --help | Print help |