Prepare your iPhone

Start with standard mode. Development signing is only required for Runner.

Before you start

Install full Xcode and open it once to finish installation. Select it in Xcode Settings → Locations. xcode-select -p should end in the app’s Contents/Developer; Command Line Tools alone are insufficient.
Connect the iPhone over USB, trust the Mac, enable Developer Mode and keep the phone unlocked.
Only for Runner mode: have an Apple Development certificate and its private key in Keychain, plus an iOS development profile authorizing that certificate, device and Runner bundle ID.

First-time trust, Developer Mode, Apple sign-in and permission dialogs require your action on the devices. Fresh-Mac and free Personal Team setup and renewal are not yet validated.

Connect in standard mode

iphone-use devices
export IOS_UDID='YOUR_DEVICE_ID'
iphone-use connect --device "$IOS_UDID" --mode standard

Use the actual device ID. Check controlAvailable=true, keep the returned session ID, observe, then disconnect when done. Standard mode never starts Runner or silently falls back to XCTest. New users default to standard; specify the mode explicitly when an old preference may exist.

iphone-use --session "SESSION_FROM_CONNECT" observe
iphone-use --session "SESSION_FROM_CONNECT" disconnect

Optional Runner setup

Setup uses existing credentials; it does not log in to Apple or create certificates or profiles. If Xcode has no suitable cached profile, prepare one through your development team’s Apple development profile workflow.

iphone-use setup --device "$IOS_UDID" \
  --profile '/absolute/path/to/development.mobileprovision' \
  --team 'YOUR_TEAM_ID'

The default Runner bundle ID is com.iphone-use.runner.xctrunner. If your profile authorizes another ID, also pass --bundle-id 'com.example.iphone-use.xctrunner'. --identity takes a matching development certificate’s SHA-1 identifier, not private key contents.

iphone-use connect --device "$IOS_UDID" --mode runner

Saved preparation

Preparation is stored in ~/Library/Application Support/iphone-use; the private key stays in Keychain. Later connections reuse successful preparation. Expired profiles, changed Runner files or package upgrades may require setup again.

Do not use build-runner to work around a release-package setup error. Source development is a different workflow. Follow the actual diagnostic.