App Data¶

Clearing an installed package's data on a connected device. clear_app_data runs the unscoped adb shell pm clear, wiping databases, shared preferences, files and cache; it is destructive and only registered when the server opts in. clear_app_cache clears only the cache (pm clear --cache-only on Android 11+, falling back to removing the cache directories as root) and never touches app data.

`clear_app_cache` ¶

Clear only a package's cache, leaving its data intact.

Prefers adb shell pm clear --cache-only (Android 11+). If that command is unsupported, or hangs (a known bug on some emulator images), it falls back to removing the package's per-user cache directories directly (/data/user*/<uid>/<pkg>/cache and code_cache) — which needs adbd running as root. Either path touches only cache, never the app's normal data; this never falls back to the destructive unscoped pm clear.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`package_name`	`str`	The package whose cache to clear, e.g. "com.example.app".	required
`user_id`	`int \| None`	Clear for one specific Android user (see list_users). Omit to clear for the current user — cache is per-user, so a user is always resolved and reported back.	`None`

Returns:

Type	Description
`ClearAppCacheResult`	The serial, package_name, the user_id actually cleared, method ("pm_clear_cache_only" or "rm_cache_dirs"), success (always True — see Error handling), and output.

Error handling

A build where pm clear --cache-only is unavailable AND the direct cache-dir removal is denied (adbd not root) raises CACHE_ONLY_UNSUPPORTED. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. On the pm path: a package not installed for the target user raises PACKAGE_NOT_FOUND, a permission-refused clear raises PERMISSION_DENIED, pm's bare "Failed" raises ANDROID_REJECTED. Any other failure raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", package_name="com.example.app". A typical response:

{
  "status": "success",
  "message": "Cleared cache for com.example.app (user 0) on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "package_name": "com.example.app",
    "user_id": 0,
    "method": "pm_clear_cache_only",
    "success": true,
    "output": "Success\n"
  },
  "error": null
}

`clear_app_data` ¶

Wipe a package's full application data on a device: adb shell pm clear.

Resets the app to a fresh-install state — its databases, shared preferences, files and cache are all deleted. This is the unscoped pm clear, the only variant supported on effectively every Android version; there is no reliable cross-version ADB way to clear just the cache (pm clear --cache-only is Android 11+ only). Use this only when losing the app's data is acceptable.