CLI Reference
sootsim command-line interface
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 |
|---|---|
preview | production-like preview build |
test | run tests against sootsim |
flow | run flows through the current sim or manage a draft from live inspect actions |
maestro | run existing 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) |
profile | manage isolated storage profiles |
cpu-profile | capture a JS CPU profile of the sim workers over the Chrome DevTools Protocol |
react | inspect React component render cost in the tenant worker |
assert | run any read verb and convert its output into an exit code |
screenshot | capture the canvas (full or cropped) as PNG |
get | read runtime state (tree, a11y, url, count, errors, …) |
screenshots | capture + compose app-store screenshot sets from a single plan |
do | drive the app (tap, type, scroll, swipe, key, reload, …) |
screenshot-mode | toggle the screenshot-mode chrome overlay |
wait | block until the runtime reaches a known state |
shell | drive shell state and simulator chrome |
three-mode | toggle the live browser 3d device stage |
upload | publish the current recorded bundle as a shareable /preview/<id> link |
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 |
diagnose | composed read commands for “what just went wrong?” |
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 |
skills | install bundled sootsim skills into a project |
claim | take an exclusive lease on a sim |
agent | attached projects + local agent sessions (codex/claude) |
close | close a connected sim |
config | manage sootsim.config.ts |
compat | check package compatibility (alias: scan) |
electron | launch 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 |
server | run the sootsim bridge daemon in the foreground |
start | install + run sootsim, open it in your browser |
runtime | manage engine runtimes under ~/.sootsim/runtimes/ |
launch | one-shot: install runtime if needed, start daemon, open the app |
setup-repo | set up sootsim in your project |
install-desktop | download and install the optional desktop GUI |
login | sign in so preview uploads are associated with your account |
logout | clear the local desktop auth state |
whoami | print the currently signed-in account |
keys | manage the api keys that authorize CI preview uploads |
hints | inspect and manage the CLI hint registry |
Global Flags
| flag | description |
|---|---|
-h, --help | show help |
-V, --version | show version |
-v, --verbose | verbose output |
-p, --port <number> | server or 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 tests, flows, 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.
- development:
preview,electron,install,config - storage:
profile - automation:
test,flow,record,screenshot,screenshots - 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:
tap,type,scroll,swipe,key, and thedo <action>family, plusshell <action>for simulator chrome - instrumentation:
debug—debug state <kind>for raw runtime dumps, plus channels/snapshots/diffs/events - escape hatches:
inspect(full subcommand surface, all old verbs still work as aliases) - 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 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