iOS Simulator

2020/04/26 xcrun simctl by jean tran

Usually when you've installed/updated Xcode, it will also prompt a notification suggesting to you to update your 'command line tools'. From here simctl is accessible through the xcrun command in your terminal.

xcrun simctl

Managing Simulator Devices

• Running list command, it will prompt a list of the available runtimes devices informations.

• Each devices are ordered by iOS, has a name, associated UUID and status (Booted|Shutdown).

xcrun simctl list

...
-- iOS 13.4 --
  iPhone 8 (D3A196A0-E332-4A6A-95F4-07ECFEEADE00) (Shutdown)
  iPhone 8 Plus (02D8F4FD-F8F4-4474-AD69-CAE7F98A00AB) (Shutdown)
  iPhone 11 (18C54542-DD6B-4D18-A008-352955341915) (Shutdown)
  iPhone 11 Pro (6F2D5BB9-C3E9-4196-81DE-F8B2A060838E) (Shutdown)
  iPhone 11 Pro Max (1DFAEF2A-090C-4E32-8534-CB3F96485EA7) (Shutdown)
...

• It's possible to launch a specific simulator by providing it UUID value:

xcrun simctl boot 18C54542-DD6B-4D18-A008-352955341915

• To access to booted simulator:

open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/

• To check which simulator are booted, combine the list subcommand with grep:

xcrun simctl list | grep Booted

iPhone 11 (18C54542-DD6B-4D18-A008-352955341915) (Booted)

• To access booted device UUID, can be done completing previous command with a regexp

xcrun simctl list devices | \
grep "(Booted)" | \
grep -E -o -i "([0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12})"
18C54542-DD6B-4D18-A008-352955341915

• It's also possible by using -j or --json subcommand to have an output as JSON. Which could be convenient when managing simulators using scripts or programs.

xcrun simctl list -j

• Finally using shutdown and erase subcommands, can be use to close and clear your simulator contents.

xcrun simctl shutdown $UUID
xcrun simctl erase $UUID

Tips: You've been working for a while and update Xcode version for few times. You've probably accumulate several version of old devices. For most, you will probably using the latest simulators version. The following command will free you few gigabytes of disk space.

xcrun simctl delete unavailable

Simctl subcommands examples

addmedia

xcrun simctl addmedia booted ~/Desktop/bunny.jpg

screen/video capture

xcrun simctl io booted screenshot app-screencapture.png
xcrun simctl io booted recordVideo app-videocapture.mp4

openurl

• Case to open in the simulator by providing a web link:

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

• Case to open in the simulator by using URL Scheme:

xcrun simctl openurl booted "app-prefs://"

Simctrl Xcode 11.4

Dark/Light mode

• Toggle appearance modes: light/dark

xcrun simctl ui booted appearance dark

keychain

• Install certificates for trusted connections via drag and drop or terminal:

xcrun simctl keychain booted add-root-cert my-selfsigned.cer

privacy location and permission

• Changing or reset simulator-device privacy permissions: location always, when app in use...

xcrun simctl privacy booted grant location <bundle_id>
xcrun simctl privacy booted grant location-always <bundle_id>

• resetting or applying all permissions:

xcrun simctl privacy booted reset all <bundle_id>
xcrun simctl privacy booted grant all <bundle_id>

push notifications

• Simulator supports background content fetch notifications and remote push notifications.

  Also, simctl has the subcommand push for remote push notifications.

xcrun simctl push booted <bundle_id> <json-aps-payload.json>

Status bar

• Change device status bar properties:

xcrun simctl status_bar booted override --dataNetwork "4g" --cellularBars 3 --operatorName "prog88"