$ bunx xcobra

A toolkit for iOS simulator automation and development. Build apps, capture screens, record video, and debug via LLDB—all from the command line.

Features

- 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

Prerequisites

$3

``sh
xcode-select --install
`

Installation

`sh


Use with npx (recommended)

npx xcobra

Or install globally

npm install -g 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.png

Record video

npx xcobra sim record-video --output ./recording.mp4

Get 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 Simulators

Display all available iOS simulators:

`sh
npx xcobra sim list
npx xcobra sim list --json
`

$3

#### sim screenshot — Capture Screenshot

Capture the simulator display as PNG:

`sh


Auto-generated filename

npx xcobra sim screenshot

Custom output path

npx xcobra sim screenshot --output ~/Desktop/screenshot.png
`

#### sim record-video — Record Video

Record simulator video:

`sh


Basic recording (press Ctrl+C to stop)

npx xcobra sim record-video --output recording.mp4

With codec option

npx xcobra sim record-video --output recording.mp4 --codec hevc
`

$3

#### sim hierarchy (or sim xml) — Get UIKit View Hierarchy

Get the full UIKit view hierarchy via LLDB, similar to Xcode's view debugger:

`sh


Get view hierarchy (auto-detects running app)

npx xcobra sim hierarchy

Get view controller hierarchy

npx xcobra sim hierarchy --controllers

Get Auto Layout constraint trace

npx xcobra sim hierarchy --constraints

Or 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 Snapshots

Analyze heap memory using LLDB:

`sh


Get heap summary (auto-detects running app)

npx xcobra sim heap summary

Take a full heap snapshot

npx xcobra sim heap snapshot --output snapshot.json

Inspect a specific object by address

npx xcobra sim heap inspect 0x7f8b12345678

Or 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 Logs

Stream logs from the simulator:

`sh


All logs from booted simulator

npx xcobra sim log

Filter by app bundle identifier

npx xcobra sim log --app-id com.example.myapp

Specific 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 dark

Set 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 list

Evaluate JavaScript in the app

npx xcobra expo eval "1 + 1"
npx xcobra expo eval "expo.modules.FileSystem"

Stream console output

npx xcobra expo console

Monitor 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 network

Monitor 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 proxy

Now 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 scripts

Get source code of a specific script

npx xcobra expo src source 42

List 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 Debug

Build for simulator

npx xcobra build -project MyApp.xcodeproj -scheme MyApp \
-destination 'platform=iOS Simulator,name=iPhone 16'

Show version (raw output)

npx xcobra -version

List SDKs (raw output)

npx xcobra -showsdks

List 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 install

Build the wrapper

bun run build

Test locally

./dist/index.js sim list
``

Claude Code + xcode, brah