xcodebuild Reference

Xcode Toolchain Selection

Before you run any other command, make sure the shell is pointing at the right Xcode installation. xcode-select controls which toolchain every downstream tool (xcodebuild, xcrun, swift) will use.

Command	What	When
xcode-select -p	Print the path to the active Xcode developer directory	Confirming which Xcode version the shell is currently using
xcode-select -s <path>	Switch the active Xcode installation	Running CI with a specific Xcode version or testing a beta toolchain
xcode-select --install	Install the Xcode Command Line Tools	Setting up a fresh machine or CI runner without full Xcode
xcrun --sdk <sdk> --find <tool>	Locate a specific tool within an SDK	Finding the exact path to swift, clang, or another bundled tool
swift --version	Print the Swift compiler version	Confirming the toolchain version before building or reporting issues

# Check active Xcode path
xcode-select -p
# /Applications/Xcode.app/Contents/Developer

# Switch to a beta installation
sudo xcode-select -s /Applications/Xcode-beta.app/Contents/Developer

# Install CLI tools on a fresh machine
xcode-select --install

# Find the swift binary in the active SDK
xcrun --sdk iphoneos --find swift

# Confirm Swift version
swift --version
# swift-driver version: 1.90 Apple Swift version 5.10

---

Workspace & Project Setup

With the toolchain confirmed, discover the structure of your project before running any build or test action.

Flag / Command	What	When
xcodebuild -list	List all schemes, targets, and configurations in the project	First thing to run when you’re unfamiliar with a project’s structure
-workspace <x.xcworkspace>	Target a workspace file (CocoaPods, multi-project)	Any project that uses a .xcworkspace — always prefer over -project in this case
-project <x.xcodeproj>	Target a standalone Xcode project file	Projects that don’t use a workspace or CocoaPods
-scheme <name>	Select which scheme to build or test	Required for workspace invocations; pick the app or framework scheme
-target <name>	Select a specific target instead of a scheme	Useful when building a single library target without running the full scheme
-configuration <Debug|Release>	Choose the build configuration	Release for archives and distribution; Debug for day-to-day builds

# List everything available in the workspace
xcodebuild -list -workspace MyApp.xcworkspace

# List targets and configurations in a standalone project
xcodebuild -list -project MyLib.xcodeproj

---

Building

With a scheme selected, compile the app. You can do a full build, a test-only build, or a clean build to wipe stale artifacts.

Command	What	When
xcodebuild build	Compile the app for the selected scheme and destination	Verifying the project compiles before running tests
xcodebuild build-for-testing	Build the test bundle without running tests	CI pipelines that separate the build step from the test execution step
xcodebuild clean	Remove all build artifacts for the scheme	Forcing a clean state before an archive build or to fix stale build errors
xcodebuild clean build	Clean then immediately build	One command to guarantee a fresh compile
-destination	Specify where to run the build (simulator, device, generic)	Always required for build and test actions
-sdk <name>	Explicitly set the SDK to build against	Targeting iphoneos for device builds or iphonesimulator for sim

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

# Build for a generic iOS device (no specific device attached)
xcodebuild build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -destination 'generic/platform=iOS'

# Clean then build
xcodebuild clean build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest'

# Build test bundle only (no test execution)
xcodebuild build-for-testing \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest'

---

Testing

Once the code compiles, run your tests. You can run the full suite, split the build and run steps, or target a single test method.

Command	What	When
xcodebuild test	Build and run all tests in the scheme	Running the full test suite locally or in CI
xcodebuild test-without-building	Run previously built tests without recompiling	CI: second step after build-for-testing, avoids redundant compiles
-only-testing:<target>/<class>/<method>	Run a single test target, class, or method	Debugging a specific failing test without running the whole suite
-skip-testing:<target>/<class>	Exclude a target, class, or method from the run	Temporarily skipping a flaky test in CI while it is being fixed
-testPlan <name>	Use a named .xctestplan file	Running a specific test plan defined in Xcode (e.g. smoke vs. full)
-resultBundlePath <path>	Write the full test results to an .xcresult bundle	Preserving test results in CI for later analysis or reporting
-parallel-testing-enabled YES	Distribute tests across multiple simulator clones	Speeding up large test suites on machines with multiple cores

# Run all tests
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest'

# Run tests without rebuilding (after build-for-testing)
xcodebuild test-without-building \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest'

# Run only one test class
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -only-testing:MyAppTests/LoginTests

# Run only one specific test method
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -only-testing:MyAppTests/LoginTests/testValidCredentials

# Save results to a bundle for CI
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -resultBundlePath TestResults.xcresult

# Parallel testing with 4 simulator clones
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -parallel-testing-enabled YES \
  -parallel-testing-worker-count 4

---

Simulator Control (simctl)

Tests run on a simulator. Use simctl to boot, reset, and inspect simulators — either before a test run or to reproduce an issue by controlling the exact environment.

Command	What	When
xcrun simctl list	List all available simulators and their states	Finding the UDID or name of a simulator to use as a destination
xcrun simctl boot <udid>	Boot a specific simulator	Ensuring a simulator is ready before running UI tests
xcrun simctl shutdown <udid>	Shut down a running simulator	Cleaning up after tests in CI
xcrun simctl erase <udid>	Reset a simulator to factory state	Guaranteeing a clean state for reproducible test runs
xcrun simctl install <udid> <app>	Install an .app bundle on a simulator	Manually deploying a build for inspection or testing
xcrun simctl launch <udid> <bundle-id>	Launch an installed app on a simulator	Starting the app programmatically, optionally with arguments
xcrun simctl push <udid> <bundle-id> <payload.json>	Send a simulated push notification	Testing push notification handling without a real device or APNs
xcrun simctl io <udid> screenshot <file>	Take a screenshot of a running simulator	Capturing UI state for debugging or visual regression baselines
xcrun simctl delete unavailable	Remove all simulators for uninstalled Xcode runtimes	Reclaiming disk space after updating Xcode

# List all simulators
xcrun simctl list devices

# Boot a simulator by UDID
xcrun simctl boot "A1B2C3D4-..."

# Erase before a test run for a clean state
xcrun simctl erase "A1B2C3D4-..."

# Install and launch an app
xcrun simctl install booted ./build/MyApp.app
xcrun simctl launch booted com.example.MyApp

# Launch with arguments and environment variables
xcrun simctl launch booted com.example.MyApp \
  --args -UITesting \
  --env FEATURE_FLAG_LOGIN_V2=1

# Simulate a push notification
xcrun simctl push booted com.example.MyApp payload.json

# Screenshot
xcrun simctl io booted screenshot ./screenshots/home.png

# Clean up unavailable simulators
xcrun simctl delete unavailable

---

APNs Push Notification Payloads

Use xcrun simctl push booted <bundle-id> <payload.json> to fire any of these at a running simulator without a real device or APNs credentials. For physical devices, use curl against the APNs HTTP/2 API with a JWT or certificate.

Basic alert

// apns-alert.json
{
  "aps": {
    "alert": {
      "title": "New Message",
      "body": "Kyaw sent you a photo."
    },
    "sound": "default",
    "badge": 1
  }
}

xcrun simctl push booted com.example.MyApp apns-alert.json

---

Alert with subtitle and custom sound

// apns-subtitle.json
{
  "aps": {
    "alert": {
      "title": "Order Shipped",
      "subtitle": "Estimated delivery: tomorrow",
      "body": "Your order #4821 is on its way."
    },
    "sound": "chime.caf",
    "badge": 2
  }
}

xcrun simctl push booted com.example.MyApp apns-subtitle.json

---

Silent / background push

Background pushes wake your app without showing any visible notification. content-available: 1 is the only required key. alert, sound, and badge must be absent.

// apns-silent.json
{
  "aps": {
    "content-available": 1
  },
  "refresh": true,
  "payload_version": 2
}

xcrun simctl push booted com.example.MyApp apns-silent.json

---

Badge-only update

Update the app badge counter without showing an alert or playing a sound.

// apns-badge.json
{
  "aps": {
    "badge": 5
  }
}

xcrun simctl push booted com.example.MyApp apns-badge.json

# Clear the badge
echo '{"aps":{"badge":0}}' > apns-badge-clear.json
xcrun simctl push booted com.example.MyApp apns-badge-clear.json

---

Notification with action category

The category must match a UNNotificationCategory identifier registered in your app. Users see custom action buttons on long-press or in the notification centre.

// apns-category.json
{
  "aps": {
    "alert": {
      "title": "Friend Request",
      "body": "Alex wants to connect with you."
    },
    "sound": "default",
    "category": "FRIEND_REQUEST"
  },
  "sender_id": "user_9821",
  "sender_name": "Alex"
}

xcrun simctl push booted com.example.MyApp apns-category.json

---

Time-sensitive notification

Breaks through Focus modes (like Do Not Disturb). Requires the Time Sensitive Notifications entitlement in your app.

// apns-time-sensitive.json
{
  "aps": {
    "alert": {
      "title": "Verification Code",
      "body": "Your code is 482910. It expires in 5 minutes."
    },
    "sound": "default",
    "interruption-level": "time-sensitive"
  }
}

xcrun simctl push booted com.example.MyApp apns-time-sensitive.json

---

Critical alert

Plays a sound even when the device is muted or in Do Not Disturb. Requires an explicit entitlement granted by Apple.

// apns-critical.json
{
  "aps": {
    "alert": {
      "title": "Server Down",
      "body": "prod-api-01 is not responding."
    },
    "sound": {
      "name": "default",
      "critical": 1,
      "volume": 1.0
    },
    "interruption-level": "critical"
  }
}

xcrun simctl push booted com.example.MyApp apns-critical.json

---

Live Activity update

Updates a running Live Activity’s dynamic content. The content-state must match the ContentState type you defined in your ActivityAttributes conformance.

// apns-live-activity.json
{
  "aps": {
    "timestamp": 1718764800,
    "event": "update",
    "content-state": {
      "driverName": "Kyaw",
      "eta": "6 min",
      "status": "arriving"
    },
    "alert": {
      "title": "Almost there",
      "body": "Your driver is 6 minutes away."
    }
  }
}

# The bundle ID for a Live Activity push is the app's bundle ID
xcrun simctl push booted com.example.MyApp apns-live-activity.json

---

Sending to a real device via curl (APNs HTTP/2)

For physical devices you need a JWT (from your APNs Auth Key .p8 file) and the device token from didRegisterForRemoteNotificationsWithDeviceToken.

# --- generate JWT ---
TEAM_ID="ABCDE12345"
KEY_ID="FGHIJ67890"
KEY_FILE="./AuthKey_FGHIJ67890.p8"
BUNDLE_ID="com.example.MyApp"
DEVICE_TOKEN="abc123...64hexchars...def456"

# Build JWT header + payload (base64url encoded)
HEADER=$(echo -n '{"alg":"ES256","kid":"'"$KEY_ID"'"}' | openssl base64 -e -A | tr '+/' '-_' | tr -d '=')
NOW=$(date +%s)
PAYLOAD=$(echo -n '{"iss":"'"$TEAM_ID"'","iat":'"$NOW"'}' | openssl base64 -e -A | tr '+/' '-_' | tr -d '=')
SIGNING_INPUT="$HEADER.$PAYLOAD"
SIG=$(echo -n "$SIGNING_INPUT" | openssl dgst -sha256 -sign "$KEY_FILE" | openssl base64 -e -A | tr '+/' '-_' | tr -d '=')
JWT="$SIGNING_INPUT.$SIG"

# --- send the notification ---
curl --http2 \
  -H "apns-topic: $BUNDLE_ID" \
  -H "apns-push-type: alert" \
  -H "apns-priority: 10" \
  -H "authorization: bearer $JWT" \
  -d '{"aps":{"alert":{"title":"Hello","body":"Sent from curl"},"sound":"default"}}' \
  "https://api.push.apple.com/3/device/$DEVICE_TOKEN"

# apns-push-type values and when to use each:
#   alert          — standard visible notification
#   background     — silent push (content-available: 1)
#   voip           — VoIP call (requires PushKit entitlement)
#   complication   — watchOS complication update
#   fileprovider   — NSFileProviderManager change notification
#   mdm            — mobile device management command
#   location       — location push (iOS 15+)
#   liveactivity   — Live Activity create / update / end

---

Code Coverage

After a successful test run, measure what your tests actually exercise. Coverage reports tell you which lines and branches remain untested.

Command	What	When
-enableCodeCoverage YES	Enable code coverage data collection during tests	Generating coverage reports in CI or before a pull request
xcrun xccov view --report	Print a human-readable coverage summary from an .xcresult	Reviewing overall coverage percentages after a test run
xcrun xccov view --file <source>	Show coverage line-by-line for a specific source file	Identifying exactly which lines or branches are not covered
xcrun xccov merge	Merge multiple .xcresult bundles into one report	Combining unit and UI test coverage into a single view

# Run tests with coverage enabled
xcodebuild test \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -enableCodeCoverage YES \
  -resultBundlePath TestResults.xcresult

# Print overall coverage report
xcrun xccov view --report TestResults.xcresult

# Coverage for a single file
xcrun xccov view --file MyApp/Sources/LoginViewModel.swift TestResults.xcresult

# Export as JSON (useful for third-party tools)
xcrun xccov view --report --json TestResults.xcresult > coverage.json

---

Build Settings & Output

Tune how the build runs and what it produces. These flags control compiler flags, warning policies, derived data location, and output verbosity.

Flag	What	When
-showBuildSettings	Print all resolved build settings for the scheme	Debugging which SDK, signing identity, or path Xcode is actually using
OTHER_SWIFT_FLAGS="-D FLAG"	Inject a Swift compiler flag at the command line	Enabling a compile-time flag without modifying the project file
SWIFT_TREAT_WARNINGS_AS_ERRORS=YES	Fail the build on any Swift warning	Enforcing a zero-warning policy in CI
-quiet	Suppress most build output; show only warnings and errors	Cleaner CI logs when you only care about failures
-verbose	Print every build command as it runs	Debugging build system issues or unexpected tool invocations
DERIVED_DATA_PATH=<path>	Override the derived data directory	Isolating build artifacts per branch or keeping CI workspaces clean

# Print all resolved build settings
xcodebuild -showBuildSettings \
  -workspace MyApp.xcworkspace \
  -scheme MyApp

# Inject a compile-time flag
xcodebuild build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'generic/platform=iOS' \
  OTHER_SWIFT_FLAGS="-DENABLE_EXPERIMENTS"

# Fail on warnings in CI
xcodebuild build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'generic/platform=iOS' \
  SWIFT_TREAT_WARNINGS_AS_ERRORS=YES

# Clean CI derived data location
xcodebuild build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'generic/platform=iOS' \
  DERIVED_DATA_PATH=./build/DerivedData

# Quiet output — only warnings and errors
xcodebuild build \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'generic/platform=iOS' \
  -quiet

---

Code Signing & Certificates

Before you can distribute a build, it must be signed. These commands inspect and verify signing identities, then handle the Apple notarization flow for macOS apps.

Command	What	When
security find-identity -v -p codesigning	List all valid code-signing identities in the keychain	Verifying which certificates are installed and usable before a build
codesign -dv <app>	Display the code signing details of an app bundle	Inspecting the signing identity and entitlements on a built artifact
codesign --verify <app>	Verify that an app bundle is correctly signed	Checking a build before submission to catch signing errors early
xcrun notarytool submit	Submit an app for Apple notarisation	Required before distributing a macOS app outside the App Store
xcrun notarytool wait	Wait for a notarisation request to complete	Blocking a CI step until Apple’s notary service finishes
xcrun stapler staple	Attach the notarisation ticket to the app bundle	Final step before distributing a notarised macOS app

# List signing identities
security find-identity -v -p codesigning
# 1) ABC123... "Apple Distribution: My Company (TEAM123)"
# 2) DEF456... "Apple Development: kyaw@example.com (TEAM123)"

# Inspect signing on a built app
codesign -dv --verbose=4 ./build/MyApp.app

# Verify signing
codesign --verify --deep --strict ./build/MyApp.app

# Notarise a macOS app (stored credentials)
xcrun notarytool submit MyApp.zip \
  --keychain-profile "notarytool-profile" \
  --wait

# Staple the ticket once notarisation is approved
xcrun stapler staple MyApp.app

---

Archiving & Exporting

The final step: produce a release-ready archive and export it as a distributable .ipa or .app for App Store Connect, TestFlight, or ad-hoc distribution.

Command	What	When
xcodebuild archive	Build a release .xcarchive	Preparing a build for App Store submission or ad-hoc distribution
-archivePath <path>	Set where the .xcarchive is written	Always specify to control output location in CI
xcodebuild -exportArchive	Export an .ipa from an existing .xcarchive	Converting an archive to a distributable .ipa after signing
-exportOptionsPlist <path>	Provide export options (method, signing identity, provisioning)	Required for -exportArchive; defines App Store vs ad-hoc vs enterprise
-exportPath <path>	Set the output directory for the exported .ipa	Controlling where CI places the final distributable artifact

# Step 1 — archive
xcodebuild archive \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath ./build/MyApp.xcarchive

# Step 2 — export .ipa
xcodebuild -exportArchive \
  -archivePath ./build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath ./build/ipa/

<!-- ExportOptions.plist (App Store upload) -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>app-store-connect</string>
  <key>teamID</key>
  <string>ABCDE12345</string>
  <key>uploadSymbols</key>
  <true/>
  <key>compileBitcode</key>
  <false/>
</dict>
</plist>