In the latest version of Xcode, its shipping CLI (Command-Line Tool) – xcodebuild should be powerful enough for us to deal with some normal tasks without any interaction with Xcode UI itself. However, as always, Apple’s “good” documentation actually kills its broad using.

In this post, we are discussing the usage of -destination option, which can help you build and run the app in iOS simulator or real device.

Destination Specifier

Based on the documentation, the -destination option takes an argument – destination specifier – to help define the destination(s). The syntax of the destination specifier is a set of comma-separated key=value pairs.

-destination DESTINATIONSPECIFIER   use the destination described by DESTINATIONSPECIFIER (a comma-separated set of key=value pairs describing the destination to use)

NOTE!! When defining this destination specifier, there should NOT have any “space” between each key=value pair.

So, this should work:

xcodebuild \
  -workspace ExampleApp.xcworkspace \
  -scheme ExampleApp \
  -destination 'platform=iOS Simulator,name=iPhone 6,OS=9.1'
  clean test

But this does NOT work:

## This DOES NOT work!!!!
xcodebuild \
  -workspace ExampleApp.xcworkspace \
  -scheme ExampleApp \
  -destination 'platform=iOS Simulator, name=iPhone 6, OS=9.1'
  clean test

Also, only using quite on each value part should also work:

xcodebuild \
  -workspace ExampleApp.xcworkspace \
  -scheme ExampleApp \
  -destination platform='iOS Simulator',name='iPhone 6',OS='9.1''
  clean test

The “name” Key

The value of name key must be the name which is presented in Xcode’s UI, as shown below:

Xcode Device Name

So, do not be afraid to use a like with a space, like iPhone 6 Plus, Lei's iPhone 6s.

Please Note, the name is case-sensitive!

Destination Platforms

The platform “key=value” pair is added to specify which destination platform that xcodebuild will run into. Besides iOS, it can also be:

  • OS X
  • iOS
  • iOS Simulator
  • watchOS
  • watchOS Simulator
  • tvOS
  • tvOS Simulator

Each different platform has different keys, like iOS Simulator has available keys name and OS.

Use the Right “SDK”

When using -destination option, you need also set another option sdk correctly. In general,

  • SDK that used for “Simulator” (like iphonesimulator) can only work with iOS Simulator platform.
  • If you need to run into a real device, be sure to use “Device” SDK (like iphoneos).

Use “xcodebuild test”

The default action of xcodebuild is build which is just to build the app. In order to run the app into a iOS simulator or device, you need to use test action.

Not sure why xcodebuild does not come with a run action.

  1. In the normal case, I would recommend to use another CLI tool to help do interaction with the iOS device – iOS-deply (

    The tool is working based on a building app ( and it also provides much more options, like doing debugging, sending / managing files in app’s Documents folder, etc.

    Check it out~~

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>