# karagoz terminate

Stops an app with am force-stop: every process of the package is killed before the command returns, and Android removes its alarms, scheduled jobs and notifications.

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

## Usage

```console title="~/app"
karagoz terminate <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. |
| `--device <id>` | see [Device selection](https://karagozmcp.com/docs/device-selection/) |                   |

## Examples

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

## Output

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

On every target, an app that is installed but not running gives the same output.

- `device` string: Serial, or the simulator's or iPhone's UDID.
- `package` string: The package name.

## Errors

| Code                                                                      | When                                                                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`INVALID_ARGS`](https://karagozmcp.com/docs/error-codes/#invalid-args)   | `'<value>' is not a package name`, as for [launch](https://karagozmcp.com/docs/commands/launch/).       |
| [`APP_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#app-not-found) | The package is not installed. `am force-stop` alone says nothing in that case, so Karagöz checks first. |
| [`ADB_FAILED`](https://karagozmcp.com/docs/error-codes/#adb-failed)       | `am force-stop` printed an error; the message is that error.                                            |

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

## Notes

- Only the package’s own processes stop. An activity from another package in the same task stays on screen: after `terminate com.android.settings` with the Settings search open, the search is still in front.
- The app stops in every user on the device, Secure Folder and work profiles included.

## On an iOS simulator

Runs `simctl terminate`. System apps are stopped like any other.

```json
{
  "device": "2EC769C1-2EF2-47EB-A441-E6843968F039",
  "package": "com.apple.Preferences"
}
```

- Stopping the app in front shows the home screen’s first page, not the app that was open before.
- `APP_NOT_FOUND` when it is not installed: simctl answers that the same way as an app that is not running, so Karagöz checks first.
- An app stopped in a debugger (an Xcode breakpoint or pause) does not stop until the debugger lets it run. Karagöz exits with [`SIMCTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#simctl-timeout) after 30 s, and the app stops when it continues or the debug session ends. Other calls to that simulator can time out for up to 5 minutes.
- An app that runs under the debugger stops at once, and Xcode’s session ends.

## On an iPhone

Looks the app up with `devicectl device info apps`, then kills every process running from its bundle, the app and its extensions, with `devicectl device process terminate --kill`. System apps are stopped like any other.

- `APP_NOT_FOUND` when it is not installed.
- An app stopped in a debugger, or started stopped, stops at once.

## MCP equivalent

MCP equivalent `terminate {"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 launch](https://karagozmcp.com/docs/commands/launch/): Checks the package name the same way.