# AI Usage Guide for rn-run
This document provides structured guidance for AI assistants (Claude, etc.) to effectively use `rn-run` for React Native development automation.
## Overview
`rn-run` is a CLI tool that automates React Native development workflows on macOS. It handles:
- Building and launching iOS/Android apps
- Cleaning build artifacts and dependencies
- Managing Metro bundler and simulators
- Environment diagnostics
**Always use `--json` flag** for programmatic parsing of results.
## Quick Reference
| `rn-run --check-env --json` | Check dev environment | Build fails with "not found" errors |
| `rn-run --rn-version --json` | Get RN version | Need to determine npm vs yarn |
| `rn-run --list-simulators --json` | List iOS simulators | Need valid simulator name |
| `rn-run --list-emulators --json` | List Android emulators | Verify emulator exists |
| `rn-run --kill-metro` | Kill Metro bundler | Port 8081 in use, Metro stuck |
| `rn-run --quit-simulator` | Quit iOS Simulator | Simulator frozen/stuck |
| `rn-run --screenshot --json` | Screenshot iOS simulator | Capture current app state |
| `rn-run --screenshot -a --json` | Screenshot Android emulator | Capture current app state |
| `rn-run --update --json` | Update rn-run | Check for and install latest version |
| `rn-run --logs --json` | List build logs | View recent build logs for debugging |
| `rn-run --show-log --json` | Show latest log | Get full content of most recent build log |
| `rn-run --clean-modules` | Delete node_modules | Dependency corruption |
| `rn-run --clean-pods` | Clean iOS pods | Pod-related build errors |
| `rn-run --clean-gradle` | Clean Android gradle | Gradle sync failures |
| `rn-run --clean-metro` | Clear Metro cache | "Unable to resolve module" errors, stale bundle |
| `rn-run --delete-emulators` | Delete ALL Android emulators | Reset Android dev environment |
| `rn-run --pod-install` | Run pod install | After cleaning pods |
| `rn-run -i` | Run iOS app | Normal iOS development |
| `rn-run -a` | Run Android app | Normal Android development |
| `rn-run -i -c` | Clean install + run iOS | Dependency issues |
| `rn-run -i -u` | Deep clean + run iOS | RN version upgrades |
---
## Decision Trees
### iOS Build Fails
```
iOS build error detected
├── Error contains "pod" or "CocoaPods"?
│ ├── Yes → rn-run --clean-pods && rn-run --pod-install
│ └── Still failing? → rn-run -i -u (deep clean)
├── Error contains "Unable to find a specification"?
│ └── rn-run --clean-pods && rn-run --pod-install
├── Error contains "SDK not found" or "Xcode"?
│ └── rn-run --check-env --json (verify Xcode setup)
├── Error contains "node_modules" or dependency errors?
│ └── rn-run --clean-modules && npm install
├── Metro bundler issues (port 8081, stuck)?
│ └── rn-run --kill-metro
├── Error contains "Unable to resolve module" or stale bundle?
│ └── rn-run --clean-metro
└── Unknown error?
└── rn-run -i -c (clean install) or rn-run -i -u (deep clean)
```
### Android Build Fails
```
Android build error detected
├── Error contains "gradle" or "Could not resolve"?
│ └── rn-run --clean-gradle
├── Error contains "SDK" or "ANDROID_HOME"?
│ └── rn-run --check-env --json (verify Android SDK)
├── Error contains "node_modules" or dependency errors?
│ └── rn-run --clean-modules && npm install
├── Metro bundler issues?
│ └── rn-run --kill-metro
├── Error contains "Unable to resolve module" or stale bundle?
│ └── rn-run --clean-metro
└── Unknown error?
└── rn-run -a -c (clean install) or rn-run -a -u (deep clean)
```
### Environment Setup Issues
```
User reports build environment problems
├── First step → rn-run --check-env --json
├── Parse the JSON response:
│ ├── Check each item in "checks" array
│ ├── If check.ok == false:
│ │ └── Show check.error and check.fix to user
│ └── Focus on checks where required_for matches target platform
```
---
## JSON Response Formats
### Successful Response Structure
```json
{
"command": "command-name",
"success": true,
"data": { /* command-specific payload */ }
}
```
### Error Response Structure
```json
{
"command": "command-name",
"success": false,
"error": "Error description",
"suggested_fix": "Recommended action to resolve"
}
```
### check-env Response
```json
{
"command": "check-env",
"success": true,
"data": {
"overall_status": "ok|warnings|errors",
"checks": [
{
"name": "node",
"ok": true,
"version": "v20.10.0",
"required_for": ["ios", "android"]
},
{
"name": "cocoapods",
"ok": false,
"error": "CocoaPods not found",
"fix": "Install CocoaPods: sudo gem install cocoapods OR brew install cocoapods",
"required_for": ["ios"]
}
],
"summary": "Some required tools are missing..."
}
}
```
### rn-version Response
```json
{
"command": "rn-version",
"success": true,
"data": {
"version": "0.74.1",
"package_manager": "npm",
"notes": ["RN 0.74+ uses npm and npx for commands"]
}
}
```
### list-simulators Response
```json
{
"command": "list-simulators",
"success": true,
"data": {
"simulators": [
{
"name": "iPhone 15",
"udid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"state": "Shutdown",
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-17-2"
}
]
}
}
```
### screenshot Response
```json
{
"command": "screenshot",
"success": true,
"data": {
"platform": "ios",
"path": "screenshot-ios-1234567890.png",
"message": "Screenshot saved to screenshot-ios-1234567890.png"
}
}
```
### update Response
```json
{
"command": "update",
"success": true,
"data": {
"current_version": "0.1.7",
"latest_version": "0.1.8",
"updated": true,
"message": "Updated from v0.1.7 to v0.1.8"
}
}
```
### logs Response
```json
{
"command": "logs",
"success": true,
"data": {
"log_dir": "/Users/user/.rn-run/logs",
"logs": [
{
"path": "/Users/user/.rn-run/logs/rn-run-ios-2024-01-30_14-30-00.log",
"name": "rn-run-ios-2024-01-30_14-30-00.log",
"size": 12345,
"modified": "2024-01-30 14:30:00"
}
]
}
}
```
### show-log Response
```json
{
"command": "show-log",
"success": true,
"data": {
"path": "/Users/user/.rn-run/logs/rn-run-ios-2024-01-30_14-30-00.log",
"content": "... full log content ..."
}
}
```
---
## Common Error Patterns
| `Unable to find a specification for` | Stale pod cache | `--clean-pods && --pod-install` |
| `pod install` hangs or fails | Corrupted Pods | `--clean-pods && --pod-install` |
| `No bundle URL present` | Metro not running | `--kill-metro`, then rebuild |
| `Unable to resolve module` | Metro cache stale | `--clean-metro` |
| `ENOSPC: no space left` | Watchman limits | `--clean-modules` |
| `Could not resolve project :app` | Gradle cache | `--clean-gradle` |
| `SDK location not found` | ANDROID_HOME not set | Check `--check-env` |
| `error: Build input file cannot be found` | Stale build | `--clean-pods` |
| `The sandbox is not in sync with the Podfile.lock` | Pods out of sync | `--pod-install` |
| `node_modules/react-native` missing | Dependencies not installed | `npm install` or `yarn` |
---
## Recommended Workflow
### For AI Debugging React Native Issues
1. **Gather context first**
```bash
rn-run --check-env --json rn-run --rn-version --json ```
2. **Parse error messages** from the user's build output
3. **Match against error patterns** (see table above)
4. **Execute targeted fix** before resorting to full clean:
- Pod errors → `--clean-pods && --pod-install`
- Gradle errors → `--clean-gradle`
- Module errors → `--clean-modules && npm install`
- Metro stuck → `--kill-metro`
- Metro cache stale → `--clean-metro`
5. **Escalate if needed**:
- If targeted fix fails → `rn-run -i -c` (clean install)
- If clean install fails → `rn-run -i -u` (deep clean)
### For Fresh Project Setup
```bash
rn-run --check-env --json # Verify all tools installed
# Fix any issues reported
rn-run -i -c # Clean install and run iOS
# OR
rn-run -a -c # Clean install and run Android
```
### For React Native Version Upgrades
```bash
rn-run -i -u # Deep clean + reinstall for iOS
# OR
rn-run -a -u # Deep clean + reinstall for Android
```
---
## Platform Notes
### iOS-specific
- Requires macOS with Xcode installed
- CocoaPods manages native dependencies
- Use `--simulator "iPhone 15 Pro"` to specify device
- `--list-simulators` shows available devices
### Android-specific
- Requires Android Studio with SDK
- ANDROID_HOME environment variable must be set
- Gradle manages native dependencies
- `--list-emulators` shows available devices
### Version-specific Behavior
| >= 0.74 | npm | Uses `npx react-native` |
| < 0.74 | yarn | Uses `yarn react-native` |
---
## Exit Codes
| 0 | Success |
| 1 | Error (check stderr or JSON error field) |
---
## Flags Reference
### Output
- `--json` - Output in JSON format (recommended for AI)
### Diagnostics
- `--check-env` - Check development environment
- `--rn-version` - Show React Native version
- `--list-simulators` - List iOS simulators
- `--list-emulators` - List Android emulators
### Process Management
- `--kill-metro` - Kill Metro bundler on port 8081
- `--quit-simulator` - Quit iOS Simulator
- `--screenshot` - Take screenshot of running simulator/emulator (iOS by default, use with `-a` for Android)
- `--output <path>` - Specify output path for screenshot (optional, defaults to timestamped filename)
- `--update` - Update rn-run to latest version from crates.io
- `--logs` - List recent build logs (last 10)
- `--show-log` - Show contents of most recent build log
### Cleanup
- `--clean-modules` - Delete node_modules only
- `--clean-pods` - Delete iOS Pods, Podfile.lock, build
- `--clean-gradle` - Delete Android build caches
- `--clean-metro` - Clear Metro bundler cache
### Build
- `--pod-install` - Run pod install
### Run
- `-i, --ios` - Run on iOS simulator
- `-a, --android` - Run on Android emulator
- `-s, --simulator <name>` - Specify iOS simulator
- `-c, --clean-install` - Clean and reinstall before running
- `-u, --upgrade` - Deep clean for RN upgrades