# karagoz uninstall

Removes an app and its data.

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

## Usage

```console title="~/app"
karagoz uninstall <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 uninstall dev.karagoz.smoke
{"device":"emulator-5554","package":"dev.karagoz.smoke"}
```

## Output

```json
{
  "device": "emulator-5554",
  "package": "dev.karagoz.smoke"
}
```

- `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. Checked first, because Android answers a missing package with `DELETE_FAILED_INTERNAL_ERROR`, the same code it gives for a package it will not remove. |
| [`UNINSTALL_FAILED`](https://karagozmcp.com/docs/error-codes/#uninstall-failed) | Android refused. The message is Android's `Failure [...]` line and `reason` its code, such as `DELETE_FAILED_INTERNAL_ERROR` for a system app with no updates.                       |

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

## Notes

- A system app with installed updates goes back to its factory version. Android reports that as success, and so does Karagöz.
- The app’s data is always removed; `adb uninstall -k` (keep data) is not offered.
- The app and its data go from every user on the device, Secure Folder and work profiles included. The installed check looks at the main user only, so an app installed only in a profile gives `APP_NOT_FOUND`.

## On an iOS simulator

Runs `simctl uninstall`.

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

- A system app is refused before anything is sent, since a simulator can lose it until it is erased:

  ```json
  {
    "error": {
      "code": "UNINSTALL_FAILED",
      "message": "'com.apple.Preferences' is a system app; a simulator does not remove system apps",
      "reason": "SYSTEM_APP"
    }
  }
  ```

- A running app is killed first; the home screen then shows the page its icon was on.

- `APP_NOT_FOUND` when it is not installed: simctl reports success for a missing app, so Karagöz checks first. A refusal from simctl is `UNINSTALL_FAILED` with its `<domain>:<code>` as `reason`.

- An app stopped in a debugger ends the call in [`SIMCTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#simctl-timeout) after 30 s, as with `install`. The app is removed once the debugger lets it run or the debug session ends.

## On an iPhone

Runs `devicectl device uninstall app`.

- A system app such as Settings is refused before anything is sent: `UNINSTALL_FAILED`, `reason` `SYSTEM_APP`, `'com.apple.Preferences' is a system app; an iPhone does not remove system apps`.
- `APP_NOT_FOUND` when it is not installed: devicectl reports success for a missing app, so Karagöz checks first. A refusal is `UNINSTALL_FAILED` with the phone’s `<domain>:<code>` as `reason`.
- A running app, also one stopped in a debugger, is killed and removed. A locked iPhone removes too.

## MCP equivalent

MCP equivalent `uninstall {"package":"dev.karagoz.smoke"}` [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.