A step by step guide to exporting your build to Waldo.

There are two supported options to export your iOS simulator build to Waldo:

  1. with Waldo CLI — which we highly recommend
  2. from Xcode

Exporting your iOS simulator build with Waldo CLI

If you haven’t yet installed Waldo CLI, simply follow the instructions here.

Once you have verified that Waldo CLI is correctly installed, exporting your iOS simulator build can be as simple as typing two commands into your terminal window.

Here’s the first command:

waldo add ios --upload_token <<waldoUploadToken>>

The waldo add command performs the following actions:

  1. It first searches the current working directory (and then its parent directories) for a configuration file named config.yml in a hidden directory named .waldo.
  2. If waldo add finds an existing configuration file, it uses that. Otherwise, it creates an empty .waldo/config.yml.
  3. It then attempts to add a recipe named “ios” to the configuration file (assuming a recipe with that name does not already exist). The name “ios” is arbitrary. You can name your recipe pretty much anything you want.
  4. If waldo add determines that there is more than one way to generate a build in the current working directory, it will ask you a series of multiple choice questions to construct the recipe. For example, if the current working directory contains more than one Xcode project or workspace, it will ask you which project or workspace it should use. If the chosen project or workspace defines more than one scheme, it will ask you again which scheme it should use. And so on.
  5. Finally, if you specify the --upload_token option, waldo add associates the upload token with the recipe. While this is not required, it is preferable that you do it now in order to avoid you having to specify it later whenever you wish to upload a build generated by this recipe.

Once you have added a particular recipe to the configuration file, you need not do it again. If you save your Waldo CLI configuration file in your source code repository, any one with access to the repository can make use of your recipe(s).

And here’s the second command:

waldo sync ios

The waldo sync command is simply a shorthand for the waldo build followed by the waldo upload command. The waldo build command performs the following actions:

  1. It looks up the “ios” recipe in the configuration file.
  2. It then generates the actual build>> (using xcodebuild in this case).

The waldo upload command performs the following actions:

  1. It looks up the “ios” recipe in the configuration file.
  2. It then attempts to find the actual build generated by the preceding waldo build action.
  3. Finally, if it finds the previous build, waldo upload attempts to send it to Waldo.


Tip: If you have only one recipe defined in your Waldo configuration, you can omit the recipe name from the waldo sync command (as well as the waldo build and waldo upload commands).

That’s it! See waldo help and waldo help <command> for more information about what you can do with Waldo CLI.

Exporting an iOS simulator build from Xcode

If you choose not to use Waldo CLI, you can also export your iOS simulator build from within Xcode.

Before you can upload an iOS simulator build to Waldo, you must first export the ‘.app’ file from Xcode. Simply follow the steps below:

  1. Launch Xcode and open the project or workspace for your application.

  2. Choose an appropriate scheme, as well as a simulator, from the drop-down menu on the toolbar. It doesn’t matter which simulator you choose, any simulator will do.


  1. Choose Product > Build to build your application.
  1. When the build completes, choose Product > Show Build Folder in Finder.
  1. A folder containing your ‘.app’ file appears in Finder. You can upload this ‘.app’ file on Waldo!
  1. Zip your .app and drag and drop it into Waldo
    Upload it with Waldo CLI as described in the preceding section.

Build for Apple Silicon / M1 chips / arm64 architecture

Are my iOS builds Apple Silicon ready ?

How to tweak my config to make it so

Xcode 12.2 and later automatically adds the arm64 architecture to the list of standard architectures for all iOS simulator binaries, including apps and libraries. During the debugging and testing process, Xcode builds only for the current system architecture by default.

The Xcode config of your target should be set like in the image below: (the popover menu must read Standard Architectures (arm64) - $(ARCHS_STANDARD))

This is the easiest (and safest) way to edit the Xcode configuration file that will be used by your CI to generate your simulator build.


If you encounter trouble while uploading a new build of your application to Waldo, you can refer to the following: