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

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

Examples

$ karagoz terminate com.android.settings
{"device":"emulator-5554","package":"com.android.settings"}exit 0

Output

{
  "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`	`'<value>' is not a package name`, as for launch.
`APP_NOT_FOUND`	The package is not installed. `am force-stop` alone says nothing in that case, so Karagöz checks first.
`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.

{
  "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 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 equivalentterminate {"package":"com.android.settings"}MCP tools

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

karagoz launch: Checks the package name the same way.