CLI Reference

The sootsim CLI is the operational surface for booting shells, opening sessions, driving automation, and exposing the bridge host to agents.

terminal

sootsim [command] [options]
sootsim [-- <bundler-command>]

Commands

command	description
`preview`	production-like preview build
`test`	run tests against sootsim
`flow`	run flows through the current session 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 session as webm/mp4/gif, or sample N png frames (—frames)
`profile`	capture a sampled CPU trace from 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
`upload`	publish the current bundle as a shareable /preview/<id> link
`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
`open`	load a target into the current session or open a new one
`list`	list connected sootsim sessions or available launch drivers
`use`	select a connected sootsim session
`skills`	install bundled sootsim skills into a project
`claim`	take an exclusive lease on a sootsim session
`close`	close a connected sootsim session
`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
`server`	run the sootsim bridge daemon in the foreground
`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 session
`whoami`	print the currently signed-in account

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 sessions over the shared bridge host
automating those sessions 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
automation: test, flow, record, screenshot, screenshots
live control: open, list, use, claim, close
runtime reads: describe, find, and the get <noun> family (get tree, get a11y, get url, get count, get errors, get requests, …)
runtime actions: tap, type, scroll, swipe, key, and the do <action> family, plus shell <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 browser tab or desktop window gets a stable id like tab-6
the desktop companion and browser shells both register through the same host
the first CLI to send a command to a tab holds a 60s lease on it. other agents are rejected until the lease expires or is taken with sootsim claim --force. the lease refreshes on every command from the owner

This means you can open a session one way and still inspect or debug it later from the CLI. The CLI also remembers the last session you opened or selected, so one common pattern is:

terminal

sootsim open 8081
sootsim describe
sootsim do tap-text "Sign in"

Common Flows

terminal

# load a local port into the current session
sootsim open 8081

# open a second session in its own browser window
sootsim open --new 8085

# see what is connected and target one tab explicitly
sootsim list
sootsim describe --session tab-3

# capture state around a bug
sootsim debug snapshot before
sootsim debug snapshot after
sootsim debug diff before after

# run a single flow
sootsim flow flows/login.yaml --record

Agent Devtool (Inspect)

preview