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.

top

read-only

A one-shot process table: CPU share, memory, state and command line.

Command: adb shell top
Commands: System and logs
Risk: read-only

Syntax

top -b -n 1 [-m <rows>] [-H] [-q]

Flags and arguments

Token	Meaning
-b	Batch mode: plain lines instead of cursor escapes.
-n 1	One iteration, then exit. Without it the command never returns.
-m <rows>	Cap the number of process rows, which is what keeps the transfer small.
-H	Threads instead of processes.
-q	Suppress the header. Never useful here — the header is the schema.
-p <pid>,	Limit the table to these process ids, comma separated. The cheapest way to watch one app over a cable without shipping every row on the phone with it.
-u <user>,	Limit the table to these users. On Android a user is a uid name such as `u0_a234`, which is where an installed app's rows live; system services answer to names of their own.
-d <seconds>	Delay between cycles, accepting a fraction. It is stored in milliseconds with a floor of a tenth of a second and a default of three seconds, and it is irrelevant once `-n 1` is in play.
-k <field>,	Fallback sort fields. The built-in default is state first, then CPU, then elapsed time, then pid — which is why an apparently idle row can sit at the top of the table.
-o <field>,	Replace the column set entirely. Mutually exclusive with `-O`, and the fastest way to shrink a capture: five columns instead of twelve is less than half the bytes.
-O <field>,	Add columns to the default set, displacing the block of memory and priority columns rather than appending to the end of the row.

Examples

```
top -b -n 1 -m 10
```
The ten busiest processes, once.
```
top -b -n 1
```
Every process. Hundreds of rows on a modern phone.
```
top -b -n 1 -H -m 20
```
Per-thread, for an app that is busy in one place.
```
top -b -n 1 -o PID,USER,%CPU,RSS,ARGS
```
A narrower table: five columns rather than twelve, a much smaller transfer, and still enough to find whatever is busy.
```
top -b -n 1 -p 3062
```
One process, sampled once — the form to reach for when you already know which pid you are arguing with.

Reading the output

Sample output

Tasks: 1003 total,   1 running, 1002 sleeping,   0 stopped,   0 zombie
  PID USER         PR  NI VIRT  RES  SHR S[%CPU] %MEM   TIME+ ARGS
 3062 u0_a234      20   0 14.2G 353M 210M S  6.2   3.0  12:04.51 com.example

Summary lines, a header, then one row per process. Read the columns through that header: the sorted column is wrapped in brackets — `S[%CPU] %MEM` is two columns, not one — and a parser that matches labels exactly without stripping the brackets loses the very column the table is sorted on.

Output fields

Field	Meaning
PID / USER	Process id and the Android uid name (`u0_a234` is an app).
%CPU	Share over the sample window, one decimal place.
RES / VIRT / SHR	Resident, virtual and shared memory as human-readable byte values, rounded to three digits.
RSS	Resident memory in KiB assuming a 4 KiB page — which is toybox's own assumption, so it under-reports on a 16 KiB-page device.
S	Process state: S sleeping, R running, D uninterruptible, Z zombie.
TIME+	Total CPU time as minutes:seconds.hundredths — and those are total minutes, so two hours of CPU prints as 120:00.00.
ARGS	The command line, spaces included. Always the last column.
PR	Scheduling priority, carried as text because a realtime process prints the letters `RT` where a number would otherwise be.
NI	The nice value. Android throttles mainly through scheduler groups, so this reads zero on plenty of processes that are being held back anyway.
%MEM	Share of physical memory to one decimal place, printed without the decimal once it reaches a hundred.
Tasks: … total, … running	The first summary line: counts, not sizes. The memory summaries beneath it restate kernel counters in a rounded form and are not numbers to compute with.

What access it needs

No root and no `adb root` — and that this works at all is an arrangement somebody made on purpose rather than an accident of file modes. `/proc` is mounted during first-stage init with `hidepid=2` and a gid of `AID_READPROC`, which hides every process directory from anyone outside that group; `adbd` then puts `AID_READPROC` into the supplementary group list it hands the `shell` user just before it drops privileges. So a cable sees the entire process table while an app on the same phone sees only itself, and the whole difference is one supplementary gid rather than a permission anything can be granted at runtime. Everything on this page is read-only: `top` opens the per-process files under `/proc` and prints what it reads. Two consequences follow from where the numbers come from. A process that exits mid-sample simply drops out of the table instead of producing an error, so two consecutive one-shot runs can legitimately disagree about how many tasks exist. And the command-line column is read from a file that is empty for kernel threads and can be unreadable for a process the shell has no business inspecting, so a blank command line is missing information rather than a parsing failure. Ending a process is `am force-stop`, a different page with a different answer to the access question; nothing here can stop anything.

Failure messages, decoded

Message	Meaning
top: Unknown option 'x' (see "top --help")	toybox does not know that letter, and it quotes whatever remained of the argument after the dash, so `-bx` is reported as `x` rather than as the whole word. Check it against the flags table on this page rather than against a GNU manual: the two programs called `top` share a name and very little else.
top: -n < 1 (see "top --help")	`-n 0` does not mean "run forever"; the option is declared with a minimum of one, so zero is simply out of range and nothing runs. To take a single sample and exit, `-n 1` is the whole answer.
top: Max 0 arguments (see "top --help")	`top` accepts no positional arguments whatsoever. In practice this is a `-p` or `-u` list that lost its flag, or a stray word carried over from the line above — and because the check happens before anything runs, nothing was sampled.
top: No 'O' with 'o' (see "top --help")	`-o` replaces the column set outright while `-O` adds to it, so asking for both would leave the header undefined and the command refuses instead of choosing. Pick whichever one describes what you meant: replace, or extend.
top: no /proc	The `/proc` tree could not be walked at all, so no process could be described. On a booted phone this says something about where the command is running rather than about the phone: it is what you get in an environment that has no `/proc` mounted, not evidence that the device has no processes.

Version and vendor notes

Android's `top` is toybox, not procps, and the flags and columns differ from the GNU manual pages. The default column set comes from the code rather than from the help text.
`-n 1` still takes about a quarter of a second, because a CPU percentage needs two samples. The number you get is a real short measurement, not an average since boot.
Do not derive memory totals from the summary lines: they restate kernel counters in a lossy rounded form. `/proc/meminfo` is the better source.
`/proc` is mounted with `hidepid=2` and a `readproc` gid, and the shell is placed in that group by `adbd`. That single arrangement is why a cable sees every process without root — and why the same command inside an app sees only that app.
The built-in fallback sort orders by state before CPU, so the row at the top of the table is sorted there rather than necessarily being the busiest thing on the phone. Read `%CPU` before drawing a conclusion from position.

We have a UI for this

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

Open Android System Monitor

Related commands

Commands that turn up in the same session as top.

Command	What it does
dumpsys meminfo	Which processes are using the most memory, measured as proportional set size.
am force-stop	Kills every process and service belonging to one app.
dumpsys activity activities	Which app is in the foreground, and the task and stack structure behind it.

More System and logs commands

Command	What it does
getprop	Prints the system properties — the phone's own answer to what it is.
logcat	Streams the system log: the running commentary of everything happening on the phone.
run-as	Runs a command as one app's own uid — the way to read a debug build's private files without root.

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.