Fast Bun CLI for headless interaction with Apple devices. Specifically designed for agents.
npm install xcobraA toolkit for iOS simulator automation and development. Build apps, capture screens, record video, and debug via LLDB—all from the command line.
- Pretty Build Output: Clean, colored formatting for xcodebuild operations
- Screen Capture: Screenshots and video recording via simctl
- View Hierarchy: Get UIKit view hierarchy via LLDB debugging
- Heap Analysis: Chrome DevTools-like heap snapshots
- Log Streaming: Real-time simulator logs with app filtering
- Crash Reports: Parse and display iOS crash reports with symbolicated backtraces
- Expo/React Native Debugging: CDP-based debugging for Expo and React Native apps
- Zero Config: Works as a drop-in replacement for xcodebuild
``sh`
xcode-select --install
`shUse with npx (recommended)
npx xcobra
Quick Start
`sh
Build your app
npx xcobra build -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'Take a screenshot
npx xcobra sim screenshot --output ./screenshot.pngRecord video
npx xcobra sim record-video --output ./recording.mp4Get view hierarchy (auto-detects running app)
npx xcobra sim hierarchy
`---
Simulator Commands (
sim)All simulator commands automatically detect the booted simulator. Use
--udid to target a specific device.$3
####
sim list — List SimulatorsDisplay all available iOS simulators:
`sh
npx xcobra sim list
npx xcobra sim list --json
`$3
####
sim screenshot — Capture ScreenshotCapture the simulator display as PNG:
`sh
Auto-generated filename
npx xcobra sim screenshotCustom output path
npx xcobra sim screenshot --output ~/Desktop/screenshot.png
`####
sim record-video — Record VideoRecord simulator video:
`sh
Basic recording (press Ctrl+C to stop)
npx xcobra sim record-video --output recording.mp4With codec option
npx xcobra sim record-video --output recording.mp4 --codec hevc
`$3
####
sim hierarchy (or sim xml) — Get UIKit View HierarchyGet the full UIKit view hierarchy via LLDB, similar to Xcode's view debugger:
`sh
Get view hierarchy (auto-detects running app)
npx xcobra sim hierarchyGet view controller hierarchy
npx xcobra sim hierarchy --controllersGet Auto Layout constraint trace
npx xcobra sim hierarchy --constraintsOr target a specific app
npx xcobra sim hierarchy --bundle-id com.example.myapp
`Note: The hierarchy command attaches LLDB to the running app, which briefly pauses execution. Only works with debuggable apps (not system apps).
$3
####
sim heap — Chrome DevTools-like Heap SnapshotsAnalyze heap memory using LLDB:
`sh
Get heap summary (auto-detects running app)
npx xcobra sim heap summaryTake a full heap snapshot
npx xcobra sim heap snapshot --output snapshot.jsonInspect a specific object by address
npx xcobra sim heap inspect 0x7f8b12345678Or target a specific app
npx xcobra sim heap summary --bundle-id com.example.myapp
`$3
####
sim keyboard — Toggle Software Keyboard`sh
npx xcobra sim keyboard
`$3
####
sim log — Stream LogsStream logs from the simulator:
`sh
All logs from booted simulator
npx xcobra sim logFilter by app bundle identifier
npx xcobra sim log --app-id com.example.myappSpecific simulator
npx xcobra sim log --udid
`$3
#### Toggle Dark/Light Mode
Switch the simulator between light and dark appearance using simctl directly:
`sh
Set to dark mode
xcrun simctl ui booted appearance darkSet to light mode
xcrun simctl ui booted appearance light
`---
Crash Reports (
crash)Parse and display iOS crash reports (.ips files) from
~/Library/Logs/DiagnosticReports/. Provides formatted, symbolicated crash analysis similar to Xcode's crash reporter.$3
Display the most recent crash report:
`sh
npx xcobra crash
npx xcobra crash latest
`$3
Show all recent crash reports:
`sh
npx xcobra crash list
npx xcobra crash list --json
`$3
Display a specific crash report file:
`sh
npx xcobra crash /path/to/crash.ips
npx xcobra crash /path/to/crash.ips --json
`$3
The formatted output includes:
- Process Information: App name, bundle ID, version, executable path
- System Information: OS version, CPU architecture
- Timestamps: When the app launched and when it crashed
- Exception Details: Exception type (e.g.,
EXC_BAD_ACCESS), signal (e.g., SIGSEGV), and fault address
- Termination Reason: Why the process was terminated
- Crashed Thread: Full symbolicated backtrace with source file and line numbers
- Other Threads: Condensed backtraces showing top 5 frames
- Binary Images: App-related dylibs with UUIDs for symbolication---
Expo Commands (
expo)Debug Expo and React Native apps via Chrome DevTools Protocol (CDP). All commands connect to the Metro dev server (default port 8081).
$3
`sh
List connected apps
npx xcobra expo listEvaluate JavaScript in the app
npx xcobra expo eval "1 + 1"
npx xcobra expo eval "expo.modules.FileSystem"Stream console output
npx xcobra expo consoleMonitor network requests
npx xcobra expo network
`$3
Evaluate JavaScript expressions in the running app. Objects are automatically inspected, and promises are awaited:
`sh
Simple expressions
npx xcobra expo eval "1 + 1" # => 2
npx xcobra expo eval "Object.keys(global)" # => ["__DEV__", ...]Inspect objects (shows all properties including functions)
npx xcobra expo eval "expo.modules.FileSystem"Async functions work automatically
npx xcobra expo eval "expo.modules.FileSystem.info(expo.modules.FileSystem.documentDirectory)"
`$3
Monitor HTTP requests from the app in real-time:
`sh
Monitor all network traffic
npx xcobra expo networkMonitor and trigger a request in the same connection
npx xcobra expo network --eval "fetch('https://httpbin.org/get').then(r => r.json())"
`The
--eval flag is useful because CDP only allows one debugger connection per target. Using --eval triggers the request from the same connection that's monitoring.$3
Start a CDP proxy to share connections between multiple commands:
`sh
Start the proxy (runs in foreground)
npx xcobra expo proxyNow other commands share the connection
npx xcobra expo eval "1 + 1" # Uses proxy
npx xcobra expo network # Uses proxy, won't disconnect eval
npx xcobra expo console # Uses proxy
`Multiple Projects: Each Metro port gets its own proxy, so you can run xcobra in multiple projects simultaneously:
`sh
Terminal 1 - Project A on port 8081
npx xcobra expo proxy &
npx xcobra expo eval "1 + 1"Terminal 2 - Project B on port 8082
npx xcobra expo proxy --port 8082 &
npx xcobra expo eval "2 + 2" --port 8082
`$3
Inspect the JavaScript bundle loaded in the app:
`sh
List all loaded scripts
npx xcobra expo src scriptsGet source code of a specific script
npx xcobra expo src source 42List Metro modules
npx xcobra expo src modules
`---
Build Commands
Standard xcodebuild commands with pretty-formatted output:
`sh
Build a project
npx xcobra build -project MyApp.xcodeproj -scheme MyApp -configuration DebugBuild for simulator
npx xcobra build -project MyApp.xcodeproj -scheme MyApp \
-destination 'platform=iOS Simulator,name=iPhone 16'Show version (raw output)
npx xcobra -versionList SDKs (raw output)
npx xcobra -showsdksList schemes
npx xcobra -list
`Build logs are automatically saved to
.xcodebuild/xcodebuild.log.---
Command Reference
$3
| Command | Description |
| ---------------- | ------------------------------------- |
|
sim list | List all simulators |
| sim screenshot | Capture screenshot |
| sim record-video | Record video |
| sim hierarchy | Get UIKit view hierarchy via LLDB |
| sim xml | Alias for sim hierarchy |
| sim heap | Heap memory analysis |
| sim keyboard | Toggle software keyboard |
| sim log | Stream simulator logs |$3
| Command | Description |
| ------------------- | ----------------------------- |
|
crash | Display latest crash report |
| crash latest | Display latest crash report |
| crash list | List recent crash reports |
| crash | Display specific crash report |
| crash --json | Output crash data as JSON |$3
| Command | Description |
| -------------------- | ------------------------------------------ |
|
expo list | List debuggable targets |
| expo eval | Evaluate JavaScript in the app |
| expo console | Stream console output |
| expo network | Monitor network requests |
| expo proxy | Start CDP proxy for connection sharing |
| expo reload | Reload the app |
| expo open-debugger | Launch React Native DevTools |
| expo src scripts | List loaded scripts |
| expo src source | Get script source code |
| expo src modules | List Metro modules |---
Development
`sh
Install dependencies
bun installBuild the wrapper
bun run buildTest locally
./dist/index.js sim list
``Claude Code + xcode, brah