Running Your iOS App in the Simulator From The Command Line

While Apple doesn’t provide an “official” way to launch an app in the iOS Simulator from the command line, there’s a few private tricks we can employ.First, the iOS Simulator app itself is located in:

/Developer/Platforms/iPhoneSimulator.platform/Developer/Applications

But running that will only bring up the simulator in the last state it was in. How do we install an application in there and then run it automatically like Xcode does?

The trick is in the private iPhoneSimulatorRemoteClient.framework. Now before you freak out, don’t worry! This isn’t something you compile your app against and submit to the store. This is a framework that we can use on our local machines to control the simulator just like Xcode does. The best part is, all the work of hooking into it has been done for us!

There are two command line utilities I’ve seen that do this best. I used to useiphonesim and it works great. But I recently switched to WaxSim since it also records video of the simulator in motion. They both are functionally equivalent and small enough to understand. It’s your call, but I recommend the later.1

The Recipe 

First, we need to pull down the WaxSim source and install it. Run the following:

git clone https://github.com/square/WaxSim
cd WaxSim
xcodebuild install DSTROOT=/

Now, you have the waxsim binary in /usr/local/bin which should already be on your path. You can now invoke your application in the simulator like this:

waxsim [application path]

So, where is your application path? That depends on how you build it! First, we’ll need to do a quick walkthrough about building Xcode projects from the command line.

cd into your iOS application’s project directory (the one with the Xcode project file). Then, invoke the xcodebuild command like so:

xcodebuild -sdk iphonesimulator5.0 \
           -arch i386 \
           install DSTROOT=/tmp/MyApp

For most projects, this command will work just fine. However, if you have an explicit workspace set up, you’ll need to use man xcodebuild to learn how to teach the xcodebuild binary to interpret your setup. There’s a lot of good stuff in there about how to specify whether to build for the simulator or device, too.

The DSTROOT environment variable on the command above is the most important part. DSTROOT is used by Xcode when run with the “install” build action to figure out where to put the results. We’re specifying /tmp/MyApp explicitly so that we know where the resulting application bundle will be to hand in to waxsim.

Once the xcodebuild command completes, you should now have an *.app bundle in /tmp/MyApp/Applications/[YourAppName].app. Of course, subtitute your own application name in the path. Invoke waxsim and you’re up and running:

waxsim /tmp/MyApp/Applications/[YourAppName].app

This runs the iPhone simulator with the latest SDK that waxsim is aware of. Usewaxsim -h to find out other options like running the iPad simulator or other using other available SDKs.

You can also record a low resolution video of the simulator like so

waxsim -v myvideo.mov /tmp/MyApp/Applications/[YourAppName].app

And now you’ll have myvideo.mov in the current directory. It’s a pretty low res and stuttery video, probably not something you’d use for a promotional demo, but it’s a nice feature if you need to review results of automated testing workflows.

Script It 

So, for completeness sake, here’s a shell script that you can modify to build and run your application:

#!/bin/bash

# Tell bash to abort the script if any error happens
set -e

APPNAME=MyApp
DSTROOT=/tmp/MyApp

xcodebuild -sdk iphonesimulator5.0 \
           -arch i386 \
           install DSTROOT="$DSTROOT"

waxsim "$DSTROOT"/Applications/"$APPNAME".app

Drop this in your project directory and tweak to taste.

The End!

So, there you have it. We’ve built the waxsim binary, learned briefly how to build with xcodebuild, and learned how to launch your application in the iOS simulator on demand and from the command line. Vive la Unix!