Using iOS Simulator with the Command Line

Joel Oliveira

May 22 2020

Posted in Engineering & Technology

Make the most out of the iOS simulator

While developing for iOS, the simulator is a great resource. It's a great way of testing your apps without a physical device. Its friendly graphical interface can speed things up and emulate very well many features of real devices. But using the terminal is also a great way to speed things up and the only way to create useful scripts for Continuous Integration servers.

Using simctl

Apple's command line utility to interact with the iOS simulator, simctl, is a poorly documented binary that comes bundled with Xcode in /Applications/Xcode.app/Contents/Developer/usr/bin/simctl and therefore you can run it using xcrun. You can list all the available options by running the following command:

xcrun simctl help

Managing Simulators

Using simctl, we can perform several tasks including how you manage, create, rename, erase, upgrade, boot and shutdown simulators.

List simulators

To obtain the list of simulators use the following command:

xcrun simctl list

This will give you a list of all simulator devices, runtimes and device types:

After running this command, you will get a UUID, which will basically allow you perform all kinds of operations involving this newly created simulator.

Booting Simulator

Now let's use the UUID you got to boot it, by running the following command:

xcrun simctl boot 8F9690AC-FCDE-4913-9BD2-E54B3CC9F6C1

Then, let's open the simulator app:

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

This will quickly open the app with the booted simulator:

Shutdown Simulator

Here onwards, by using the UUID you can perform other operations, for example to shutdown the simulator you would run the following command:

xcrun simctl shutdown 8F9690AC-FCDE-4913-9BD2-E54B3CC9F6C1

Erase Simulator

Pretty much the same way, you can eventually delete this simulator:

xcrun simctl erase 8F9690AC-FCDE-4913-9BD2-E54B3CC9F6C1

If you've installed several versions of Xcode in the same machine, over time, you will accumulate a sizable cache of old simulators. Most of them, will no longer be usable in the latest version of iOS. To clean all these and save a few gigabytes of disk space, you can run the following command:

xcrun simctl delete unavailable

Setting Simulator Locale

One of the most annoying tasks when developing an app with multi-language support, is the fact that you will find yourself switching back and forward between different locales. This usually is done via the Settings app in General > Language & Region and by selecting one from a list of locales.

You can accelerate this process using the terminal without necessarily using simctl. Each simulator stores these preferences in a file called .GlobalPreferences.plist. Using the plutil utility, you can edit the contents of any .plist file. For example, use the following command to see the contents of this file:

Opening an URL in Simulator

Another handy operation that you will occasionally need, is the ability to open a specific URL. You can do this using the openurl subcommand. For example to open the browser:

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

Or if you want to open the Maps app:

xcrun simctl openurl booted maps://?s=Rotterdam

And eventually if you want to open your own app (assuming you've implemented deep linking):

xcrun simctl openurl booted com.myapp://myapp.com/action/buy

Add Files to the Photo Library

By default, a simulator will include a handful of images in its Photo Library. For some apps, you will need to use these to test how images are uploaded to a server or shown as an avatar, for example. You can use simctl to add more media files to the simulator's library by using the following command:

xcrun simctl addmedia booted ~/Desktop/AnImage.png

Take a Screenshot

Another cool functionality is the ability to take a screenshot of the simulator, usually you would use ⌘ + S via the GUI, but this can also be done via the terminal using:

xcrun simctl io booted screenshot ~/Desktop/screenshot.png

Record a video

Pretty much the same way, you can record a video using the terminal by invoking the following command:

xcrun simctl io booted recordVideo ~/Desktop/video.mp4

New features in Xcode 11.4

This version of Xcode shipped with more simctl functionality. For example, you can now emulate push notifications in the simulator using the following:

For those developers, with an eye for detail, this will allow you to customize the status bar of the simulator and take the perfect screenshots or make the best screen recordings.

Conclusion

As you can see, using the terminal (or bash scripts) and simctl, you can programmatically control the simulator, which can accelerate your next round of tests or allow you to create a very complete CI server script. If you have any questions, corrections or simply just want to drop us a line, we are, as always, available via our Support Channel.