Using Xcode CLI

Overview

Native Xcode CLI tools (xcodebuild and xcrun simctl) provide full control over iOS/macOS builds and simulators without opening Xcode IDE. Core principle: Use CLI for automation, headless builds, and CI/CD—the same tools Xcode uses internally.

When to Use

• Building iOS/macOS apps from command line
• Running apps in iOS Simulator programmatically
• Taking screenshots or recording video of simulator
• Running unit/UI tests with specific targeting
• Automating builds in CI/CD pipelines
• Managing simulator instances (boot, shutdown, erase)
• Simulating location, push notifications, or permissions
• Capturing app logs for debugging

Symptoms that trigger this skill:

• "Unable to find destination matching"
• "No scheme named X found"
• "xcodebuild: error:"
• Need to automate Xcode workflows
• Building without opening Xcode IDE

When NOT to Use

• Editing code or project settings → Use Xcode IDE
• Managing Swift Package dependencies → Use swift package CLI
• Cross-platform builds → Use platform-specific tools
• Signing/provisioning profile management → Use Xcode or fastlane

Quick Start

Find available simulators:

xcrun simctl list devices available

Build for simulator:

UDID=$(xcrun simctl list devices --json | jq -r '.devices | .[].[] | select(.name=="iPhone 16 Pro" and .isAvailable==true) | .udid' | head -1)
xcodebuild -workspace App.xcworkspace -scheme App -destination "platform=iOS Simulator,id=$UDID" -derivedDataPath /tmp/build build

Install and launch:

APP_PATH=$(find /tmp/build -name "*.app" -type d | head -1)
xcrun simctl install $UDID "$APP_PATH"
xcrun simctl launch --console $UDID com.bundle.identifier

Take screenshot:

xcrun simctl io $UDID screenshot /tmp/screenshot.png

Quick Reference

| Task | Command | |------|---------| | List schemes | xcodebuild -workspace App.xcworkspace -list | | List simulators | xcrun simctl list devices available | | Get simulator UDID | xcrun simctl list devices --json \| jq ... | | Boot simulator | xcrun simctl boot $UDID | | Build for simulator | xcodebuild ... -destination "platform=iOS Simulator,id=$UDID" build | | Install app | xcrun simctl install $UDID /path/to/App.app | | Launch app | xcrun simctl launch --console $UDID com.bundle.id | | Take screenshot | xcrun simctl io $UDID screenshot /tmp/shot.png | | Run tests | xcodebuild ... test | | Stream logs | /usr/bin/log stream --predicate 'processImagePath CONTAINS "App"' |

Reference Documentation

| Reference | Contents | |-----------|----------| | xcodebuild.md | Project discovery, building, archiving, testing | | simctl.md | Device management, screenshots, video, location, permissions | | logging.md | Log streaming and filtering predicates | | workflows.md | End-to-end automation scripts |

Common Patterns

Build + Run

1. Find simulator UDID via simctl list devices --json
2. Boot simulator with simctl boot $UDID
3. Build with xcodebuild using -derivedDataPath
4. Find .app bundle in derived data
5. Install with simctl install
6. Launch with simctl launch --console

Run Tests

xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  -only-testing "AppTests/SpecificTest" test

Common Mistakes

| Mistake | Fix | |---------|-----| | "Unable to find destination" | Verify simulator exists with simctl list devices. Use exact name or UDID. | | "No scheme found" | Run xcodebuild -list to see available schemes. Ensure you're using -workspace or -project flag. | | "App not found after build" | Use -derivedDataPath /tmp/build and search there with find. | | Simulator not responding | Try xcrun simctl shutdown all then boot fresh. | | Build succeeds but app crashes | Check xcrun simctl launch --console for runtime errors. | | Tests hang indefinitely | Add -destination-timeout flag. Ensure simulator is booted first. | | Wrong simulator selected | Always use UDID from simctl list devices --json, not device name alone. | | Stale build artifacts | Use clean build action or delete derived data directory. |