Agent skill
using-xcode-cli
Builds and manages iOS/macOS apps using xcodebuild and xcrun simctl CLI tools. Use when working with Xcode projects, running apps in simulators, managing simulator instances, taking screenshots, capturing logs, running tests, or automating builds.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/using-xcode-cli
SKILL.md
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:
bash
xcrun simctl list devices available
Build for simulator:
bash
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:
bash
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:
bash
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
bash
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. |
Didn't find tool you were looking for?