---
name: ios-simulator
description: "xcrun simctl from the command line: create, boot, erase and delete devices, install and launch apps, simulated pushes without APNs, GPS locations and routes, granting or resetting privacy permissions, openurl deep links, status bar overrides, screenshots and video, os_log streaming, app containers, targetEnvironment(simulator), boot and CoreSimulator failures. Use when scripting simulators for tests or CI or deciding what needs real hardware. Not for Instruments profiling, real APNs setup, or push-server, Core Bluetooth or Core Motion code."
metadata:
  source: multi-agent-pipeline
---

# iOS Simulator with simctl

`xcrun simctl` controls simulators without the Simulator app's menus, which is
what test scripts and CI need. This skill covers the device lifecycle, app
installation, the simulation commands, capture, logs, the compile-time
simulator check, and where the simulator stops being a stand-in for hardware.

Every subcommand, flag table, jq recipe and troubleshooting step is in
`references/simctl-commands.md`.

## Devices

### What is installed

```bash
xcrun simctl list devices available
xcrun simctl list runtimes
xcrun simctl list devices booted
xcrun simctl list devices available -j
```

The first groups usable devices by runtime, the second lists runtimes, the
third shows only running devices, and `-j` switches to JSON for scripts
(parse it with `jq`; recipes in the reference).

### Making a device

```bash
xcrun simctl list devicetypes
SIM=$(xcrun simctl create "Checkout iPad" "iPad Air 11-inch (M3)" com.apple.CoreSimulator.SimRuntime.iOS-26-0)
echo "$SIM"
```

`create` prints the new device's UDID; keep it and pass it to later commands.
Device type and runtime strings above are examples only, so read the real
ones from `list devicetypes` and `list runtimes` on the machine. A descriptive
name makes devices easy to tell apart.

### Boot, stop, wipe, remove

| Command | Effect |
|---|---|
| `xcrun simctl boot "$SIM"` | Starts the device |
| `xcrun simctl bootstatus "$SIM" -b` | Boots when necessary, then waits for boot to finish |
| `xcrun simctl shutdown "$SIM"` / `shutdown all` | Stops one device / every device |
| `xcrun simctl erase "$SIM"` | Factory reset: data gone, device kept |
| `xcrun simctl delete "$SIM"` | Removes the device |
| `xcrun simctl delete unavailable` | Removes devices the current Xcode cannot run |

- If only one simulator is up, the word `booted` can stand in for its UDID.
  With several running, which one `booted` means is not defined; parallel
  jobs must use explicit UDIDs.
- In scripts and CI, run `bootstatus "$SIM" -b` before installing, launching,
  pushing or setting a location. If you call `boot` on its own, follow it
  with `bootstatus "$SIM"`.

## Installing and launching

```bash
xcodebuild build -scheme Pantry \
  -destination "platform=iOS Simulator,id=$SIM" \
  -derivedDataPath build/
xcrun simctl bootstatus "$SIM" -b
xcrun simctl install "$SIM" build/Build/Products/Debug-iphonesimulator/Pantry.app
```

`install` wants the simulator-built `.app` folder, never an `.ipa`.

```bash
xcrun simctl launch "$SIM" org.example.pantry
xcrun simctl launch --console "$SIM" org.example.pantry
xcrun simctl launch "$SIM" org.example.pantry -seedDemoData YES -AppleLanguages "(de)"
xcrun simctl terminate "$SIM" org.example.pantry
```

- `--console` keeps the command attached and prints the app's stdout and
  stderr, so `print()` output and `os_log` messages appear in the terminal.
- Anything after the bundle ID becomes a launch argument.

Containers, for looking at sandboxed files, databases or defaults while
debugging:

```bash
xcrun simctl get_app_container "$SIM" org.example.pantry app
xcrun simctl get_app_container "$SIM" org.example.pantry data
xcrun simctl get_app_container "$SIM" org.example.pantry group.org.example.pantry
```

`app` is the bundle, `data` the data container (Documents, Library, tmp),
and a group identifier returns that App Group's shared container.

## Simulating the outside world

### Push notifications

```bash
cat > restock.json <<'JSON'
{
  "aps": {
    "alert": { "title": "Back in stock", "body": "Oat milk is available again" },
    "badge": 1,
    "sound": "default"
  },
  "itemID": "oat-milk-1l"
}
JSON
xcrun simctl push "$SIM" org.example.pantry restock.json
echo '{"aps":{"alert":"Pickup ready"}}' | xcrun simctl push "$SIM" org.example.pantry -
```

A file path or `-` (stdin) supplies the payload. Delivery is local: nothing
talks to APNs. That makes it good for payload parsing, presentation and
notification actions, and useless as proof that APNs delivery works; check
that end to end on a device before shipping.

### Location

```bash
xcrun simctl location "$SIM" set 52.3702,4.8952
xcrun simctl location "$SIM" list
xcrun simctl location "$SIM" run "Freeway Drive"
xcrun simctl location "$SIM" start --speed=12 --interval=2 52.3702,4.8952 52.3791,4.9003
printf '52.37,4.89\n52.38,4.90\n52.39,4.91\n' | xcrun simctl location "$SIM" start --distance=50 -
xcrun simctl location "$SIM" clear
```

- One fixed point: `set`. A scenario that ships with the simulator: `run`. Your own path: `start`
  with waypoints, or `-` to read one `lat,lon` per line from stdin.
- `run` takes scenario names such as "City Run" or "Freeway Drive", not GPX
  files. GPX routes are loaded from the Xcode menu instead (Debug >
  Simulate Location).
- A simulated location applies to every Core Location client on that device.
  `clear` it when the test ends so later tests are not surprised.

### Privacy permissions

```bash
xcrun simctl privacy "$SIM" grant photos org.example.pantry
xcrun simctl privacy "$SIM" revoke microphone org.example.pantry
xcrun simctl privacy "$SIM" reset all org.example.pantry
```

Services you will use most: `location`, `location-always`, `photos`,
`contacts`, `calendar`, `reminders`, `microphone`, `siri`, `motion` (the
reference has them all). Granting up front keeps CI from stalling on system
alerts, but it can also hide a missing usage-description key. Keep the
Info.plist privacy strings and still test the real prompt path.

### Deep links

```bash
xcrun simctl openurl "$SIM" "https://pantry.example.org/list/42"
xcrun simctl openurl "$SIM" "pantry://list/42"
```

An `https` URL exercises universal links, which need the associated domains
entitlement; the simulator downloads the domain's
`apple-app-site-association` file. A custom scheme opens the app directly.

### Status bar

```bash
xcrun simctl status_bar "$SIM" override --operatorName '' --time "9:41" \
  --wifiBars 3 --cellularBars 4 --cellularMode active --batteryLevel 100 --batteryState charged
xcrun simctl status_bar "$SIM" clear
```

Overrides give App Store screenshots a consistent status bar. Clear them once
the captures are done.

## Screenshots and video

```bash
xcrun simctl io "$SIM" screenshot home.png
xcrun simctl io "$SIM" screenshot --mask=alpha framed.png
xcrun simctl io "$SIM" recordVideo --mask=black onboarding.mov
```

- Masks: `ignored` (default, plain rectangle), `alpha` (transparent rounded
  corners), `black` (black corners). Pick `alpha` or `black` to show the
  device outline.
- `alpha` works for screenshots only; video falls back to `black`.
- Recording runs until SIGINT (Ctrl+C) and the file is written only after it
  stops. A SIGKILL ends it with no file at all.

## Logs

```bash
xcrun simctl spawn "$SIM" log stream \
  --predicate 'subsystem == "org.example.pantry" AND category == "sync"' --level debug
xcrun simctl spawn "$SIM" log stream --predicate 'process == "Pantry"'
```

`--level debug` shows debug messages and everything above them. Filter by
subsystem, add a category, or filter by process name. Design the logging so
these filters are useful:

```swift
import Foundation
import os

enum Diagnostics {
    static let sync = Logger(subsystem: "org.example.pantry", category: "sync")
    static let screens = Logger(subsystem: "org.example.pantry", category: "screens")
}

func refreshShoppingList(from endpoint: URL) async throws -> Data {
    Diagnostics.screens.info("Refreshing shopping list")
    let (body, response) = try await URLSession.shared.data(for: URLRequest(url: endpoint))
    let status = (response as? HTTPURLResponse)?.statusCode ?? -1
    Diagnostics.sync.debug("List payload \(body.count) bytes, HTTP \(status)")
    return body
}
```

## Detecting the simulator in code

```swift
import UIKit
import os

@MainActor
func enableRemotePush() {
    #if !targetEnvironment(simulator)
    UIApplication.shared.registerForRemoteNotifications()
    #else
    Logger(subsystem: "org.example.pantry", category: "push").info("Remote push registration skipped in Simulator")
    #endif
}
```

At run time, `ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil`
also tells you, but prefer the compile-time check: the excluded code is not
compiled at all, so symbols that do not exist for the simulator cannot cause
link errors.

## Where the simulator ends

Sort each test by two questions: can the simulator *trigger* the behavior, and
does the test need *real-device fidelity*?

The simulator can trigger or approximate: screenshots and video, status bar
overrides, granting and resetting permissions, memory warnings, a new
location, a push delivered locally with `simctl push`, a hand-started iCloud
sync, and biometric enrollment with matching or failing faces and fingers
from the Features menu.

Real hardware is required to validate: delivery through APNs; NFC and
Bluetooth LE; live camera and microphone input; motion sensors; App Attest
and the Secure Enclave; iCloud changes that propagate on their own, their
conflicts and their background delivery; processing speed and CPU
throughput; how fast and how slow the network really is; whether Metal
shaders render correctly and what the GPU allows; memory bandwidth; frame
pacing; memory pressure and Jetsam; heat.

iCloud is not one item. Triggering a sync by hand and checking that the app
reacts are simulator work. Automatic propagation, several devices or
accounts, conflict resolution, sync started by a push, background delivery,
and differences in account or device state need hardware.

| Capability | In Simulator | Notes |
|---|---|---|
| APNs push delivery | No | Local `simctl push` only |
| Performance | Relative only | Says nothing reliable about CPU, networking, Metal or graphics, shader correctness, memory bandwidth or pressure, frame pacing, Jetsam or heat; measure on devices |
| Metal GPU family parity | Partial | The Mac's GPU does the work, so limits and some shader behavior differ |
| Camera | No | Add photos to the library or mock `AVCaptureSession` |
| Microphone / audio input | No general app input | Siri can be triggered from the Simulator menus |
| Secure Enclave | No | Operations using `kSecAttrTokenIDSecureEnclave` fail |
| App Attest | No | `DCAppAttestService.shared.isSupported` is `false` |
| DockKit motor control | No | Accessories cannot connect |
| Accelerometer, gyroscope, barometer | No | |
| Core Bluetooth | No | BLE testing needs a device |
| Core NFC | No | |
| CarPlay display | Yes | Offered with the external display options; confirm in an actual car or head unit too |
| Face ID / Touch ID | No sensor | Enrollment and match results are simulated from the Features menu |
| Memory warnings, manual iCloud sync, location changes | Yes | Menus or `simctl` |
| Automatic iCloud sync | Not fully | Validate on hardware |
| Cellular conditions | No | Shape traffic with the Mac's Network Link Conditioner |

Numbers from the simulator only show that something works at all. Whenever a
question touches performance limits, the answer lists every area that needs a
device: processing and CPU, network speed and latency, graphics, whether Metal
shaders are correct, memory bandwidth, frame pacing, memory pressure and
Jetsam, and heat.

A release checklist always carries this sentence, word for word:

> Simulator timings do not predict device timings, so before release we
> measure on real hardware: CPU and processing, graphics and Metal, Metal GPU
> behavior, memory, memory pressure and Jetsam, frame pacing, network speed
> and latency, and thermal behavior.

Even a question about Metal alone gets processing, memory and networking in
that device list.

## Common mistakes

1. **Hard-coded UDIDs.** They change whenever a device is deleted and
   recreated and never match on another Mac or CI runner. Look the UDID up:

   ```bash
   SIM=$(xcrun simctl list devices available --json |
     jq -r --arg rt "com.apple.CoreSimulator.SimRuntime.iOS-26-0" \
       '.devices[$rt][] | select(.name == "Checkout iPad") | .udid')
   ```

   or use `booted` when exactly one simulator runs.
2. **Installing or launching on a stopped device.** These fail silently or
   with unhelpful errors. Boot, then install, then launch.
3. **Simulators left running in CI.** They keep eating memory and CPU. Clean
   up on every exit path:

   ```bash
   teardown() {
     xcrun simctl shutdown "$SIM"
     xcrun simctl delete "$SIM"
     xcrun simctl shutdown all
   }
   trap teardown EXIT
   ```

4. **Taking `simctl push` as APNs proof.** It never touches APNs, so it says
   nothing about token registration, entitlements or server delivery. Iterate
   with it, then confirm on a device against the APNs sandbox before release.
5. **Calling `boot` again on a stuck device.** When boot reports that the
   device is already in the Booting state and never finishes, CoreSimulator's
   state is damaged. Shut the
   device down, erase it and boot again; if that fails, `shutdown all` plus
   `erase all`; as a last resort delete the cache folder
   (`~/Library/Developer/CoreSimulator/Caches`).

## Review checklist

- [ ] `create` calls pass explicit device-type and runtime identifiers
- [ ] No literal UDIDs in scripts; `booted` or a JSON lookup instead
- [ ] Push payloads exercised with `simctl push` during development
- [ ] Push delivery confirmed on a physical device before release
- [ ] Location covered with fixed points, built-in scenarios and custom waypoints as needed
- [ ] CI grants privacy permissions up front
- [ ] `#if targetEnvironment(simulator)` guards APIs the simulator lacks
- [ ] Status bar overrides cleared after screenshots
- [ ] CI teardown shuts down and deletes its simulators
- [ ] Log streams filter by subsystem and category
- [ ] App container paths used to inspect sandbox data

## References

- `references/simctl-commands.md`
- Running on simulated or physical devices: https://developer.apple.com/documentation/xcode/running-your-app-on-simulated-or-physical-devices
- Downloading simulator runtimes and other components: https://developer.apple.com/documentation/xcode/downloading-and-installing-additional-xcode-components
- Configuring a simulated device's environment: https://developer.apple.com/documentation/xcode/configuring-the-environment-of-a-simulated-device
- Device Hub (managing simulated and physical devices): https://developer.apple.com/documentation/xcode/device-hub
