// Command reference

simforge drafts

Generated from the CLI's own help (CLI 0.2.0-rc.5). Global flags and exit codes are on the reference index.

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply add-lane-change

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-lane-change [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply add-next-junction-turn

Choose the turn an actor takes at its next junction.

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> add-next-junction-turn [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply duplicate-actor

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> duplicate-actor [OPTIONS] --id <ID> --new-id <NEW_ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply move-actor

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> move-actor [OPTIONS] --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply remove-role

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> remove-role [OPTIONS] --id <ID> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--id ID	required	Actor to delete.

simforge drafts apply set-actor-speed

Set an actor's initial speed.

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-actor-speed [OPTIONS] --id <ID> --speed-kph <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--id ID	required	Actor.
--speed-kph N	required	Initial speed. [0..160 km/h]

simforge drafts apply set-actor-static

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-actor-static [OPTIONS] --id <ID> --static <BOOL> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--id ID	required	Actor.
--static BOOL	required; one of true, false	true: static; false: mobile.

simforge drafts apply set-clip

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-clip [OPTIONS] <--clip-seconds <N>|--warmup-seconds <N>> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--clip-seconds N		Clip length. [3..120 s]
--warmup-seconds N		Warm-up before the clip. [0..30 s]

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-clock [OPTIONS] --minutes <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--minutes N	required	Minutes after local midnight. [0..1439 min]

simforge drafts apply set-ego

Make an actor the ego vehicle.

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-ego [OPTIONS] --role-id <ROLE_ID> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--role-id ROLE_ID	required	Actor to make ego.

simforge drafts apply set-event-timing

Retime an event's start and optional end.

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-event-timing [OPTIONS] --id <ID> --start-s <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--end-s N		End clip time. [>= 0 s]
--id ID	required	Event.
--start-s N	required	Start clip time. [>= 0 s]

simforge drafts apply set-waypoint-route

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

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-waypoint-route [OPTIONS] --actor-id <ACTOR_ID> --duration-s <N> --id <ID> --point <X,Z> --start-s <N> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--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 drafts apply set-weather

Set the scenario weather.

simforge drafts apply --expected-version <N> --expected-digest <SHA256> <DRAFT_ID> set-weather [OPTIONS] --weather <WEATHER> [-- [OPERATION]...]

Argument / flag	Notes	What
<draft_id>	required
<operation>	repeatable	Further operations of the same transaction, each after `--`.
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--weather WEATHER	required; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleet	Canonical scenario weather.

simforge drafts create

Create a workspace draft on an exact map version; prints its receipt (documentId, draftVersion, contentDigest, mapPin)

simforge drafts create [OPTIONS] --map <MAP_VERSION_ID> --name <NAME>

Argument / flag	Notes	What
--map MAP_VERSION_ID	required	The map version id the draft is pinned to
--name NAME	required
--dataset DATASET_ID		The writable dataset; absent, the credential's default dataset (named in the receipt)
--clip-seconds S

simforge drafts freeze

Freeze the draft as an immutable revision (revisionId, revisionContentDigest) for simulate/render

simforge drafts freeze [OPTIONS] --expected-version <N> --expected-digest <SHA256> <DRAFT_ID>

Argument / flag	Notes	What
<draft_id>	required
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on
--name NAME		The revision's name

simforge drafts save

Save the draft through the workspace store at an explicit version and digest

simforge drafts save [OPTIONS] --expected-version <N> --expected-digest <SHA256> <DRAFT_ID>

Argument / flag	Notes	What
<draft_id>	required
--expected-version N	required	The draftVersion of the receipt this change is based on
--expected-digest SHA256	required	The contentDigest of the receipt this change is based on

simforge drafts show

The draft's current receipt and content: version, digest, map/actor/recording pins

simforge drafts show [OPTIONS] <DRAFT_ID>

Argument / flag	Notes	What
<draft_id>	required

simforge drafts validate

Validate every actor of the draft, optionally with the authoritative preview; exit 2 on findings

simforge drafts validate [OPTIONS] <DRAFT_ID>

Argument / flag	Notes	What
<draft_id>	required
--strict		Warnings are findings too
--preview		Run the authoritative materializer/engine preview (every actor, collisions, quality issues)