Run iOS App in Simulator

Use this skill when the user wants to run an iPlug2 iOS project in the iOS Simulator.

Workflow

1. Identify the project:

   • If not specified, look for .xcworkspace files in the repo root
   • Ask user to choose if multiple projects exist

2. Check available simulators and get UDID:

   bashCopy

   xcrun simctl list devices available | grep -E "iPhone|iPad"
   

   Extract the UDID from the output (the value in parentheses, e.g., 9E866BC3-9E64-4608-B4D0-D20F1DE3E980)

   Or programmatically:

   bashCopy

   xcrun simctl list devices available -j | jq -r '.devices[] | .[] | select(.name=="[DeviceName]") | .udid'
   

3. Build for Simulator:

   bashCopy

   xcodebuild -workspace [Project]/[Project].xcworkspace \
     -scheme "iOS-APP with AUv3" \
     -configuration Debug \
     -destination 'platform=iOS Simulator,name=[DeviceName]' \
     build
   

4. Find the built app:

   bashCopy

   find ~/Library/Developer/Xcode/DerivedData -name "[Project].app" -path "*Debug-iphonesimulator*" -type d 2>/dev/null | head -1
   

5. Boot simulator and install (use UDID, not "booted"):

   bashCopy

   open -a Simulator
   xcrun simctl boot [UDID] 2>/dev/null || true
   xcrun simctl install [UDID] "[path/to/Project.app]"
   

   Using the UDID ensures the correct simulator is targeted even when multiple are running.

6. Launch the app (use UDID):

   bashCopy

   # Get bundle ID from Info.plist
   /usr/libexec/PlistBuddy -c "Print :CFBundleIdentifier" "[path/to/Project.app]/Info.plist"
   xcrun simctl launch [UDID] [bundle.identifier]
   

Notes

• No code signing required for Simulator builds
• Always use UDID to target a specific simulator, not booted
• Default device: iPhone 17 Pro (or latest available)
• The AUv3 plugin is embedded in the app and will be available to host apps in the Simulator
• Use xcrun simctl list devices available to see all device options
• If jq is not installed, extract UDID manually from xcrun simctl list devices available output

Example

For TemplateProject on iPhone 17 Pro:

# Get the UDID for iPhone 17 Pro
UDID=$(xcrun simctl list devices available -j | jq -r '.devices[] | .[] | select(.name=="iPhone 17 Pro") | .udid')

# Build
xcodebuild -workspace TemplateProject/TemplateProject.xcworkspace \
  -scheme "iOS-APP with AUv3" -configuration Debug \
  -destination "platform=iOS Simulator,id=$UDID" build

# Install and run using UDID
open -a Simulator
xcrun simctl boot $UDID 2>/dev/null || true
xcrun simctl install $UDID ~/Library/Developer/Xcode/DerivedData/TemplateProject-*/Build/Products/Debug-iphonesimulator/TemplateProject.app
xcrun simctl launch $UDID com.AcmeInc.TemplateProject