# karagoz launch

Starts an app the way tapping its launcher icon does.

- Android emulator Done
- Android device Done
- iOS simulator Done
- iOS device Done

## Usage

```console title="~/app"
karagoz launch <package> [--device <id>]
```

## Before you start

- On an iOS simulator: Xcode, opened once.
- On an iPhone: Xcode 15 or newer, paired with the Mac, Developer Mode on (Settings > Privacy & Security > Developer Mode).

## Options

| Option          | Default                                                               | Meaning                                           |
| --------------- | --------------------------------------------------------------------- | ------------------------------------------------- |
| `<package>`     |                                                                       | The package name, such as `com.android.settings`. |
| `--device <id>` | see [Device selection](https://karagozmcp.com/docs/device-selection/) |                                                   |

## Examples

```console title="~/app"
$ karagoz launch com.android.settings
{"device":"emulator-5554","package":"com.android.settings","activity":"com.android.settings/.homepage.SettingsHomepageActivity"}
```

## Output

```json
{
  "device": "emulator-5554",
  "package": "com.android.settings",
  "activity": "com.android.settings/.homepage.SettingsHomepageActivity"
}
```

- `device` string: Serial, or the simulator's or iPhone's UDID.
- `package` string: The package name, such as `com.android.settings`.
- `activity` string or null: The activity Android reports as started, in its `package/.Class` short form, or `null` when Android names none. On iOS always `null`. See below.

`activity` is not always the launcher activity:

- Settings’ launcher activity `.Settings` hands off to `.homepage.SettingsHomepageActivity`, and that one is reported.
- If the app’s task is already running, it comes to the front as it is, and its top activity is reported, even one from another package. With the Settings search open, `launch com.android.settings` reports `com.google.android.settings.intelligence/.modules.search.activity.SearchActivity`.

## Which activity is started

Android’s own rule for launch intents: the first activity with the `MAIN` action and the `INFO` category, otherwise the first with `MAIN` and `LAUNCHER`. With two launcher activities the first one Android lists is started; no chooser appears.

## Errors

| Code                                                                                | When                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`INVALID_ARGS`](https://karagozmcp.com/docs/error-codes/#invalid-args)             | `'<value>' is not a package name`. A package name is letters, digits and `_`, in dot-separated parts that each start with a letter. Checked before any device call, except for a value that is a valid iOS bundle id (`com.foo-bar`, `1abc.x`): that one is refused once an Android device is picked. |
| [`APP_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#app-not-found)           | `package 'dev.karagoz.nope' is not installed on emulator-5554`.                                                                                                                                                                                                                                       |
| [`APP_NOT_LAUNCHABLE`](https://karagozmcp.com/docs/error-codes/#app-not-launchable) | `package 'com.android.shell' has no launcher activity`.                                                                                                                                                                                                                                               |
| [`ADB_FAILED`](https://karagozmcp.com/docs/error-codes/#adb-failed)                 | Android refused the start. The message is Android's `Error:` line, such as `Error: Activity class {com.example/com.example.Main} does not exist.`                                                                                                                                                     |
| [`ADB_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#adb-timeout)               | After 30 s. Android itself gives up after 10 s for a process to start and 10 s for the activity to settle.                                                                                                                                                                                            |

Every launch can also get the device selection errors and the adb errors.

## Notes

- Exit `0` means Android started the activity, not that the app is up. An app that crashes at start, and a start with the screen off, also exit `0`. Read the [tree](https://karagozmcp.com/docs/commands/ui-tree/) to check.
- Nothing is restarted or cleared. For a fresh start, run [`terminate`](https://karagozmcp.com/docs/commands/terminate/) first.

## On an iOS simulator

`<package>` is the bundle id, such as `com.apple.Preferences`: letters, digits, `-` and `_`, in dot-separated parts. Runs `simctl launch`.

```json
{
  "device": "2EC769C1-2EF2-47EB-A441-E6843968F039",
  "package": "dev.karagoz.probe",
  "activity": null
}
```

- It returns when the app’s process starts, before the app is in front: a `ui-tree` read right away can still show the previous screen. The app was in front 0.3 to 1.5 s later.
- `activity` is always `null`.
- An app that crashes at start also exits `0`. A running app comes to the front as it is.
- `APP_NOT_FOUND`: `app 'dev.karagoz.nope' is not installed on <udid>`. Any other refusal is [`SIMCTL_FAILED`](https://karagozmcp.com/docs/error-codes/#simctl-failed) with simctl’s message. `APP_NOT_LAUNCHABLE` does not come from a simulator: a bundle without an executable is refused at install.

## On an iPhone

Runs `devicectl device process launch`, with `<package>` the bundle id.

- It returns when the app’s process starts, before the app is in front.
- A running app, also one in the background, comes to the front with the same process; nothing is restarted.
- `activity` is always `null`.
- `APP_NOT_FOUND`: `app 'dev.karagoz.nope' is not installed on <UDID>`. Any other refusal is [`DEVICECTL_FAILED`](https://karagozmcp.com/docs/error-codes/#devicectl-failed) with devicectl’s description and the phone’s reason, such as an app whose developer the phone does not trust yet.
- A locked iPhone gives [`DEVICE_NOT_READY`](https://karagozmcp.com/docs/error-codes/#device-not-ready) after about 10 s.
- An app stopped in a debugger, or started stopped, holds the launch until it continues: Karagöz exits with [`DEVICECTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#devicectl-timeout) after 30 s, and the message names that cause.

## MCP equivalent

MCP equivalent `launch {"package":"com.android.settings"}` [MCP tools](https://karagozmcp.com/docs/mcp/#tools)

Arguments: `package` (required), `device`. The names are the CLI's option and positional names.

## Related commands

- [karagoz ui-tree](https://karagozmcp.com/docs/commands/ui-tree/): Read the tree after the launch to check that the app is up.
- [karagoz terminate](https://karagozmcp.com/docs/commands/terminate/): Run it first for a fresh start: launch restarts and clears nothing.