How do I run an adb shell command?

Switch on developer options and USB debugging on the phone, plug it in, then run adb shell from a machine with platform-tools installed — or run adb shell on its own to get an interactive prompt and type the command without the prefix. If the command produces binary output, such as a screenshot, use adb exec-out instead of adb shell: the plain shell service attaches a terminal, which rewrites newline bytes and corrupts the data.

Do adb shell commands need root?

Not the ones on this reference. They run as the shell user, which can manage packages for its own Android user, read most dumpsys services, write the settings provider, inject input and read shared storage. Root is only needed for things this reference deliberately avoids — reading another app's private data (except through run-as on a debuggable build), writing system partitions, or reading /data/anr directly.

Why does the output look different on my phone?

Either the Android version or the manufacturer. Some flags and fields arrived in a specific release, and those are noted per command. The rest is OEM patching, which hits dumpsys hardest: a dump is debug output whose text is whatever the service author last printed, and manufacturers change it and backport their changes. Read fields by name rather than by position, and treat an unfamiliar shape as a difference rather than as a failure.

Can I run this from a browser instead of a terminal?

For many commands, yes — the Web ADB tools on this site talk to a phone over WebUSB from a Chromium-based desktop browser, with no SDK installed and nothing uploaded. Each page links to the tool that runs its command, when one exists. Two limits are worth knowing: only one program can hold the ADB interface at a time, so a desktop adb server has to be stopped first, and adb forward and adb reverse cannot work in a browser at all.

pm clear

destructive

Wipes an app's data — or, on Android 13 and later, only its cache.

Command: adb shell pm clear
Commands: Packages (pm)
Risk: destructive

Syntax

pm clear [--user <id>] [--cache-only] <package>

Flags and arguments

Token	Meaning
--cache-onlyAndroid 13+	Delete only the cache directory, leaving accounts and data alone.
--user <id>	Which Android user loses the data. Worth stating explicitly so the command you ran is the whole truth about what was cleared.

Examples

```
pm clear --user 0 --cache-only com.example
```
Drop one app's cache on Android 13 or later. The argument order matters — see the notes.
```
pm clear --user 0 com.example
```
Factory-reset one app. Everything inside it is gone.
```
pm help
```
Ask the phone whether it has `--cache-only` at all, instead of inferring it from the Android version.

Reading the output

Sample output

Success

`Success` on stdout, `Failed` on stderr, and `Error: Unknown option: …` when the option loop rejects a flag. `pm clear` always says something, so silence means the command never ran.

Output fields

Field	Meaning
Success	The data (or cache) was deleted.
Failed	Nothing was deleted; the package could not be resolved or the call was refused.
Error: Unknown option:	This build does not know that flag. Only Android 13 and later reject unknown options here.

What access it needs

An authorised `adb` connection. No root, no `su`, and nothing to switch on in developer options: `packages/Shell/AndroidManifest.xml` on the `android16-release` branch declares `CLEAR_APP_USER_DATA` and `DELETE_CACHE_FILES`, which are the permissions `clearApplicationUserData` and `deleteApplicationCacheFilesAsUser` enforce, so a stock build lets the shell user do both halves of this command without ceremony. That is exactly why it earns a confirmation dialog rather than a shrug — what stands between an app's accounts and oblivion is your own typing, not a privilege check. An OEM build that stripped one of those declarations makes the command fail loudly instead of quietly, which is the good failure mode and the one the Android Storage Analyzer passes through verbatim. What no permission protects you from is the pre-Android-13 parser: on those releases the access check passes, the unknown flag is dropped, and the wipe you did not ask for succeeds.

Failure messages, decoded

Message	Meaning
Failed	`runClear` writes exactly this word to stderr when the observer reported failure — the package could not be resolved, or the call was refused. It is also the designed outcome of `pm clear --user 0 --cache-only <pkg>` on Android 12 and earlier, where the old parser takes the flag as a package name and finds nothing to wipe. From that exact command line on an old phone, this word means the defence held.
Error: Unknown option: --cache-only	Android 13's `runClear` iterates over the options and rejects the ones it does not know. Counter-intuitively the line is reassuring: a build old enough to be dangerous never prints it, it accepts the flag silently and deletes everything. Never read the absence of this line as evidence the flag is supported — read `pm help`.
Exception occurred while executing 'clear':	The wrapper caught a `Throwable`, and the line beneath names it; a build that withheld `CLEAR_APP_USER_DATA` from the shell surfaces as a `SecurityException` here. `classifyPmClear` rejects the whole run when such a line appears, even alongside a `Success`, so no wiped entry lands in the log for an app that still has its data.

What it changes, and the way back

`pm clear <pkg>` deletes that app's databases, preferences, accounts and files. Android has no undo and no trash: the app comes back as if freshly installed and you sign in again. `--cache-only` is the survivable variant, and it exists only on Android 13 and later — see the note below, because on older releases the same flag can wipe everything.

Version and vendor notes

On Android 12 and earlier the option parser does not reject `--cache-only`, it *ignores* it — so `pm clear --cache-only com.example` deletes all of that app's data and prints `Success`. Check the device's own `pm help` for the flag rather than guessing from the version.
Putting `--user 0` before `--cache-only` is a real defence, not tidiness: the old single-option parser consumes `--user 0` and then takes `--cache-only` as the package name, which cannot be resolved, so the command fails harmlessly instead of wiping the app.
The shell user is allowed to do this on a stock build; an OEM that stripped the permission makes the command fail loudly rather than silently.

We have a UI for this

Android Storage Analyzer runs this command over USB and parses what comes back — a Chromium browser, no SDK, nothing uploaded.

Open Android Storage Analyzer

Related commands

Commands that turn up in the same session as pm clear.

Command	What it does
pm trim-caches	Asks the system to drop cached files until the given amount of free space exists.
pm uninstall	Removes a package, or removes it for one Android user only — which is how a preinstalled app is disposed of without root.
dumpsys diskstats	Free space per partition, a disk write latency check, and a cached per-app breakdown of what is using storage.
du	Reports how much disk space a directory tree occupies.

More Packages (pm) commands

Command	What it does
pm list packages	Lists installed packages, optionally with the APK path, uid, version code and installer.
pm path	Prints the absolute paths of the APK files that make up an installed package.
pm disable-user	Switches a package off for one Android user without removing it — the reversible alternative to uninstalling.
pm install	Installs one APK that is already on the device, which is what `adb install` does under the hood.
pm install-create	Opens an install session so several APKs — a base plus its splits — are installed as one atomic unit.

Checked against AOSP, toybox and kernel sources while writing the parsers behind our Web ADB tools. Where a behaviour genuinely varies by Android version or manufacturer, this page says so instead of giving a number that would be wrong on half the phones out there.