CLI Reference

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

sootsim [command] [options]

#Commands

#Global Flags

#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
• agent onboarding: skill install installs the bundled SootSim workflow skills
• storage: storage
• automation: maestro, detox, record, screenshot
• live control: open, list, use, claim, close
• runtime reads: describe, find, and the get <noun> family (get tree, get a11y, get layout --styling, get url, get count, get errors, get requests, …)
• runtime actions: the do <action> family (do tap, do type, do scroll, do swipe, do key, …), plus shell <action> for simulator chrome
• instrumentation: perf for profiling and debug for raw runtime dumps, channels, snapshots, diffs, and events
• escape hatches: inspect for the full low-level subcommand surface
• compatibility: compat, plus the explicitly approved report-issue feedback path

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 shell URL: http://localhost:7668/
• every connected sim gets a stable hex id like a1, a2, …, af, b0
• browser sims use isolated Playwright Chrome for Testing profiles; the desktop companion uses Electron
• sootsim open reuses the saved sim by default. --new, --profile, and --ephemeral explicitly request a separate sim
• 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; prefer sootsim open --new to 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:

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

#Local Setup And CI

Start the app’s Metro, Expo, React Native, or One development server with its existing command. SootSim does not start or replace that server. Run sootsim open <port> from the app project root when possible. That directory is the fallback for custom-font, splash-screen, and project-configuration discovery when the development server does not advertise its root.

The local bridge is a lightweight HTTP and WebSocket server at http://localhost:7668/ by default. The recommended installer registers that bridge as a background daemon so local commands can reuse it, but daemon registration is optional. CI can install the CLI with npm install --global sootsim and run sootsim open <port> --driver playwright --headless; the command starts the bridge for the job without registering an operating-system service.

Coding agents should run sootsim skill install once, then restart their session so they load the bundled setup, debugging, testing, visual, and performance workflows.

#Common Flows

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

# open a second sim only when it must run concurrently
sootsim open --new 8085

# see what is connected and target one sim explicitly
sootsim list
sootsim describe --sim a3

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

# isolate app storage in Electron or Playwright
sootsim storage profile create qa
sootsim open 8081 --profile qa

# run a single Maestro flow
sootsim maestro test .maestro/login.yaml --record