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.

sootsim inspect <subcommand> [args]

#Options

#Examples

sootsim describe
sootsim get errors 5
sootsim get requests 5
sootsim do tap-text "Sign in"
sootsim list
sootsim debug state shell --sim a2

#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 Sims

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

Passing --sim <sim> also skips the CLI’s identity lookup entirely. If you need a stable identity without pinning a sim on every call, export SOOTSIM_CLI_IDENTITY=<any-stable-string> once for your shell or agent run.

#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 200ms (400ms when an agent environment is detected), bailing 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 sim. 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, so there is no bridge timeout ceiling. It is the first thing to run after opening a new sim 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. A missing node prints the wait selector hint.

#Flow Drafting

When sootsim maestro 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 maestro keep only after the last action proved itself.

#Related

• debug
• get
• do
• shell
• find
• list
• open
• use