Skip to content

physical_device_launch

Launch an app that is already installed on a connected physical iOS device. This tool starts the specified app by its bundle identifier on the target device, bringing it to the foreground. It is typically used after physical_device_install to immediately run the newly installed build.

Parameters

Parameter	Type	Required	Default	Description
`deviceId`	string	Yes	—	The UDID of the target device (obtain from `physical_device_list`)
`bundleId`	string	Yes	—	The bundle identifier of the app to launch (e.g., `"com.acmecorp.fitnesstracker"`)

Usage Examples

Launch the app after installation

“Launch FitnessTracker on my iPhone 15 Pro Max”

{
  "deviceId": "00008130-001A2B3C4D5E6F78",
  "bundleId": "com.acmecorp.fitnesstracker"
}

Launch on a different test device

“Start the app on the iPhone 14 test device”

{
  "deviceId": "00008110-001122334455AABB",
  "bundleId": "com.acmecorp.fitnesstracker"
}

Launch a different app on the same device

“Open the Settings companion app on my iPhone”

{
  "deviceId": "00008130-001A2B3C4D5E6F78",
  "bundleId": "com.acmecorp.fitnesstracker.settings"
}

Example Output

Launching app on device...

Device:      iPhone 15 Pro Max (00008130-001A2B3C4D5E6F78)
Bundle ID:   com.acmecorp.fitnesstracker

App launched successfully.

When the launch fails:

Launching app on device...

Device:      iPhone 15 Pro Max (00008130-001A2B3C4D5E6F78)
Bundle ID:   com.acmecorp.fitnesstracker

Error: Launch failed.
  The app with bundle ID "com.acmecorp.fitnesstracker" is not installed
  on device 00008130-001A2B3C4D5E6F78.

  Use physical_device_install to install the app first.

physical_device_install — Install the app before launching it
physical_device_list — Find the UDID of the target device
physical_device_console — Stream console logs after launching to debug runtime behavior
xcode_build — Build the app before installing and launching

Tips