$ 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

Xcode Command Line Tools

xcode-select --install

Installation

# Use with npx (recommended)
npx xcobra <args>

# Or install globally
npm install -g xcobra

Quick Start

# 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 <UDID> to target a specific device.

Device Listing

sim list — List Simulators

Display all available iOS simulators:

npx xcobra sim list
npx xcobra sim list --json

Screenshots & Video

sim screenshot — Capture Screenshot

Capture the simulator display as PNG:

# 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:

# 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

View Hierarchy (LLDB)

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

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

# 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).

Heap Memory Analysis

sim heap — Chrome DevTools-like Heap Snapshots

Analyze heap memory using LLDB:

# 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

Keyboard

sim keyboard — Toggle Software Keyboard

npx xcobra sim keyboard

Logging

sim log — Stream Logs

Stream logs from the simulator:

# 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 <SIMULATOR_UDID>

Appearance

Toggle Dark/Light Mode

Switch the simulator between light and dark appearance using simctl directly:

# 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.

crash / crash latest — View Latest Crash

Display the most recent crash report:

npx xcobra crash
npx xcobra crash latest

crash list — List Recent Crashes

Show all recent crash reports:

npx xcobra crash list
npx xcobra crash list --json

crash <path> — View Specific Crash

Display a specific crash report file:

npx xcobra crash /path/to/crash.ips
npx xcobra crash /path/to/crash.ips --json

Crash Report Output

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).

Quick Start

# 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

expo eval — Evaluate JavaScript

Evaluate JavaScript expressions in the running app. Objects are automatically inspected, and promises are awaited:

# 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)"

expo network — Monitor Network Requests

Monitor HTTP requests from the app in real-time:

# 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.

expo proxy — Connection Sharing

Start a CDP proxy to share connections between multiple commands:

# 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:

# 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

Source Inspection

Inspect the JavaScript bundle loaded in the app:

# 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:

# 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

Simulator Commands

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

Crash Report Commands

| Command | Description | | ------------------- | ----------------------------- | | crash | Display latest crash report | | crash latest | Display latest crash report | | crash list | List recent crash reports | | crash <path> | Display specific crash report | | crash --json | Output crash data as JSON |

Expo Commands

| Command | Description | | -------------------- | ------------------------------------------ | | expo list | List debuggable targets | | expo eval <expr> | 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

# Install dependencies
bun install

# Build the wrapper
bun run build

# Test locally
./dist/index.js sim list

Claude Code + xcode, brah