--- title: "xcrun simctl commands: a reference with examples | Mobster" description: "Every xcrun simctl command in Xcode 26.4 with its usage line and an example, from devices and apps to push, permissions, location, the status bar and video." canonical: "https://mobster.dev/blog/simctl-commands" last-updated: "2026-11-14" --- Every xcrun simctl command in Xcode 26.4 with its usage line and an example, from devices and apps to push, permissions, location, the status bar and video. # xcrun simctl commands, with examples 22 October 2026 `xcrun simctl` is the command line for the iOS Simulator. It creates and boots simulators, installs and launches apps, and sets the state a test needs: a push notification, a permission, a location, a status bar, a text size. This page lists each subcommand by the job it does, with its usage line, an example you can paste and what it prints. Every usage line here is from `xcrun simctl help ` in Xcode 26.4 (17E192). Run the same command on your Mac to see your version’s flags. ## Before you start Most subcommands take a ``. It is a simulator’s UDID, or the word `booted`, which picks a booted simulator. The help is plain about the catch: “If multiple devices are booted when the “booted” device is selected, simctl will choose one of them.” Use `booted` at your desk and a UDID in scripts. `boot`, `launch` and `spawn` pass environment variables to the simulator when you prefix them with `SIMCTL_CHILD_` in your own shell: `SIMCTL_CHILD_API_URL=http://localhost:8080 xcrun simctl launch booted com.example.YourApp` starts the app with `API_URL` set. `xcrun simctl` itself is a short shell script in Xcode (`Contents/Developer/usr/bin/simctl`). It checks the installed CoreSimulator framework’s version, runs `xcodebuild -runFirstLaunch` when it isn’t the one this Xcode expects, then hands your arguments to CoreSimulator’s own `simctl`. That is why the first command after you switch Xcode can take a minute. ## Find and create simulators ### list ``` Usage: simctl list [-j | --json] [--json-fd=] [--json-output=] [-e | --no-escape-slashes] [-v] [devices|devicetypes|runtimes|pairs] [|available] ``` Name a type to list only that, and add a search term to filter it. The term `available` keeps the items this Xcode can run. ``` xcrun simctl list runtimesxcrun simctl list devicetypes "iPhone 17"xcrun simctl list devices available ``` What Xcode 26.4 printed for the first two: ``` == Runtimes ==iOS 26.4 (26.4 - 23E244) - com.apple.CoreSimulator.SimRuntime.iOS-26-4== Device Types ==iPhone 17 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro)iPhone 17 Pro Max (com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro-Max)iPhone 17e (com.apple.CoreSimulator.SimDeviceType.iPhone-17e)iPhone 17 (com.apple.CoreSimulator.SimDeviceType.iPhone-17) ``` `list devices` prints one line per simulator under its runtime: the name, the UDID in brackets and the state, such as `iPhone 17 Pro () (Shutdown)`. `-j` prints the same as JSON; [Read the JSON with jq](#read-the-json-with-jq) has the queries. ### create ``` Usage: simctl create [] ``` Leave out the runtime and simctl picks the newest one that runs the device type. It prints the new simulator’s UDID, so a script can keep it: ``` UDID=$(xcrun simctl create "CI iPhone" com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro com.apple.CoreSimulator.SimRuntime.iOS-26-4) ``` ### clone, rename, delete `delete` takes UDIDs, `unavailable` or `all`. `delete unavailable` removes simulators whose runtime this Xcode no longer has, the usual leftover after an Xcode update; `delete all` removes every simulator in the set, yours included. `rename ` and `clone ` do what they say. For tests that must not see each other’s data, create each simulator fresh instead of cloning one. In our own benchmark runs, apps on a clone resolved to the source simulator’s containers, so our harness refuses a cloned simulator. ## Boot, wait, shut down and erase ### boot and bootstatus ``` Usage: simctl boot [--arch=] [--disabledJob=] [--enabledJob=] [--checked-allocations]Usage: simctl bootstatus [-bcd] ``` `boot` returns before the simulator is ready for an app. `bootstatus` isn’t in `simctl help`’s list, but `simctl help bootstatus` documents it: it prints boot progress until the device finishes booting, and `-b` boots the device first if it isn’t booted. In a script, that one line replaces a boot and a sleep: ``` xcrun simctl bootstatus "$UDID" -b ``` Booting a simulator that is already booted fails with `Unable to boot device in current state: Booted`. Check `state` in `list -j` first, or let `bootstatus -b` decide. ### shutdown and erase ``` Usage: simctl shutdown | allUsage: simctl erase [... ] | all ``` `erase` returns a simulator to a new one’s contents and settings: apps, data, permissions and the keychain. The simulator must be shut down first. ``` xcrun simctl shutdown "$UDID"xcrun simctl erase "$UDID" ``` ## Install, launch and remove an app ``` Usage: simctl install Usage: simctl launch [-w | --wait-for-debugger] [-a | --arch=] [--console|--console-pty] [--stdout=] [--stderr=] [--terminate-running-process] [--checked-allocations] [ ... ]Usage: simctl terminate Usage: simctl uninstall ``` `install` takes the `.app` a simulator build makes, such as the one under `Build/Products/Debug-iphonesimulator/` in your derived data. A device build or an `.ipa` won’t install on a simulator. ``` xcrun simctl install booted Build/Products/Debug-iphonesimulator/YourApp.appxcrun simctl launch --terminate-running-process booted com.example.YourApp -AppleLanguages "(de)" -AppleLocale de_DE ``` Arguments after the bundle ID go to the app as launch arguments, which is how a test sets the app’s language without changing the simulator’s. `--console` keeps the command attached and prints the app’s stdout and stderr in your terminal; the help notes that log output usually goes to stderr. `--terminate-running-process` quits a running copy first, so the launch is always a cold start. ### listapps, appinfo and get_app_container ``` Usage: simctl listapps Usage: simctl appinfo Usage: simctl get_app_container [] ``` `get_app_container` prints a path on your Mac. The container is `app` (the `.app` bundle, the default), `data` (Documents, Library and tmp), `groups`, or one App Group’s identifier. `open "$(xcrun simctl get_app_container booted com.example.YourApp data)"` opens the data container in Finder. That is the fastest way to read what your app wrote to disk during a test, or to delete one file without erasing the simulator. ## Open a URL or a deep link ``` Usage: simctl openurl ``` ``` xcrun simctl openurl booted "yourapp://tasks/42"xcrun simctl openurl booted "https://example.com/products/42" ``` A custom scheme opens your app when its `Info.plist` declares the scheme. The first time on each simulator, iOS asks “Open in …?” before it hands the link over ([Mobster simulator docs](https://docs.mobster.dev/simulators#deep-links)), so a test that opens links this way has to press Open once. ## Send a push notification ``` Usage: simctl push [] ( | -) ``` The payload must be a JSON object with an `aps` key and be 4,096 bytes or less, the same 4,096-byte limit Apple sets for remote notifications other than VoIP. Only app remote notifications work: the help says “VoIP, Complication, File Provider, and other types are not supported.” ``` { "Simulator Target Bundle": "com.example.YourApp", "aps": { "alert": { "title": "Order shipped", "body": "Your order is on its way." }, "badge": 1, "sound": "default" }} ``` With `Simulator Target Bundle` in the file, the bundle ID argument is optional; when you pass both, the argument wins. ``` xcrun simctl push booted payload.jsonecho '{"aps":{"alert":"Hello"}}' | xcrun simctl push booted com.example.YourApp - ``` On success simctl prints a line that starts `Notification sent to`. Keep `Simulator Target Bundle` out of payloads your server sends. ## Grant, revoke and reset permissions ``` Usage: simctl privacy [] ``` The actions are `grant` and `revoke`, which need a bundle ID, and `reset`, which prompts again on next use. The services in Xcode 26.4 are `all`, `calendar`, `contacts-limited`, `contacts`, `location`, `location-always`, `photos-add`, `photos`, `media-library`, `microphone`, `motion`, `reminders` and `siri`. ``` xcrun simctl privacy booted grant photos com.example.YourAppxcrun simctl privacy booted revoke location com.example.YourAppxcrun simctl privacy booted reset all com.example.YourApp ``` Two warnings come with it. “Some permission changes will terminate the application if running”, so set permissions before you launch. And a grant skips the prompt, so it also skips the check that your `Info.plist` has the usage description; the help says that bypass “can mask bugs”. Keep one test that sees the real prompt. Camera and Face ID aren’t in the list. ## Set the location ``` Usage: simctl location [arguments] ``` The actions are `list`, `clear`, `set ,`, `run `, and `start`, which moves along waypoints at a speed you set (20 m/s unless you say otherwise): ``` xcrun simctl location booted set 52.5200,13.4050xcrun simctl location booted start --speed=1.4 --interval=1 52.5200,13.4050 52.5163,13.3777xcrun simctl location booted clear ``` Write coordinates with `.` as the decimal separator and `,` between latitude and longitude. `location list` prints the built-in scenarios that `run` accepts. ## Override the status bar for screenshots ``` Usage: simctl status_bar [list | clear | override ] ``` The overrides are `--time`, `--dataNetwork`, `--wifiMode`, `--wifiBars` (0 to 3), `--cellularMode`, `--cellularBars` (0 to 4), `--operatorName`, `--batteryState` and `--batteryLevel` (0 to 100). Apple’s example from the Xcode 11 release notes: ``` xcrun simctl status_bar booted override --time "9:41" --batteryState charged --batteryLevel 100xcrun simctl status_bar booted clear ``` `--time` takes an ISO date too, and then sets the date as well as the clock. Clear the overrides at the end of a run, so the next test starts from the real status bar. ## Take screenshots and record video ``` io screenshot [--type=] [--display=] [--mask=] io recordVideo [--codec=] [--display=] [--mask=] [--force] ``` ``` xcrun simctl io booted screenshot home.pngxcrun simctl io booted recordVideo --codec=h264 run.mp4 ``` A screenshot is a PNG unless the extension or `--type` says `tiff`, `bmp`, `gif` or `jpeg`; simctl prints `Detected file type from extension:` and then `Wrote screenshot to:` with the path. `-` writes the PNG to stdout. `recordVideo` uses HEVC unless you pass `--codec=h264`, which more players and CI artifact viewers open. It writes `Recording started` to stderr once the first frame is in, and it stops on SIGINT, finishing the file before it exits. In a script, start it in the background and stop it with `kill -INT`: ``` xcrun simctl io "$UDID" recordVideo --codec=h264 --force run.mp4 &REC=$!# ... run the test ...kill -INT "$REC"; wait "$REC" ``` On a display that isn’t a rectangle, `--mask=black` fills the masked parts, such as the rounded corners, with black; `ignored` keeps the whole framebuffer. ## Appearance, contrast and text size ``` Usage: simctl ui