CLI Reference

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

rnx [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 rnx open before pasting shell URLs, and rnx 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 rnx 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
• +
  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 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
• +
  rnx 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 rnx claim --force (which interrupts whoever’s mid-flow; prefer rnx 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:

rnx open 8081
rnx describe
rnx 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. rnx does not start or replace that server. Run rnx 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 background service keeps that bridge and the runtime ready between commands. It is strongly recommended for local agent work because inspect, interaction, and test commands start much faster. It remains optional: enable it any time with rnx daemon install. CI can install the standalone CLI with curl -fsSL https://rnxsim.com/install.sh | RNX_NO_MODIFY_PATH=1 sh and run rnx open <port> --driver playwright --headless; the command starts the bridge for the job without registering an operating-system service. The rnx installer itself does not require Node.js, npm, or Bun.

Coding agents should run rnx 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
rnx open 8081

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

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

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

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

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

#Multiple Sims

When more than one sim is connected, run rnx 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 RNX_CLI_IDENTITY=<any-stable-string> once for your shell or agent run.

#Auto-Settle After Writes

Every rnx 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 warns that the next command may see mid-animation state and points at rnx do settle for a longer wait, so agents know what happened.

Opt out with --no-wait on the command, or RNX_NO_AUTO_WAIT=1 for the sim. For longer waits (e.g. screens that animate slowly), chain an explicit rnx do settle <seconds> or rnx wait idle after the write.

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

#Explicit Waits

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

• +
  rnx wait ready blocks until the guest app bundle is loaded and painted. A persistent runtime readiness flag is cleared on bundle reload and reset by full page reload, avoiding node-count heuristics that can mistake the connection screen for a loaded app. It is idempotent and returns immediately when the app is already ready. The default timeout is 20 seconds; pass --max-ms 30000 for slow cold bundles. CLI-side polling has no bridge timeout ceiling. Run it after opening a new sim or after debug js "window.location.reload()"; no sleep is needed.
• +
  rnx wait idle blocks until animations, rAF queue, and layout all stop moving. Same signal as do settle but discoverable under the wait grouping.
• +
  rnx wait selector <testid> blocks until a node with that testID is present and laid out. Playwright-style. When rnx 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.

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