CLI Reference
CLI Reference
The sootsim CLI is the operational surface for booting shells, opening sims, driving automation, and exposing the bridge host to agents.
terminal
Commands
| command | description |
|---|---|
maestro | author, generate, and run Maestro YAML flows against sootsim |
detox | run existing Detox suites against sootsim on headless Chromium |
record | capture the live sim as webm/mp4/gif, or sample N png frames (—frames) |
film | record a flow on the flat canvas, replay it on the 3d device stage under a camera cinematic, save a clip |
storage | manage guest app storage and launch profiles |
perf | CPU, React render, and shell frame profiling |
describe | curated human-readable UI summary (default inspection tool) |
find | locate nodes by text / testID / role / type / predicate |
assert | run any read verb and convert its output into an exit code |
screenshot | capture PNGs and manage App Store screenshot assets |
get | read runtime state (tree, a11y, url, count, errors, …) |
do | drive the app (tap, type, scroll, swipe, key, reload, …) |
wait | block until the runtime reaches a known state |
shell | drive shell state and simulator chrome |
mode | toggle screenshot and 3D display modes |
device | inspect or change the live device preset for a sim |
inspect | query, describe, and drive the running sootsim instance |
network | inspect live network traffic from the running sootsim worker |
logs | inspect live console output from the running sootsim worker |
debug | drive __sootsimDebug: channels, snapshots, and inspectors |
what-happened | show recent semantic events: toasts, keyboards, screens, alerts, fetches, errors |
timeline | control the semantic event timeline (enable opt-in kinds, clear, dump) |
open | load a target into the current sim or open a new one |
list | list connected sims or available launch drivers |
use | select a connected sim |
skill | install and inspect bundled SootSim agent skills |
claim | take an exclusive lease on a sim |
agent | attached projects + local agent sessions (codex/claude) |
close | close a connected sim |
setup | bootstrap SootSim, then install the global CLI |
compat | check package compatibility |
desktop | launch or install the desktop companion |
daemon | manage the sootsim bridge as a login agent |
version | show the CLI + engine runtime versions you are running |
upgrade | update the sootsim CLI and engine runtime to the latest |
serve | run the sootsim bridge in the foreground |
runtime | manage engine runtimes under ~/.sootsim/runtimes/ |
auth | inspect active CLI auth |
login | sign in for preview uploads |
logout | clear the local desktop auth session |
config | manage local CLI preferences |
Global Flags
| flag | description |
|---|---|
-h, --help | show help |
-V, --version | show version |
-v, --verbose | verbose output |
-p, --port <number> | bridge port, depending on command |
-d, --device <model> | override the simulated device model |
-t, --theme <scheme> | override light, dark, or auto color scheme |
--headless | run browser automation without a visible window where supported |
What The CLI Covers
The CLI is split across four jobs:
- booting a simulator shell around a local React Native bundler
- opening, listing, and targeting live sims over the shared bridge host
- automating those sims for Maestro/Detox tests, screenshots, and recordings
- exposing the same bridge-backed runtime to CLI automation and generated docs
If you only remember one rule, use the highest-level command that matches the task. Reach for sootsim open before pasting shell URLs, and sootsim describe before debugging with screenshots.
Command Groups
The command set is intentionally shaped around workflow instead of implementation detail.
- setup and development:
setup,open,desktop - storage:
storage - automation:
maestro,detox,record,screenshot - live control:
open,list,use,claim,close - runtime reads:
describe,find, and theget <noun>family (get tree,get a11y,get url,get count,get errors,get requests, …) - runtime actions: the
do <action>family (do tap,do type,do scroll,do swipe,do key, …), plusshell <action>for simulator chrome - instrumentation:
perffor profiling anddebugfor raw runtime dumps, channels, snapshots, diffs, and events - escape hatches:
inspectfor the full low-level subcommand surface - compatibility:
compat
That grouping is what the website docs and terminal help now share from the same package source.
Bridge Model
The bridge host is the control plane behind top-level verbs like describe and do tap, plus inspect, debug, open, list, use, claim, and close.
- default bridge port:
7668 - default browser shell URL:
http://localhost:5173/ - every connected sim gets a stable hex id like
a1,a2, …,af,b0 - the desktop companion and browser shells both register through the same host
- the first CLI to send a command to a sim holds a 60s lease on it. other agents are rejected until the lease expires or, last-resort, taken with
sootsim claim --force(which interrupts whoever’s mid-flow; prefersootsim open --newto get a fresh sim instead). the lease refreshes on every command from the owner
This means you can open a sim one way and still inspect or debug it later from the CLI. The CLI also remembers the last sim you opened or selected, so one common pattern is:
terminal
Common Flows
terminal