sootsim flow
run flows through the current sim or manage a draft from live inspect actions
sootsim flow
Use flow files when you already have them, or start a draft so inspect-driven actions can be kept one by one and exported into YAML once the path is proven. Flow playback, recording, and profiling now stay on the shared bridge runner.
terminal
Options
| flag | description |
|---|---|
--record | record a video while the flow runs |
--profile | capture perf stats while the flow runs |
--out <dir> | output bundle directory — recordings land here, and --screenshots also defaults to this directory (so one flag controls the whole demo-run bundle instead of needing both) |
--screenshots <dir> | override screenshot output directory (defaults to —out, or /tmp/sootsim-flow if neither is set) |
--screenshot-paths <mode> | screenshot path mode: dir (default — flat directory of files) or flow (per-flow subdirectory tree) |
--replace <module>=<file> | replace a Metro module with a local file for this run — useful for swapping in a fixture component (e.g. a deterministic SeedPhraseInputScreen for demo recordings). repeatable |
--slow <ms> | delay between steps for easier debugging |
--tail-wait <ms> | hold recording open after the last step so the final UI state is captured (default: smart idle up to 6000ms for —preview, fixed 2000ms for —record, 0 otherwise) |
--url <url> | load this target before running the flow |
--no-shell | capture every screenshot tenant-only (no status bar, keyboard, notification center, or other shell overlays). per-step layers: still wins over this default |
--shell-only | inverse — capture only the shell chrome overlays |
--new | open a fresh sim before running the flow |
--driver <id> | when paired with —new, launch through a specific driver from the registry (e.g. playwright); see sootsim list --drivers |
--headless | pass headless=true to the launch driver (useful with —driver playwright) |
--sim <sim> | target a specific current sim |
--electron | prefer the desktop companion for this flow run |
--output <path> | write the drafted flow when using flow end |
--validate | replay the drafted flow before clearing it |
--video | replay and record the drafted flow before clearing it |
--preview | record + upload the run as a shareable /preview/<id> link (implies —record) |
--preview-origin <url> | override the upload target for —preview (defaults to auto) |
--preview-public-origin <url> | override the public link origin for —preview (defaults to sootsim.com for prod uploads) |
--preview-open | open the resulting /preview/<id> url after upload |
Examples
terminal
Flow-Specific Behavior
flow now has two jobs:
- run an existing YAML flow against the current sim by default
- manage an ephemeral draft while you drive the app through
inspect
For draft mode, the commands are intentionally minimal:
terminal
Nothing is kept automatically. Only the last successful write action becomes the
pending candidate, and flow keep promotes that single action into the draft.
Plain flow end only exports the draft. Use --validate or --video
when the finish line needs to prove the exported YAML still replays from a clean
run. If replay fails, the draft stays active so you can keep iterating instead
of losing the good steps you already kept.
When a flow depends on a clean boot, sootsim inspect shell launch rn --clear-state
can also be kept into the draft so replay resets the app before later steps.
Existing flow files still support frontmatter like:
That lets a flow file encode which target it opens and whether the desktop companion is the preferred runtime for that flow.
When you want frame timing for a full scripted path, run the same file with
--profile. Flow playback, recording, and profiling now stay on the same bridge-backed sim/action surface as the rest of the CLI.
Why Flow Owns Playback
flow is now the one public YAML playback surface. It owns both:
- running an existing flow file through the bridge-backed sim/action layer
- managing a live draft while you prove steps through the CLI