> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# simforge scenario

> Reference for simforge scenario: usage, arguments and flags, generated from the CLI.

Generated from the CLI's own help (CLI 0.2.0-rc.5). Global flags and exit codes are on the [command reference](/cli).

## scenario actors

The built-in actors operations place: class, dimensions, ego and static eligibility

```sh theme={null}
simforge scenario actors [OPTIONS]
```

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

```sh theme={null}
simforge scenario apply <FILE> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>|--movement-rsl <MOVEMENT_RSL>> [-- [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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--before-m N` | | With movementRsl: distance before the junction (default 40). \[1..500 m] |
| `--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` | | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. \[>= 0 m] |
| `--x N` | | Scene-frame x (east). \[m] |
| `--z N` | | Scene-frame z (minus north). \[m] |
| `--movement-rsl MOVEMENT_RSL` | | A junction movement's connecting lane (a junction\_movement location's anchor.road.rsl): place the actor beforeM up its approach and turn it through that movement. |

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

```sh theme={null}
simforge scenario apply <FILE> add-encounter [OPTIONS] --id <ID> --kind <KIND> [-- [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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--at-s N` | | Clip time of the moment: lead-brake brake start (default 3), cut-in lane-change start (3), crossing time on the target's lane (4), reversing start (1), pull-out start (2). \[>= 0 s] |
| `--catalog-id CATALOG_ID` | | Built-in actor; default vehicle.sedan (box truck for reversing, pedestrian.adult for crossing). |
| `--decel-mps2 N` | | lead-brake deceleration (default 5.5, a hard stop that stays within comfort checks). \[0.5..12 m/s²] |
| `--gap-m N` | | Centre-to-centre distance ahead of the target: at the start (lead-brake 20, slow-lead 30, stopped 25, reversing 25, pull-out 30, u-turn 25) or when the cut-in starts (7). \[0..500 m] |
| `--id ID` | required | New actor id. |
| `--kind KIND` | required; one of lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turn | lead-brake: ahead in the target's lane, brakes to a stop at atS. slow-lead: ahead, slower. stopped: standing ahead in the lane. cut-in: from the lane on the target's side, into its lane from atS, starting gapM in front. crossing: a pedestrian on the target's path at atS (or at x,z), ttcS before the target. oncoming / cross-traffic: a car on the opposite / a crossing approach of a junction ahead crosses its path ttcS before it (the first junction whose movement enters within 30° of straight against / square to the target's heading, else the nearest to it). reversing: standing ahead, reverses toward the target from atS. pull-out: parked at the side edge of the target's lane gapM ahead, pulls into the lane at atS. u-turn: ahead in the target's lane gapM ahead, makes a U-turn at the first place it can (a mapped U-turn movement, else a path through a junction or across a road wide enough). |
| `--side SIDE` | one of left, right | cut-in: the target's side the car comes from (required). crossing: the side the pedestrian starts on (default right). pull-out: the lane edge the car is parked at (default right). |
| `--speed-kph N` | | The new actor's speed: lead-brake the target's, slow-lead half of it, cut-in 10 faster, crossing walk 4.5, oncoming/cross-traffic the posted limit, reversing 6, pull-out 20, u-turn the target's within 15-30. \[0..160 km/h] |
| `--target TARGET` | | The actor the encounter is with: a moving road vehicle on a lane. (default "ego") |
| `--ttc-s N` | | crossing, oncoming, cross-traffic: the target's time to the conflict point when the new actor is on it (crossing default 2, junctions 1.5; negative: after the target). \[-10..30 s] |
| `--turn TURN` | one of left, right, straight | oncoming / cross-traffic: the new car's movement through the junction (default straight). |
| `--x N` | | crossing: a scene point on the target's path where the pedestrian crosses (a crosswalk), with z; replaces atS. \[m] |
| `--z N` | | crossing: the point's scene z (minus north). \[m] |

## scenario apply add-lane-change

Add a timed lane change for a mobile lane-bound road actor.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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] |

## scenario apply add-next-junction-turn

Choose the turn an actor takes at its next junction.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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] |

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

```sh theme={null}
simforge scenario apply <FILE> add-speed-change [OPTIONS] --actor-id <ACTOR_ID> --id <ID> --start-s <N> --target-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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--actor-id ACTOR_ID` | required | Actor. |
| `--end-s N` | | Clip time the event ends. \[>= 0 s] |
| `--id ID` | required | New event id. |
| `--rate-mps2 N` | | Acceleration or deceleration (default 4, at most the class limit: a car brakes at up to 8, speeds up at up to 3). \[0.1..20 m/s²] |
| `--start-s N` | required | Clip time the change starts. \[>= 0 s] |
| `--target-kph N` | required | Speed to reach; 0 brakes to a stop. \[0..160 km/h] |

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

```sh theme={null}
simforge scenario apply <FILE> add-u-turn [OPTIONS] --actor-id <ACTOR_ID> --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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--actor-id ACTOR_ID` | required | A moving road vehicle on a lane. |
| `--id ID` | required | New event id. |
| `--movement-rsl MOVEMENT_RSL` | | A U-turn movement's connecting lane on the actor's route (authoring discover --kind movements, turnRelation UTurnLeft/UTurnRight); default: the first place it can turn. |

## scenario apply duplicate-actor

Copy an actor with its presentation and own events under a new id at a new position.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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` | | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. \[>= 0 m] |
| `--x N` | | Scene-frame x (east). \[m] |
| `--z N` | | Scene-frame z (minus north). \[m] |

## scenario apply move-actor

Move an actor to a lane station or scene point, keeping identity, class, static state and speed.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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` | | Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. \[>= 0 m] |
| `--x N` | | Scene-frame x (east). \[m] |
| `--z N` | | Scene-frame z (minus north). \[m] |

## scenario apply remove-role

Delete an actor with dependent events, reasoning and ego handoff.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--id ID` | required | Actor to delete. |

## scenario apply set-actor-speed

Set an actor's initial speed.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--id ID` | required | Actor. |
| `--speed-kph N` | required | Initial speed. \[0..160 km/h] |

## scenario apply set-actor-static

Make an actor static (clears its route and motion events) or mobile again.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--id ID` | required | Actor. |
| `--static BOOL` | required; one of true, false | true: static; false: mobile. |

## scenario apply set-clip

Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--clip-seconds N` | | Clip length. \[3..120 s] |
| `--warmup-seconds N` | | Warm-up before the clip. \[0..30 s] |

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

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--minutes N` | required | Minutes after local midnight. \[0..1439 min] |

## scenario apply set-ego

Make an actor the ego vehicle.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--role-id ROLE_ID` | required | Actor to make ego. |

## scenario apply set-event-timing

Retime an event's start and optional end.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--end-s N` | | End clip time. \[>= 0 s] |
| `--id ID` | required | Event. |
| `--start-s N` | required | Start clip time. \[>= 0 s] |

## scenario apply set-waypoint-route

Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--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 `X,Z` in metres (x east, z minus north; the height follows the map ground), the actor's current position first. One `--point X,Z` per item (comma-separated numbers), at least 2. |
| `--start-s N` | required | Clip time the route starts. \[>= 0 s] |

## scenario apply set-weather

Set the scenario weather.

```sh theme={null}
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, at most 256 characters (default: the operation ids, e.g. `addActor×2, setEgo`) |
| `--weather WEATHER` | required; one of clear, cloudy, overcast, light\_rain, heavy\_rain, wet\_road, fog\_light, fog\_dense, snow, sleet | Canonical 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

```sh theme={null}
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) |

## scenario drive

Run the editor preview's engine pass over a scenario and report how each road vehicle drove

```sh theme={null}
simforge scenario drive [OPTIONS] <FILE>
```

Runs on: local runtime.

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

## scenario motion

Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes)

```sh theme={null}
simforge scenario motion [OPTIONS] --actor <ID> --to <TO> <FILE>
```

Runs on: local runtime.

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

## scenario new

Create an empty scenario on an installed map (revision 0)

```sh theme={null}
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 |
| `--dataset DATASET_ID` | | The writable dataset the hosted draft goes in; absent, the credential's default dataset (named in the receipt) |

## scenario ops list

Every authoring operation: id, command, summary, required map context

```sh theme={null}
simforge scenario ops list [OPTIONS]
```

## scenario ops show

One operation: input and result schemas, flags, applicability and refusal codes

```sh theme={null}
simforge scenario ops show [OPTIONS] <OPERATION>
```

| Argument / flag | Notes | What |
| - | - | - |
| `<operation>` | required | Operation id (`addActor`) or command (`add-actor`) |

## scenario pull

Download a hosted scenario document as a local scenario JSON file

```sh theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.