Run Device

Run on a Physical Device (CLI)

Builds, signs, installs, and launches an app on a connected physical device straight from the terminal — no Xcode Run button. The companion run-simulator skill covers the Simulator; this is the hardware path, which uses a different toolchain: devicectl (not simctl), real code signing, and an external tool for screenshots.

Building proves the code typechecks and signs; launching proves it installs and runs on real hardware. A crash on launch or a failed install is a failure.

When This Skill Activates

Use when the user wants to:

• Run / test their app on a real iPhone or iPad from the CLI
• Install a build on a device without opening Xcode
• Reproduce a device-only bug (camera, sensors, performance, push)
• Screenshot the app running on hardware

Not for the Simulator (use run-simulator) and not for xcodebuild test.

Prerequisites (one-time, partly interactive — cannot be scripted)

1. Device connected by USB (or paired over Wi-Fi).
2. Developer Mode ON (iOS 16+): Settings → Privacy & Security → Developer Mode → on → restart. There is no CLI to enable this.
3. Device trusted/paired: the first connection shows "Trust This Computer?" on the device — tap Trust. devicectl pairs once trusted.
4. Automatic signing configured: the target needs CODE_SIGN_STYLE = Automatic and a DEVELOPMENT_TEAM, and the signing Apple ID must already be logged into Xcode (Settings → Accounts) so -allowProvisioningUpdates can mint profiles. A free personal team works but apps expire after 7 days.

Confirm reachability before building:

xcrun devicectl list devices

The Identifier column is a CoreDevice UUID (e.g. A1B2C3D4-…). It is used by devicectl for install/launch. It is NOT the value xcodebuild wants — see the trap in step 2. Pick a row whose State is available (paired) / connected.

Process

1. Pick the device identifier

xcrun devicectl list devices    # grab the Identifier (CoreDevice UUID) of the paired device

Store it: DEV=<identifier-from-the-Identifier-column>.

2. Build + sign for a device

Trap: xcodebuild matches on the hardware UDID, not the devicectl identifier. Passing -destination 'platform=iOS,id=<devicectl-id>' fails with "Unable to find a device matching the provided destination specifier." Build for a generic device instead — it produces the same signed .app:

xcodebuild build \
  -project MyApp.xcodeproj -scheme MyApp \
  -destination 'generic/platform=iOS' \
  -allowProvisioningUpdates 2>&1 | tail -5

(Use -workspace MyApp.xcworkspace instead of -project if the project has one.) Look for ** BUILD SUCCEEDED **. -allowProvisioningUpdates lets xcodebuild register the device and create/refresh the provisioning profile automatically.

Common failures:

• "Signing requires a development team" → set DEVELOPMENT_TEAM=XXXXXXXXXX on the command line, or fix it in project settings.
• "No profiles for '…' were found" → add -allowProvisioningUpdates (above), and make sure the signing Apple ID is logged into Xcode.

3. Resolve the built .app (device build → Debug-iphoneos)

Don't guess DerivedData — read it from build settings. Note the directory is Debug-iphoneos for device builds (vs Debug-iphonesimulator for the Simulator):

eval $(xcodebuild -project MyApp.xcodeproj -scheme MyApp \
  -destination 'generic/platform=iOS' -showBuildSettings 2>/dev/null \
  | awk -F' = ' '/ TARGET_BUILD_DIR =/{print "DIR=\""$2"\""} / FULL_PRODUCT_NAME =/{print "NAME=\""$2"\""}')
APP="$DIR/$NAME"   # .../Debug-iphoneos/MyApp.app
BID=$(/usr/libexec/PlistBuddy -c "Print :CFBundleIdentifier" "$APP/Info.plist")

4. Install

xcrun devicectl device install app --device "$DEV" "$APP"

Prints App installed: with the bundleID and installationURL on success.