Commands
| Command | Description |
|---|---|
simgrid | Interactive picker, then launch — the default. |
simgrid --profile <name> | Launch a saved device set; saved automatically the first time you use a name. |
simgrid device [--json] | Prepare this project's dedicated device and print it — for agents, never prompts. |
simgrid devices [--json] | List every device: booted?, build installed?, held by which project. Alias ls. |
simgrid init | Wire "start": "simgrid" into package.json and write the agent rule. |
simgrid status | Show which project runs on which device (global). |
simgrid logs [device] | Stream a running device's system logs; picker when several run. |
simgrid profiles | List saved device profiles for this project. |
simgrid doctor | Check xcrun / adb / emulator on your PATH, with install hints. |
simgrid stop | Stop this project's sessions and deregister them. |
simgrid help | Print usage. |
simgrid status is global — run it from anywhere. Everything else (logs, profiles,
stop, init, launching) acts on the project in your current directory.
simgrid
The default. Resolves the project from app.json / app.config.ts, discovers every device,
annotates each (build installed? busy?), shows the picker, then boots + launches your selection.
One Metro is started per project and reused across all its devices. Runs in the foreground —
Ctrl+C stops it.
simgrid --profile <name>
Skip the picker and relaunch a remembered set of devices. The first time you use a new name it falls back to the picker and saves your choice under that name. See Profiles.
Launch flags: --force-build, --clean-build, --clear and --reset control the native build
and Metro caches. --reset implies --clean-build, which implies --force-build.
simgrid device [--json]
The non-interactive door, for coding agents and scripts. Returns this project's dedicated
device — booted, with a fresh dev build, pointed at a running Metro. stdout is pure JSON;
progress and build output go to stderr.
One dedicated device per project and per platform: --platform android prepares the
project's own AVD, --all prepares every platform it already uses, sharing one Metro. Metro is
spawned detached so it outlives the command and the next call reuses it.
simgrid devices [--json]
Every simulator, emulator and physical device, annotated for the project you are standing in:
booted?, is this project's build installed and fresh?, which project is holding it. Read-only
and never fatal — outside an Expo project you still get the list, with buildStatus: "unknown".
simgrid init
Sets "start": "simgrid" in package.json. The previous start script is preserved as
start:orig, so nothing is lost. It also writes .claude/rules/simgrid.md so coding agents
ask simgrid for the device instead of booting their own — pass --no-agent-rule to skip it,
and an existing file is never overwritten.
simgrid status
Lists every running session across all projects: project → device, Metro port, PID. Dead sessions
(crash, kill -9) are reconciled away automatically.
simgrid logs [device]
Streams a running device's system logs. With several sessions you get a picker; pass a device name to target one directly. See Logs.
simgrid doctor
Verifies xcrun, adb and emulator are on your PATH and prints install hints for whatever is
missing. See Doctor.
simgrid stop
Signals this project's sessions to stop and removes them from the registry.