Command	Synopsis	Notes
`list`	`simctl list [devices\|devicetypes\|runtimes\|pairs] [search-term]`	Add `-j` for JSON. Add `available` to filter to usable devices.
`create`	`simctl create <name> <device-type-id> [<runtime-id>]`	Returns the new UDID. Omitting runtime selects the newest compatible one.
`clone`	`simctl clone <UDID> <new-name>`	Copies device state including installed apps.
`delete`	`simctl delete <UDID\|unavailable\|all>`	`unavailable` removes devices whose runtime is missing.
`rename`	`simctl rename <UDID> <new-name>`
`erase`	`simctl erase <UDID\|all>`	Factory reset — wipes apps and data, keeps the device.
`boot`	`simctl boot <UDID>`	Starts the device runtime.
`shutdown`	`simctl shutdown <UDID\|all>`	Stops the device runtime.
`upgrade`	`simctl upgrade <UDID> <runtime-id>`	Upgrades device to a newer runtime.
`pair`	`simctl pair <watch-UDID> <phone-UDID>`	Pairs a watchOS simulator with an iOS simulator.
`unpair`	`simctl unpair <pair-UDID>`	Removes a watch/phone pairing.

Device Type and Runtime IDs

# List all device types — use the identifier column
xcrun simctl list devicetypes

# Example output line:
# iPhone 16 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro)

# List all runtimes
xcrun simctl list runtimes

# Example output line:
# iOS 18.4 - com.apple.CoreSimulator.SimRuntime.iOS-18-4

Use the identifier strings (e.g., com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro) in create and upgrade commands.

App Lifecycle Commands

Command	Synopsis	Notes
`install`	`simctl install <UDID> <path-to-.app>`	Device must be booted. Path is a `.app` directory, not `.ipa`.
`uninstall`	`simctl uninstall <UDID> <bundle-id>`	Removes app and its data.
`launch`	`simctl launch [--console] [--terminate-running-process] <UDID> <bundle-id> [args...]`	`--console` streams stdout/stderr. `--terminate-running-process` kills existing instance first.
`terminate`	`simctl terminate <UDID> <bundle-id>`	Sends SIGTERM to the running app.
`spawn`	`simctl spawn <UDID> <path-to-binary> [args...]`	Runs an arbitrary binary inside the simulator. Used for `log stream`.
`get_app_container`	`simctl get_app_container <UDID> <bundle-id> [app\|data\|groups\|<group-id>]`	Returns the filesystem path to the container. `groups` lists all App Group containers.
`appinfo`	`simctl appinfo <UDID> <bundle-id>`	Prints Info.plist-derived information as JSON.

Launch Arguments and Environment

# Pass launch arguments (received as CommandLine.arguments)
xcrun simctl launch booted com.example.MyApp --reset-onboarding --debug-mode

# Override language and locale
xcrun simctl launch booted com.example.MyApp -AppleLanguages "(ja)" -AppleLocale "ja_JP"

# Set environment variables via spawn
xcrun simctl spawn booted env MY_VAR=value /path/to/MyApp.app/MyApp

Testing and Simulation Commands

Command	Synopsis	Notes
`push`	`simctl push <UDID> <bundle-id> <payload.json\|->`	Simulates local push delivery. Use `-` for stdin.
`openurl`	`simctl openurl <UDID> <URL>`	Triggers universal links or custom URL schemes.
`location`	`simctl location <UDID> <set\|clear\|list\|run\|start> [args]`	`set <lat,lon>`, `run <scenario>`, `list`, `start`, or `clear`.
`privacy`	`simctl privacy <UDID> <grant\|revoke\|reset> <service> <bundle-id>`	See Privacy Service Names for service values.
`keychain`	`simctl keychain <UDID> <add-root-cert\|add-cert\|reset> [cert-path]`	Manages trusted certificates in the simulator keychain.
`status_bar`	`simctl status_bar <UDID> <override\|clear> [flags]`	See Status Bar Override Flags.

Push Payload Format

The JSON payload mirrors the APNs payload format. The Simulator Target Bundle key is optional — when provided, the bundle ID argument can be omitted:

{
    "Simulator Target Bundle": "com.example.MyApp",
    "aps": {
        "alert": {
            "title": "Order Update",
            "subtitle": "Order #1234",
            "body": "Your order has been shipped"
        },
        "badge": 1,
        "sound": "default",
        "category": "ORDER_STATUS",
        "thread-id": "order-1234",
        "interruption-level": "time-sensitive"
    },
    "orderID": "1234"
}

Location Scenarios

The run subcommand accepts predefined scenario names, not GPX file paths:

# List available predefined scenarios
xcrun simctl location booted list

# Run a predefined scenario
xcrun simctl location booted run "City Run"

# Set a fixed coordinate
xcrun simctl location booted set 37.3349,-122.0090

# Clear the simulated location
xcrun simctl location booted clear

Available scenarios include "City Run", "City Bicycle Ride", "Freeway Drive", and "Apple" (stationary at Apple Park). Use list to see all options on your system.

For custom routes using GPX files, use Xcode's Debug > Simulate Location menu instead of simctl location run.

Media and IO Commands

Command	Synopsis	Notes
`io screenshot`	`simctl io <UDID> screenshot [--type png\|jpeg\|tiff\|bmp\|gif] [--mask ignored\|alpha\|black] <path>`	Default type is png.
`io recordVideo`	`simctl io <UDID> recordVideo [--codec h264\|hevc] [--mask ignored\|alpha\|black] [--force] <path>`	Ctrl+C to stop. `--force` overwrites existing files.
`addmedia`	`simctl addmedia <UDID> <path> [path...]`	Adds photos, live photos, videos, or contacts to the device. Supports PNG, JPEG, GIF, MOV, MP4, and vCard.

Mask Options

Value	Effect
`ignored`	No mask applied (default). Full rectangular capture.
`alpha`	Transparent pixels where the device bezel would be. Produces PNG with alpha channel. Not supported for video recording — falls back to `black`.
`black`	Black pixels where the device bezel would be. Works with JPEG.

JSON Output Parsing

Find a Booted Device UDID

xcrun simctl list -j devices booted | \
    jq -r '[.devices[][] | select(.state == "Booted")] | first | .udid'

Find a Device by Name and Runtime

RUNTIME="com.apple.CoreSimulator.SimRuntime.iOS-18-4"
xcrun simctl list -j devices available | \
    jq -r --arg rt "$RUNTIME" \
    '.devices[$rt][] | select(.name == "iPhone 16 Pro") | .udid'

List All Available Runtimes

xcrun simctl list -j runtimes | \
    jq -r '.runtimes[] | select(.isAvailable == true) | "\(.name) — \(.identifier)"'

Get Device State

xcrun simctl list -j devices | \
    jq -r --arg udid "$UDID" \
    '[.devices[][] | select(.udid == $udid)] | first | .state'

Privacy Service Names

Service names accepted by simctl privacy grant|revoke|reset:

Service	Description
`all`	All services (reset only)
`calendar`	EventKit calendar access
`contacts-limited`	Limited contacts access
`contacts`	Full contacts access
`location`	When-in-use location access
`location-always`	Always location access
`photos-add`	Add-only photo library access
`photos`	Full photo library access
`media-library`	Apple Music / media library
`microphone`	Microphone access
`motion`	Core Motion activity data
`reminders`	EventKit reminders access
`siri`	Siri integration

Status Bar Override Flags

All flags for simctl status_bar <UDID> override:

Flag	Type	Example
`--time`	String	`"9:41"`
`--dataNetwork`	String	`hide`, `wifi`, `3g`, `4g`, `lte`, `lte-a`, `lte+`, `5g`, `5g+`, `5g-uc`, `5g-uwb`
`--wifiMode`	String	`searching`, `failed`, `active`
`--wifiBars`	Integer	`0`–`3`
`--cellularMode`	String	`notSupported`, `searching`, `failed`, `active`
`--cellularBars`	Integer	`0`–`4`
`--operatorName`	String	`""` (empty for clean screenshots)
`--batteryState`	String	`charging`, `charged`, `discharging`
`--batteryLevel`	Integer	`0`–`100`

App Store Screenshot Preset

xcrun simctl status_bar booted override \
    --time "9:41" \
    --batteryState charged \
    --batteryLevel 100 \
    --cellularMode active \
    --cellularBars 4 \
    --wifiMode active \
    --wifiBars 3 \
    --dataNetwork wifi \
    --operatorName ""

Troubleshooting

Stuck "Booting" State

The device shows state "Booting" and simctl boot returns "Unable to boot device in current state: Booting."

# Step 1: force shutdown
xcrun simctl shutdown <UDID>

# Step 2: erase the device
xcrun simctl erase <UDID>

# Step 3: boot again
xcrun simctl boot <UDID>

If erasing does not resolve it, delete and recreate the device. As a last resort, clear the CoreSimulator caches:

xcrun simctl shutdown all
rm -rf ~/Library/Developer/CoreSimulator/Caches

Runtime Not Installed

simctl create or simctl boot fails with "Invalid runtime" or the runtime does not appear in simctl list runtimes.

# Check what's installed
xcrun simctl list runtimes

# Download a runtime via xcodebuild
xcodebuild -downloadPlatform iOS

# Or download via Xcode > Settings > Platforms

Runtime downloads can be large (5+ GB). In CI, pre-install runtimes in the base image.

CoreSimulator Cache Corruption

Symptoms: devices fail to boot, simctl list shows stale data, or "Unable to determine simulator device status."

# Nuclear option — reset everything
xcrun simctl shutdown all
xcrun simctl erase all
rm -rf ~/Library/Developer/CoreSimulator/Caches
# Restart CoreSimulatorService
launchctl kickstart -k gui/$(id -u)/com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true

After clearing caches, you may need to re-create custom devices. Default devices are recreated automatically by Xcode.

"Unable to boot device in current state: Shutdown"

This usually means the required runtime is not fully installed or is corrupted. Verify the runtime is available and re-download if needed:

xcrun simctl list runtimes
# If the runtime shows (unavailable), re-download it
xcodebuild -downloadPlatform iOS

skills

accessorysetupkit

activitykit

adattributionkit

alarmkit

app-clips

app-intents

app-store-optimization

app-store-review

apple-on-device-ai

appmigrationkit

audioaccessorykit

authentication

avkit

background-processing

browserenginekit

callkit

carplay

cloudkit

contacts-framework

core-bluetooth

core-data

core-motion

core-nfc

coreml

cryptokit

cryptotokenkit

debugging-instruments

device-integrity

dockkit

energykit

eventkit

financekit

focus-engine

gamekit

healthkit

homekit

ios-accessibility

ios-localization

ios-networking

ios-simulator

references

simctl-commands.md

SKILL.md

mapkit

metrickit

musickit

natural-language

paperkit

passkit

pdfkit

pencilkit

permissionkit

photokit

push-notifications

realitykit

relevancekit

scenekit

sensorkit

shareplay-activities

speech-recognition

spritekit

storekit

swift-api-design-guidelines

swift-architecture

swift-charts

swift-codable

swift-concurrency

swift-formatstyle

swift-language

swift-security

swift-testing

swiftdata

swiftlint

swiftui-animation

swiftui-gestures

swiftui-layout-components

swiftui-liquid-glass

swiftui-patterns

swiftui-performance

swiftui-uikit-interop

swiftui-webkit

tabletopkit

tipkit

vision-framework

weatherkit

widgetkit

CHANGELOG.md

README.md

tile.json

dpearson2699/swift-ios-skills

simctl-commands.mdskills/ios-simulator/references/

simctl Command Reference

Contents

Device Management Commands

Device Type and Runtime IDs

App Lifecycle Commands

Launch Arguments and Environment

Testing and Simulation Commands

Push Payload Format

Location Scenarios

Media and IO Commands

Mask Options

JSON Output Parsing

Find a Booted Device UDID

Find a Device by Name and Runtime

List All Available Runtimes

Get Device State

Privacy Service Names

Status Bar Override Flags

App Store Screenshot Preset

Troubleshooting

Stuck "Booting" State

Runtime Not Installed

CoreSimulator Cache Corruption

"Unable to boot device in current state: Shutdown"

dpearson2699/swift-ios-skills

simctl-commands.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}skills/ios-simulator/references/

simctl Command Reference

Contents

Device Management Commands

Device Type and Runtime IDs

App Lifecycle Commands

Launch Arguments and Environment

Testing and Simulation Commands

Push Payload Format

Location Scenarios

Media and IO Commands

Mask Options

JSON Output Parsing

Find a Booted Device UDID

Find a Device by Name and Runtime

List All Available Runtimes

Get Device State

Privacy Service Names

Status Bar Override Flags

App Store Screenshot Preset

Troubleshooting

Stuck "Booting" State

Runtime Not Installed

CoreSimulator Cache Corruption

"Unable to boot device in current state: Shutdown"

simctl-commands.mdskills/ios-simulator/references/