Skip to content
idb is a flexible command line interface for automating iOS simulators and devices
Branch: master
Clone or download
lawrencelomax and facebook-github-bot s/fmapReplace/chainReplace
The naming is erroneous. `fmap` should only be `T -> Future<T>` not for errors. Adds a test to this effect.

Instead of changing the implementation, we can follow up with another diff that will change existing implementations that expect the true `fmapReplace` implementation

Reviewed By: zeyadsalloum

Differential Revision: D15898692

fbshipit-source-id: cdda39c5b914d54aee1eea926c5d9f86c1950af4
Latest commit d9e9429 Jun 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add CircleCI config to auto-deploy docs May 1, 2019
.github ℌ𝔢𝔩𝔩𝔬 𝔦𝔡𝔟 Apr 25, 2019
Configuration Add Xcode 9 Default Compiler Warnings Oct 4, 2017
FBControlCore s/fmapReplace/chainReplace Jun 19, 2019
FBControlCoreTests s/fmapReplace/chainReplace Jun 19, 2019
FBDeviceControl Revert D15898131: [idb_companion] stop ignoring pull errors Jun 19, 2019
FBDeviceControlTests Replace -[FBFuture futureWithResult:NSNull.null] with FBFuture.empty May 7, 2019
FBSimulatorControl.xcodeproj Flatten Binary parsing into FBBinaryDescriptor (D15821789 Redux) Jun 18, 2019
FBSimulatorControl s/fmapReplace/chainReplace Jun 19, 2019
FBSimulatorControlTests Remove > Xcode 8 conditionality Jun 4, 2019
Fixtures update bundle id Apr 29, 2019
PrivateHeaders Fix removed method in SimDeviceNotifier Jun 4, 2019
Shims Raise Deployment Target Jun 19, 2019
XCTestBootstrap s/eofHasBeenReceived/finishedConsuming Jun 12, 2019
XCTestBootstrapTests Remove FBApplicationBundle May 20, 2019
docs install-dylib -> dylib install May 16, 2019
fbsimctl Fix missing typo fix Jun 13, 2019
fbxctest s/fmapReplace/chainReplace Jun 19, 2019
idb Add UUID to installs Jun 19, 2019
idb_companion.xcodeproj Remove FBDeltaUpdateManager for Log Jun 13, 2019
idb_companion.xcworkspace ℌ𝔢𝔩𝔩𝔬 𝔦𝔡𝔟 Apr 25, 2019
idb_companion s/fmapReplace/chainReplace Jun 19, 2019
proto Return UUID and Name in grpc Jun 19, 2019
website Upgrade website deps Jun 7, 2019
.dockerignore ℌ𝔢𝔩𝔩𝔬 𝔦𝔡𝔟 Apr 25, 2019
.gitignore Text lint all .gitignore files May 15, 2019
.travis.yml Fix travis builds Apr 10, 2019 Add Code of Conduct Oct 30, 2018
Cartfile.private Move OCMock to Cartfile.private file Apr 1, 2016
Cartfile.resolved Extracted XCTestBootstrap Mar 14, 2016
Dockerfile ℌ𝔢𝔩𝔩𝔬 𝔦𝔡𝔟 Apr 25, 2019
LICENSE Re-license as MIT Mar 8, 2019 Add required dependencies to build idb companion (#527) May 15, 2019 Fix typos in build script usage texts (#518) May 7, 2019
docker-compose.yml ℌ𝔢𝔩𝔩𝔬 𝔦𝔡𝔟 Apr 25, 2019 Fix typos in build script usage texts (#518) May 7, 2019 Correct classifier Apr 26, 2019


idb logo

The “iOS Development Bridge” or idb, is a command line interface for automating iOS Simulators and Devices for development. It has three main goals:

  • Remote Automation. idb has a “companion” that runs on macOS and a python client and cli that runs anywhere. This enables scenarios such as a “Device Lab” within a Data Center or fanning out commands to large numbers of iOS Simulators.
  • Simple Primitives. idb exposes granular APIs that enable building more sophisticated workflows on top. This means you can use idb from an IDE or build an automated testing scenario that is more than just running a set of tests. All of these primitives are consistent across OS Versions and between Simulators and Devices. The cli is intended to also be easy to use for humans as well as automation, as such it provides terse and self-documenting commands.
  • Exposing missing functionality. Xcode has a number of features that aren't available outside it's own UI. idb exposes many of these features so that they can be used within other GUI-less automation.

idb is largely built from the FBSimulatorControl and FBDeviceControl Frameworks, contained within this repository. These Frameworks can be used independently of idb, but idb is likely to provide the simplest install and the most sensible defaults for most users.

We've given a talk about idb at F8, so that you can learn a bit more about what idb is and why we built it. A recording of the talk is available here.

Quick Start

Under Construction please bear with us. the quick start steps might not be working for you yet.

idb is made up of 2 parts, each of which needs to be installed separately.

idb companion

Each target (simulator/device) will have a companion process attached allowing idb to communicate remotely.

The idb companion can be installed via brew or built from source

brew tap facebook/fb
brew install idb-companion

Note: Instructions on how to install brew can be found here

idb client

A cli tool and python client is provided to interact with idb.

It can be installed via pip:

pip3.6 install fb-idb

Note: The idb client requires python 3.6 or greater to be installed.

Please refer to for detailed installation instructions and a guided tour of idb.

Once installed, just run the list-targets command which will show you all the simulators installed on your system:

$ idb list-targets
iPhone X | 569C0F94-5D53-40D2-AF8F-F4AA5BAA7D5E | Shutdown | simulator | iOS 12.2 | x86_64 | No Companion Connected
iPhone Xs | 2A1C6A5A-0C67-46FD-B3F5-3CB42FFB38B5 | Shutdown | simulator | iOS 12.2 | x86_64 | No Companion Connected
iPhone Xs Max | D3CF178F-EF61-4CD3-BB3B-F5ECAD246310 | Shutdown | simulator | iOS 12.2 | x86_64 | No Companion Connected
iPhone Xʀ | 74064851-4B98-473A-8110-225202BB86F6 | Shutdown | simulator | iOS 12.2 | x86_64 | No Companion Connected

list-apps will show you all the apps installed in a simulator:

$ idb list-apps --udid 74064851-4B98-473A-8110-225202BB86F6 | Maps | system | x86_64 | Not running | Not Debuggable | MobileSMS | system | x86_64 | Not running | Not Debuggable | MobileSlideShow | system | x86_64 | Not running | Not Debuggable | MobileSafari | system | x86_64 | Not running | Not Debuggable

launch will launch an application the application:

$ idb launch

Head over here for more details on what you can do with idb and the full list of commands.

Building from Source

idb is made up of 2 parts.

To build the python part make sure you are in the root of the repo and run:

pip3 install .

To build the objective-c/c++ part:

Make sure you have installed gRPC dependencies: brew tap grpc/grpc && brew install grpc

open idb_companion.xcworkspace

This will open an xcode project that you can build and run.


Find the full documentation for this project at


We've released idb because it's a big part of how we scale iOS automation at Facebook. We hope that others will be able to benefit from the project where they may have needs that aren't currently serviced by the standard Xcode toolchain.

Code of Conduct

Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contributing Guide

Read our contributing guide to learn about our development process.


idb is MIT-licensed.

You can’t perform that action at this time.