ios-simulator

name	ios-simulator
description	Control the iOS Simulator using xcrun simctl. Use when asked to take a screenshot of the simulator, navigate to a screen, open a deep link, launch or kill an app, control the status bar, list simulators, or interact with the running iOS simulator. Trigger terms: simulator, xcrun, simctl, screenshot simulator, deep link, open app, navigate mobile.

iOS Simulator Control

Controls the iOS Simulator via xcrun simctl. All commands target the booted device unless a UDID is specified.

Quick Reference

See commands.md for the full command reference.

Core Workflow

1. Verify a simulator is booted

xcrun simctl list devices | grep Booted

If nothing is booted, boot one:

# List available devices first
xcrun simctl list devices available

# Boot by UDID or name
xcrun simctl boot "iPhone 16"
open -a Simulator

2. Take a screenshot

xcrun simctl io booted screenshot /tmp/screen.png

Then read the image to show it to the user:

# After running the screenshot command, use the Read tool on the file path

Always show the screenshot to the user after taking it.

3. Navigate via deep link

Expo dev build (Metro running on 8081):

xcrun simctl openurl booted "exp://localhost:8081/--/<route>"

Examples:

xcrun simctl openurl booted "exp://localhost:8081/--/training"
xcrun simctl openurl booted "exp://localhost:8081/--/nutrition"
xcrun simctl openurl booted "exp://localhost:8081/--/profile"

Production / preview build (custom scheme):

xcrun simctl openurl booted "myheavyduty://training"

Generic web URL:

xcrun simctl openurl booted "https://example.com"

Important: Custom app schemes (myheavyduty://) fail in Expo dev mode with LSApplicationWorkspaceErrorDomain error 115. Always use exp://localhost:8081/--/<path> for development.

4. Launch / terminate an app

# Find the bundle ID
xcrun simctl listapps booted | grep -A3 "MyHeavyDuty\|heavyduty"

# Launch
xcrun simctl launch booted <bundle-id>

# Terminate
xcrun simctl terminate booted <bundle-id>

5. Status bar overrides

# Set clean demo status bar
xcrun simctl status_bar booted override \
  --time "9:41" \
  --batteryState charged \
  --batteryLevel 100 \
  --wifiBars 3 \
  --cellularMode active \
  --cellularBars 4

# Clear overrides (restore real status bar)
xcrun simctl status_bar booted clear

What Does NOT Exist

• xcrun simctl tap — not a valid subcommand
• xcrun simctl io booted tap — not a valid io operation
• Gesture simulation (swipe, pinch, long press) — requires Detox or accessibility access

Tapping / Gestures

simctl cannot simulate taps. Alternatives:

1. AppleScript (requires Terminal to have Accessibility permission in System Settings → Privacy):

osascript -e 'tell application "System Events" to tell process "Simulator" to click at {x, y}'

2. Deep link — preferred: navigate directly instead of tapping.

3. Detox — for full E2E tap automation.

Common Patterns

Screenshot after navigation

xcrun simctl openurl booted "exp://localhost:8081/--/training"
sleep 2
xcrun simctl io booted screenshot /tmp/training.png

Then use Read tool to show /tmp/training.png.

Check what's installed

xcrun simctl listapps booted | grep -i heavy

Device info

xcrun simctl list devices | grep Booted