sootsim inspect

Use the bridge-backed inspection surface for full access to the real node tree. sootsim inspect <sub> works for every subcommand in the surface; day-to-day, prefer the grouped verbs (describe, find, get, do, shell, debug) — run sootsim --help to see the full set.

terminal

sootsim inspect <subcommand> [args]

Options

flag	description
`--session <session-id>`	target a specific connected browser or desktop window
`--port <number>`	bridge port (defaults to 7668)
`--timeout <ms>`	command timeout for bridge requests
`--base-url <url>`	base shell URL used by open when wrapping bundle targets

Examples

terminal

sootsim describe
sootsim get errors 5
sootsim get requests 5
sootsim do tap-text "Sign in"
sootsim list
sootsim debug state shell --session tab-2

Core Subcommands

sootsim inspect <sub> is the full surface — every runtime verb dispatches through here. Day-to-day, prefer the grouped verbs which are shorter and self-documenting:

sootsim describe for understanding visible UI quickly
sootsim find <text | --testid | --role | --type | --pressable | --visible> for locating specific nodes
sootsim get <noun> for reads — tree, a11y, url, count, errors, warnings, requests, globals, layout, node
sootsim do <action> for writes — tap, double-tap, tap-text, tap-id, type, type-into, key, key-sequence, dispatch, scroll, drag, swipe, long-press, touch, gesture, pinch, reload, sleep, settle
sootsim wait <kind> for explicit sync — ready (app loaded), idle (animations settled), selector <testid> (node present)
sootsim shell <action> for shell state — launch, home, switcher, open-card, appearance, lock, shake
sootsim debug state <kind> for raw runtime dumps — shell, worker, keyboard, scroll, hit, gesture
sootsim debug <tool> for instrumentation — channels, snapshots, diffs, events, js/eval, perf, sample-color

The default debugging move in sootsim should be to inspect the real node tree first, not to infer structure from a screenshot.

Multiple Sessions

When more than one shell is connected, run sootsim list first and pass --session to the command you care about. The CLI remembers the last session you opened or used, so explicit --session matters most when you are juggling more than one target and want deterministic automation.

Passing --session <tab-id> (or its alias --tab) also skips the CLI’s identity lookup entirely — roughly 250ms saved per command on macOS where identity otherwise falls back to lsof. If you can’t pass --session on every call, export SOOTSIM_SESSION_ID=<any-stable-string> once for your shell or agent session and identity becomes free. When a sandboxed shell environment (some agent Bash tools) causes identity to drift between invocations, the CLI now warns and recommends these options directly.

Auto-Settle After Writes

Every sootsim do <write> command (tap, tap-id, type, scroll, drag, swipe, etc.) briefly waits for layout to stabilize before returning — capped at 350ms (1200ms when an agent environment is detected), bails on 2 consecutive stable frames. This keeps the next CLI call from capturing mid-animation state, which is the single most common source of agent confusion (do tap then describe showing a half-slid screen). When the auto-wait hits its cap without stabilizing, it logs ⚠ auto-wait timed out after Xms — next command may see mid-animation state so agents know what happened.

Opt out with --no-wait on the command, or SOOTSIM_NO_AUTO_WAIT=1 for the session. For longer waits — e.g., screens that animate slowly — chain an explicit sootsim do settle <seconds> or sootsim wait idle after the write.

Agent detection is automatic: CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_THREAD_ID, CURSOR_TRACE_ID, AIDER_MODEL, or explicit SOOTSIM_AGENT=1 enables agent-friendly defaults. Set SOOTSIM_AGENT=0 to force interactive defaults.

Explicit Waits

sootsim wait <kind> gives you bounded, loud synchronization primitives instead of sleep guessing:

sootsim wait ready blocks until the guest app bundle is loaded and painted. Uses a persistent __sootsimExternalAppReady flag set by the sootsim:externalAppReady event handler (cleared on bundle reload, reset by full page reload), not a node-count heuristic that false-positives on the ConnectRN skeleton. Idempotent: returns in ~200ms when already ready. Default 20s; pass --max-ms 30000 for slow cold bundles (uniswap, expensify). CLI-side polling — no bridge timeout ceiling. First thing to run after opening a new session or after debug js "window.location.reload()" — no sleep needed.
sootsim wait idle blocks until animations, rAF queue, and layout all stop moving. Same signal as do settle but discoverable under the wait grouping.
sootsim wait selector <testid> blocks until a node with that testID is present and laid out. Playwright-style. When sootsim find --testid foo returns no result, the CLI prints this as a hint.

All wait subverbs accept --max-ms <ms> and exit non-zero on timeout, so scripts fail loudly.

sootsim do <tap|double-tap|long-press> also accept --testid <id> or --text <text> to resolve a node center at call time — equivalent to do tap-id / do tap-text but consistent with find --testid. Missing node prints the wait selector hint.

Flow Drafting

When sootsim flow start is active, successful write commands like tap, tap-id, type, scroll, and swipe update the pending flow candidate. They do not automatically become part of the draft. Use sootsim flow keep only after the last action proved itself.

upload

network