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 packageCLI - 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
- Find simulator UDID via
simctl list devices --json - Boot simulator with
simctl boot $UDID - Build with
xcodebuildusing-derivedDataPath - Find .app bundle in derived data
- Install with
simctl install - 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. |