/native

xcrun — Xcode / Apple Toolchain CLI Reference

Production-grade reference for the xcrun wrapper and its most-used subtools (simctl, devicectl, xctrace, xcresulttool, notarytool, plus binary-introspection helpers). Focus: commands a native iOS developer or CI script actually runs day-to-day.

Scope: iOS / macOS / watchOS / tvOS development from terminal or CI. Use this when scripting simulator/device automation, parsing test results, symbolicating crashes, or shipping to App Store Connect from headless environments.

0. Base Mechanics

• Role: resolves the current DEVELOPER_DIR / SDK and runs the appropriate internal tool.
• Switch active Xcode: sudo xcode-select -s /Applications/Xcode_16.app
• Locate a tool: xcrun --find <tool> (e.g. xcrun --find swift)
• Inspect SDK: xcrun --show-sdk-path / xcrun --show-sdk-version
• Target a specific SDK: xcrun --sdk iphonesimulator <command> / --sdk iphoneos / --sdk macosx
• Environment override: DEVELOPER_DIR=/Applications/Xcode-beta.app xcrun ... (no sudo needed; per-process)

1. simctl — Simulator Control (most-used)

Recipe: automated screen recording

UDID=$(xcrun simctl list devices booted -j | jq -r '.devices | to_entries[] | .value[0].udid')
xcrun simctl launch "$UDID" com.example.app &
xcrun simctl io "$UDID" recordVideo demo.mp4

Recipe: clean App Store screenshot session

UDID=...
xcrun simctl status_bar "$UDID" override \
  --time "9:41" --dataNetwork wifi --wifiMode active --wifiBars 3 \
  --cellularMode active --cellularBars 4 --batteryState charged --batteryLevel 100
# ... run UI test that calls xcrun simctl io screenshot per scene
xcrun simctl status_bar "$UDID" clear

2. devicectl — Physical Device Control (Xcode 15+, replaces idevice* / ios-deploy)

Migration note: prefer devicectl for new CI. Legacy ios-deploy shows instability on M1/M2/M3 Macs with iOS 17+; replace it where possible.

3. xctrace — Instruments as a CLI (performance / leaks)

→ One of the few ways to gate Time Profiler / Allocations regressions in CI.

4. xcresulttool — Test Result Parsing

→ Pair with xcodebuild test ... -resultBundlePath Result.xcresult to parse pass/fail counts, durations, and attachments in CI.

5. altool / notarytool — App Store Submission + macOS Notarization

6. Binary Introspection (debugging / forensics)

7. xcodebuild (not via xcrun, but always co-used)

# Build for simulator
xcodebuild -workspace App.xcworkspace -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' \
  -configuration Debug build

# Test with result bundle (machine-readable)
xcodebuild test -workspace App.xcworkspace -scheme AppTests \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' \
  -resultBundlePath TestResults.xcresult -enableCodeCoverage YES

# Archive + export
xcodebuild archive -workspace App.xcworkspace -scheme App \
  -configuration Release -archivePath build/App.xcarchive
xcodebuild -exportArchive -archivePath build/App.xcarchive \
  -exportOptionsPlist exportOptions.plist -exportPath build/export

# Export App Store Connect localization XLIFF (handoff to Polyglot)
xcodebuild -exportLocalizations -project App.xcodeproj -localizationPath ./l10n -includeScreenshots

8. Gotchas

1. xcrun looks up tools in active Xcode only — xcode-select -p to verify. CI runners with multiple Xcodes installed (via xcodes) require explicit DEVELOPER_DIR=... per build.
2. simctl push payload format — must be a top-level aps dict; if you copy a server payload that's already wrapped, strip the wrapper. Bundle ID arg is mandatory.
3. Booted device disambiguation — simctl io booted screenshot works when exactly one device is booted; with multiple, use explicit UDID.
4. devicectl vs idb — Apple's devicectl covers basic install/launch/console, but Facebook's idb is still richer for UI automation (touch / swipe / record events). Pick devicectl for CI signing/install paths, idb for E2E test orchestration.
5. xctrace record --launch vs --attach — --launch requires the .app bundle path, not the bundle ID. --attach accepts pid only on a known device.
6. xcresulttool schema breaking changes — Xcode 16 introduced a new structure under actions._values; pin your parser to the Xcode version or use xcresulttool get --legacy for the older shape.
7. notarytool keychain profile — xcrun notarytool store-credentials "AC_KEY" once saves Apple ID + app-specific password to Keychain; subsequent calls use --keychain-profile AC_KEY instead of inline credentials.
8. atos requires the matching dSYM UUID — dwarfdump --uuid on the dSYM must equal the crash report's binary UUID. Mismatch produces nonsensical symbols silently.

Cross-References

• reference/mobile-ci-cd.md — Xcode Cloud / fastlane / GitHub Actions pipeline integration
• reference/release-rollout.md — TestFlight phased release that consumes notarytool / altool output
• reference/adb-cli.md — Android counterpart (side-by-side iOS ↔ Android command mapping at bottom of that file)
• Apple official: https://developer.apple.com/documentation/xcode-release-notes