# simctl cheat sheet: every xcrun simctl command you will actually use

> A tested simctl cheat sheet: boot, install, launch, status bar, permissions, location, push, screenshots and video with xcrun simctl on Xcode 27.2.

Source: https://showtake.app/blog/simctl

*Recording · updated 2026-11-16*

simctl is the command-line tool that controls the iOS Simulator. Here are the commands that matter, run on Xcode 27.2 today, with the output, the flags and the errors you will hit.

`simctl` is Apple's command-line tool for the iOS Simulator: you run it as `xcrun simctl <subcommand>` to create, boot, erase and delete simulators, install and launch apps, and set the status bar, permissions, location, appearance, screenshots and video. It ships with Xcode, so there is nothing to install, and almost every command takes a device UDID or the word `booted` for the simulator that is running.

The top results for "simctl" are a 2018 article, a Rust crate, Stack Overflow threads and a Medium post. This cheat sheet is current: every command below was run on November 16, 2026 on an M4 Mac mini with macOS 27.2.1, Xcode 27.2 (27B52), the iOS 27.0 runtime and an iPhone 17 Pro simulator, and the screenshots are what those commands produced.

## simctl cheat sheet

| Task | Command |
| --- | --- |
| List devices (or JSON) | `xcrun simctl list devices available` / `xcrun simctl list -j devices` |
| Create a device | `xcrun simctl create "Demo iPhone" "iPhone 17 Pro"` |
| Boot and wait until ready | `xcrun simctl bootstatus <udid> -b` |
| Shut down / erase | `xcrun simctl shutdown all` / `xcrun simctl erase <udid>` |
| Delete old devices | `xcrun simctl delete unavailable` |
| Install / uninstall an app | `xcrun simctl install booted MyApp.app` / `xcrun simctl uninstall booted com.example.app` |
| Launch with logs in Terminal | `xcrun simctl launch --console-pty booted com.example.app` |
| Open a URL or deep link | `xcrun simctl openurl booted myapp://orders/42` |
| Clean status bar | `xcrun simctl status_bar booted override --time 9:41 --batteryLevel 100` |
| Dark mode / text size | `xcrun simctl ui booted appearance dark` / `xcrun simctl ui booted content_size accessibility-large` |
| Pre-grant a permission | `xcrun simctl privacy booted grant photos com.example.app` |
| Fake a location | `xcrun simctl location booted set 37.3349,-122.0090` |
| Add photos, videos, contacts | `xcrun simctl addmedia booted ~/Pictures/a.jpg ~/Movies/b.mov` |
| Send a push notification | `xcrun simctl push booted com.example.app payload.json` |
| Screenshot | `xcrun simctl io booted screenshot shot.png` |
| Record video | `xcrun simctl io booted recordVideo --codec=h264 demo.mov` |
| App data folder | `xcrun simctl get_app_container booted com.example.app data` |

`xcrun simctl help` lists 41 subcommands in Xcode 27.2, and `xcrun simctl help <subcommand>` prints the flags of one. If more than one simulator is booted, `booted` picks one of them, so use the UDID in scripts.

## Find, create, boot and delete simulators

Start with the list. `available` hides devices whose runtime is gone, and `-j` gives JSON you can parse with `jq`:

```sh
xcrun simctl list runtimes available
# iOS 27.0 (27.0 - 24A434) - com.apple.CoreSimulator.SimRuntime.iOS-27-0

xcrun simctl list devicetypes | grep "iPhone 17"
# iPhone 17 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro)

# The UDID of the first booted device
xcrun simctl list -j devices booted | jq -r '.devices[][] | .udid' | head -1
```

`create` takes a name, a device type and, optionally, a runtime. Without a runtime it picks the newest compatible one and says so (`No runtime specified, using 'iOS 27.0 …'`), then prints the new UDID:

```sh
UDID=$(xcrun simctl create "Demo iPhone" "iPhone 17 Pro")
xcrun simctl bootstatus "$UDID" -b    # boots if needed, returns when the device is ready
```

`bootstatus -b` is better than `boot` in scripts: `boot` returns before SpringBoard is up, so the next command can fail. A fresh iPhone 17 Pro took 21 seconds to finish booting on our Mac mini. `bootstatus` is not in the `simctl help` list, but it works in Xcode 27.2.

To clean up, `shutdown all` stops every running simulator, `erase <udid>` resets one to factory state, and `delete` removes devices for good. `xcrun simctl delete unavailable` deletes the devices whose runtime your current Xcode no longer supports; run it after every Xcode upgrade, because those leftovers keep their data on disk. `clone` copies a configured device, which is the fastest way to get the same clean setup every time.

## Install, launch and debug an app

Build for the Simulator first (`xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build`), then:

```sh
xcrun simctl install booted ./build/Debug-iphonesimulator/MyApp.app
xcrun simctl launch --console-pty --terminate-running-process booted com.example.myapp
```

The flags worth knowing in `launch`:

- `--console-pty` keeps simctl attached and prints the app's stdout and stderr in your terminal; Control-C is passed on to the app. Apple's help notes that log output often goes to stderr, not stdout.
- `--terminate-running-process` quits a running copy first, so you always get a cold start.
- `-w` (`--wait-for-debugger`) stops the app at launch until a debugger attaches.
- Anything after the bundle id is passed as launch arguments, e.g. `-demoMode YES`.
- Environment variables use a prefix: `SIMCTL_CHILD_API_BASE=http://localhost:8080 xcrun simctl launch booted com.example.myapp` sets `API_BASE` inside the app.

`terminate` quits the app, `uninstall` removes it, and `listapps` prints every installed app with its bundle path. `get_app_container booted <bundle id> data` prints the app's data folder on your Mac, which is how you inspect its files, databases and UserDefaults plist without a debugger.

## Set up the Simulator for screenshots and demos

This is where simctl saves the most time: every setting you would otherwise click through in Settings has a command, so the simulator looks the same in every screenshot and every take.

### Status bar

`status_bar override` fixes the time, signal, Wi-Fi and battery. All flags are optional, but at least one is required:

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

xcrun simctl status_bar booted list    # show the overrides
xcrun simctl status_bar booted clear   # back to the real values
```

Before: ![iPhone 17 Pro simulator status bar before and after xcrun simctl status_bar override](https://showtake.app/blog/simctl/status-bar-before.webp)
After: ![iPhone 17 Pro simulator status bar before and after xcrun simctl status_bar override](https://showtake.app/blog/simctl/status-bar-after.webp)

*The same simulator before (18:22, no cellular bars) and after the override above (09:41, full bars, full battery). Drag the slider.*

Two things we saw on iOS 27.0. The clock follows the simulator's region: our device used 24-hour time, so `--time 9:41` showed **09:41**; set a 12-hour region such as en-US for the classic 9:41. And `--batteryState charged` draws the battery green with a charging bolt. `--time` also accepts an ISO date, which sets the date on devices that show it.

### Appearance, text size and contrast

```sh
xcrun simctl ui booted appearance dark                   # or light
xcrun simctl ui booted content_size accessibility-large  # or increment
xcrun simctl ui booted increase_contrast enabled
```

The text sizes go from `extra-small` to `extra-extra-extra-large`, plus five accessibility sizes from `accessibility-medium` to `accessibility-extra-extra-extra-large`. Taking one screenshot at the largest accessibility size is a quick Dynamic Type test.

### Permissions, location, media and links

```sh
# No permission alert in the middle of a demo
xcrun simctl privacy booted grant photos com.example.myapp
xcrun simctl privacy booted reset all          # ask again on next use

# A fixed point, a route, or a built-in scenario
xcrun simctl location booted set 37.3349,-122.0090
xcrun simctl location booted start --speed=15 37.3349,-122.0090 37.3318,-122.0312
xcrun simctl location booted list              # City Run, City Bicycle Ride, Freeway Drive, Apple

# Seed the photo library and test a deep link
xcrun simctl addmedia booted ~/Demo/photo1.jpg ~/Demo/clip.mov
xcrun simctl openurl booted "myapp://orders/42"
```

`privacy` knows `all`, `calendar`, `contacts-limited`, `contacts`, `location`, `location-always`, `photos-add`, `photos`, `media-library`, `microphone`, `motion`, `reminders` and `siri`. Some changes terminate the app if it is running, and Apple's help warns that bypassing the prompt "can mask bugs": keep one pass where the real alert appears.

### Push notifications

`push` delivers a remote notification from a JSON file or stdin. The payload needs an `aps` key and must be 4,096 bytes or less; if it contains a `Simulator Target Bundle` key you can leave out the bundle id.

```sh
echo '{"aps":{"alert":{"title":"Order ready","body":"Your tacos are waiting"}}}' \
  | xcrun simctl push booted com.example.myapp -
```

> **"Source is not authorized" (code 2003):** We sent that payload to an app that had never asked for notification permission and got `Repository could not save notification. Source is not authorized.` (UNErrorDomain code 2003). The app has to request notification authorization and you have to allow it in the Simulator before a simulated push shows up (`privacy` has no notifications service). Only regular remote notifications work; VoIP, complication and File Provider pushes are not supported.

## Screenshots and video with simctl io

`io screenshot` writes the screen at device pixels (1206×2622 on iPhone 17 Pro) with no window frame. `--type` takes `png` (default), `tiff`, `bmp`, `gif` or `jpeg`, and `-` as the file name writes to stdout.

```sh
xcrun simctl io booted screenshot home.png
xcrun simctl io booted screenshot --mask=black framed.png   # black corners and Dynamic Island
```

![iPhone 17 Pro simulator screenshot in dark mode taken with xcrun simctl io screenshot --mask=black](https://showtake.app/blog/simctl/dark-mask-black.webp)

*`ui appearance dark` plus `io screenshot --mask=black`: the rounded corners and the Dynamic Island are drawn black. Without `--mask` our screenshots had square corners and no island.*

For App Store screenshots you need specific pixel sizes per device class; the current list is in [App Store screenshot sizes](https://showtake.app/blog/app-store-screenshot-sizes). Video works the same way with `io booted recordVideo`; codecs, the variable frame rate and how to make the file App Store ready are covered in [how to record the iOS Simulator](https://showtake.app/blog/record-ios-simulator-video).

> **simctl hangs when writing to an external drive:** On our Mac, `xcrun simctl io … screenshot /Volumes/…/before.png` printed the display note and then waited for minutes with no file. The same command writing to `/tmp` finished at once. macOS asks for permission before a tool writes to a removable or network volume, and from a non-interactive shell nobody answers. Write to your home folder or `/tmp` and move the file afterwards, or allow your terminal in **System Settings > Privacy & Security > Files and Folders**.

`recordVideo` waits for the first frame before it prints `Recording started`, and it only writes a frame when the screen changes, so on a still home screen it can sit there with no output. Start it, then interact with the app.

## A setup script you can reuse

Put the setup in a script and every screenshot session starts from the same state:

```sh
#!/bin/sh
set -e
BUNDLE=com.example.myapp
UDID=$(xcrun simctl create "Screenshots iPhone" "iPhone 17 Pro")
xcrun simctl bootstatus "$UDID" -b
xcrun simctl status_bar "$UDID" override --time 9:41 --batteryState charged --batteryLevel 100 \
  --wifiBars 3 --cellularBars 4 --dataNetwork wifi
xcrun simctl ui "$UDID" appearance light
xcrun simctl install "$UDID" ./build/Debug-iphonesimulator/MyApp.app
xcrun simctl privacy "$UDID" grant photos "$BUNDLE"
xcrun simctl addmedia "$UDID" ./demo-media/*.jpg
xcrun simctl launch "$UDID" "$BUNDLE" -demoMode YES
sleep 3
xcrun simctl io "$UDID" screenshot "$HOME/Desktop/01-home.png"
# when you are done: xcrun simctl delete "$UDID"
```

- [ ] Use a dedicated device, not the one you develop on, so test data never shows up
- [ ] Wait with `bootstatus -b`, never a fixed `sleep` after `boot`
- [ ] Status bar, appearance and permissions set before the app launches
- [ ] Demo data loaded through a launch argument ([demo mode](https://showtake.app/docs/demo-mode) shows the pattern)
- [ ] Output written to your home folder or `/tmp`, not an external drive
- [ ] The device deleted at the end, plus `xcrun simctl delete unavailable` after Xcode updates

## Fix common simctl errors

| Error | Cause | Fix |
| --- | --- | --- |
| `unable to find utility "simctl"` | Command Line Tools are selected instead of Xcode | Select Xcode (command below) |
| `Source is not authorized` on `push` | The app has no notification permission | Ask for permission in the app, allow it |
| A command hangs, no file | macOS asks for folder access | Write to `/tmp` or your home folder |
| No `Recording started` | The screen has not changed yet | Interact with the app |
| A command fails after `boot` | The device is not ready | Use `bootstatus <udid> -b` |

For the first error, point the developer directory at Xcode and check that simctl answers:

```sh
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcrun simctl help
```

## Where simctl stops, and what films the demo

simctl sets the stage, but it cannot tap, type or swipe: there is no input command among its 41 subcommands. That is why UI tests use XCUITest and why coding agents use MCP servers to drive the Simulator (we compared them in [iOS Simulator MCP servers](https://showtake.app/blog/ios-simulator-mcp)). And a raw screenshot or recording is still raw: no zoom on what changed, no captions, no App Store sizes.

ShowTake does both parts for demos. Your coding agent prepares the app with `prepare_ios`, which builds it, clones a clean simulator with the status bar at 9:41, pre-grants permissions, seeds photos and a location (the same settings as above, without the script), then drives the app through its accessibility tree and films the take. The render zooms on every tap and turns the agent's step captions into on-screen captions.

[Video: An agent driving an app in the Simulator through ShowTake: every step is logged with the element it touched, so the render can zoom on it.](https://showtake.app/media/agent-takes.mp4)

What ShowTake does not do: it is not a test framework (no assertions), it does not record real devices or Android, and it does not replace simctl for your own scripts. **Free vs Pro.** The free plan films, adds library music and captions, and exports the X 16:9 preset with a small watermark. [Pro](https://showtake.app/pricing) adds every other preset, App Previews, App Store screenshots and the launch kit, 4K, batch replays and your own audio files. All tools are in the [tool reference](https://showtake.app/docs/tools); to start, [download ShowTake](https://showtake.app/download) or paste showtake.app into your agent.

> Try it: paste this into your coding agent: "Set up ShowTake for me from https://showtake.app/agents.md and make a demo video of my app."

## Common questions

### What is simctl?

simctl is Apple's command-line interface to the iOS Simulator (and the watchOS, tvOS and visionOS simulators). It is part of Xcode, lives inside the CoreSimulator framework, and you call it through `xcrun simctl` so it always matches the selected Xcode.

### How do I install simctl?

Install Xcode from the Mac App Store or Apple's developer site. The Command Line Tools alone do not include it. If `xcrun simctl` says it cannot find the utility, point `xcode-select` at Xcode as shown in the error table above.

### What does "booted" mean in simctl commands?

`booted` stands for the simulator that is running. If several are running, simctl picks one of them, so scripts should pass the UDID from `xcrun simctl list devices` instead.

### How do I delete all simulators?

`xcrun simctl delete all` deletes every simulator device, and `xcrun simctl delete unavailable` deletes only the ones your current Xcode cannot run. Runtimes are separate: `xcrun simctl runtime list` shows them and `xcrun simctl runtime delete --unusable` (or `--notUsedSinceDays <days>`) removes them.

### Can simctl tap or type in the Simulator?

No. simctl controls the device (boot, apps, settings, media, screenshots) but has no input commands. Use XCUITest for tests, or an MCP server or ShowTake when a coding agent should drive the app.
