Skip to content

app_launch

Launches an installed application on a simulator device. You can pass launch arguments to configure the app’s behavior at startup and optionally attach a console PTY to capture the app’s standard output and standard error streams in real time.

Parameters

Parameter	Type	Required	Default	Description
`deviceId`	string	Yes	—	The UDID of the target simulator device.
`bundleId`	string	Yes	—	The bundle identifier of the app to launch.
`args`	string[]	No	`[]`	An array of launch arguments passed to the app on startup.
`consolePty`	boolean	No	`false`	When `true`, attaches a console PTY to capture stdout/stderr from the app.

Usage Examples

Basic app launch

“Launch the WeatherApp on the simulator.”

{
  "deviceId": "F3A1B2C3-D4E5-6789-ABCD-EF0123456789",
  "bundleId": "com.example.weatherapp"
}

Launch with arguments for testing

“Start the app in debug mode with a specific test user.”

{
  "deviceId": "F3A1B2C3-D4E5-6789-ABCD-EF0123456789",
  "bundleId": "com.example.weatherapp",
  "args": ["-UITesting", "-mockAPI", "--user", "testuser@example.com"]
}

Launch with console output enabled

“Launch the app and show me its console output.”

{
  "deviceId": "F3A1B2C3-D4E5-6789-ABCD-EF0123456789",
  "bundleId": "com.example.weatherapp",
  "consolePty": true
}

Launch with environment-like flags

“Start the app with the staging server configuration.”

{
  "deviceId": "A1B2C3D4-E5F6-7890-ABCD-1234567890EF",
  "bundleId": "com.example.shopapp",
  "args": ["-serverEnvironment", "staging", "-enableLogging"],
  "consolePty": true
}

Example Output

App launched successfully.
Device: F3A1B2C3-D4E5-6789-ABCD-EF0123456789
Bundle ID: com.example.weatherapp
PID: 48291
Arguments: -UITesting -mockAPI --user testuser@example.com
Console PTY: attached

app_install — Install the app before launching it.
app_terminate — Stop the app when you are done.
log_stream — Stream system logs filtered to your app for deeper diagnostics.
app_open_url — Open a deep link in the app after it has launched.
screenshot — Capture the screen after the app launches.

Tips