Learn the simctl command line utility by example

The simctl command controls iOS simulator instances. It can be run via xcrun simctl to ensure the version of the tool used matches your currently active Xcode version.

For a full listing of what simctl can do, simply run: xcrun simctl to see the built-in help.

Remove un-needed simulators

Delete simulators that are no longer usable.

xcrun simctl delete unavailable

Record a video from a simulator

xcrun simctl io booted recordVideo --type=h264 ~/your-file.mov

Alternative: Pipe to another program or server socket

xcrun simctl io booted recordVideo --type=fmp4 - | otherProgram

A URL may be specified instead of a file to establish a server socket. The syntax for accepted URLs is: "[tcp|udp]://[ipv4|ipv6]:" Valid examples are: "tcp://127.0.0.1:9152" and "udp://[::1]:8152".

Options:

Option Values
--type 'h264', 'mp4' or 'fmp4'
--display which display
--mask ignored will record full-screen rectangle video on iPhone X
black will render a black mask over the video

Take a screenshot of a simulator

xcrun simctl io booted screenshot --type=jpeg ~/your-file.jpg
Option Values
--type 'png', 'jpg', 'bmp', 'gif'
--display which display
--mask ignored will record full-screen rectangle video on iPhone X
black will render a black mask over the video

List devices and/or runtimes

List All:

xcrun simctl list --json

List Devices:

xcrun simctl list devices --json

List Device Types:

xcrun simctl list devicetypes --json

List Simulator Runtimes:

xcrun simctl list runtimes --json

List Paired Devices:

xcrun simctl list pairs --json

For more tips/tricks, see the Listing Devices article

Option Values
--json or -j produce JSON output

Opening a URL on a simulator

xcrun simctl openurl booted 'https://google.com'
xcrun simctl openurl booted 'myapp://custom'

Locate an app bundle, app data, or app group data

The .app container:

xcrun simctl get_app_container booted com.yourco.appname

Other containers:

xcrun simctl get_app_container booted com.yourco.appname <container>
Option Values
container (see below)
Container Option Container
app The .app bundle (default)
data The application's data container
groups The App Group containers
(group identifier) A specific App Group container

Adding media to a simulator

Add photos, videos and live photos to the simulator

Add one photo

xcrun simctl addmedia booted ~/Photos/iphone-sample-photos/sample-1.jpg

Or add a mix of many items

xcrun simctl addmedia booted ~/sample-1.jpg \
    ~/sample-2.jpg \
    ~/sample-3.mp4

Managing preferences on-device using defaults

Get a list of all available preference domains:

xcrun simctl spawn booted defaults domains

Read the defaults for a specific app:

xcrun simctl spawn booted defaults read com.apple.springboard

Set a default value for a specific app:

xcrun simctl spawn booted defaults write \
    com.socool.my-app apiBaseURL -string "https://beta.example.com/api/v3/"


There's more to read!

Did this help solve your problem? If so, consider letting us know on Twitter. You should follow us for all the latest articles and updates:


Have you seen our latest project on Github?.

Sign up for our newsletter

Get an email when new content comes out! Emails are not sold and are used only for announcing updates to the site. Expect ~1-2 emails per month. Unsubscribe any time.