name: run-ios-simulator description: Build and run an iPlug2 iOS app in the iOS Simulator

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:

   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:

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

3. Build for Simulator:

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

4. Find the built app:

   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"):

   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):

   # 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