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.

am start

read-only

Starts an activity by component or by intent — the fastest way to test whether a deep link resolves.

Command: adb shell am start
Commands: Activities and intents (am)
Risk: read-only

Syntax

am start [-W] [-a <action>] [-d <data URI>] [-n <package>/<activity>] [<extras>]

Flags and arguments

Token	Meaning
-W	Wait for the launch to complete and print its status and timings.
-a <action>	The intent action, e.g. `android.intent.action.VIEW`.
-d <uri>	The intent data URI. A scheme is required: without one there is nothing to match an intent filter against.
-n <pkg>/<activity>	Start one exact component, bypassing intent resolution.

Examples

am start -W -a android.intent.action.VIEW -d 'myapp://item/42'

Test a deep link and see which activity claimed it.

am start -W -a android.intent.action.VIEW -d 'https://example.com/item/42'

Test an App Link, including whether the browser wins instead of your app.

```
am start -n com.example/.MainActivity
```
Launch one activity directly, no intent filter involved.

Reading the output

Sample output

Starting: Intent { act=android.intent.action.VIEW dat=https://example.com/ flg=0x10000000 }
Status: ok
LaunchState: COLD
Activity: com.example/.MainActivity
TotalTime: 245
WaitTime: 262
Complete

With `-W` you get the intent as the platform parsed it, then the outcome. The interesting failures are not status lines at all: `Error: Activity not started, unable to resolve Intent { … }` is what an unclaimed scheme looks like, and `Warning: Activity not started, its current task has been brought to the front` is a success with a caveat — the app was already open, so nothing was cold-started and no timings are printed.

Output fields

Field	Meaning
Status: ok	An activity was started.
LaunchState	COLD, WARM or HOT — how much of the app was already alive.
Activity	The component that won the intent.
TotalTime	Milliseconds to the activity being drawn. Absent when nothing was launched.
WaitTime	Milliseconds including the time the caller was blocked.
Error: … unable to resolve Intent	Nothing on the phone claims that intent. Often the answer you were testing for.

What access it needs

An authorised `adb` connection. No root, no `su`, and no developer-options switch beyond USB debugging itself — launching an activity is something the `shell` user is ordinarily permitted to do, which is what makes this the cheapest deep-link test available. The limit is per component rather than global: the platform can decline one particular launch, and when it does the refusal arrives as a `SecurityException` or a `Permission Denial` line instead of a `Status:` line. `parseAmStartResult` watches for exactly those two shapes and hands the device's own sentence back verbatim, because that line names its own reason and paraphrasing it would throw away the only detail worth having. Adding `-p <package>` narrows a launch to one app, which is how you find out which app claims a link when several compete for it; it grants nothing extra and cannot make a declined launch succeed.

Failure messages, decoded

Message	Meaning
Error: Activity not started, unable to resolve Intent	Written to stderr, followed by the intent exactly as the platform built it. Nothing on the phone claims that scheme, which for a deep-link test is usually the finding you were after rather than a fault. Read the brace contents first: a URL that lost everything past an unquoted ampersand resolves to a different intent than the one you meant to test.
Warning: Activity not started, its current task has been brought to the front	A success with a caveat. The app was already open, so its existing task was raised rather than cold-started, and neither `TotalTime` nor `WaitTime` is printed. Their absence is a fact about the launch, not a zero-millisecond result; stop the app first when you wanted a cold-start measurement.
Status: timeout	The launch was accepted but the activity never reported itself drawn within the window `-W` waits. The app is very likely running; what failed was the measurement, so repeat it before reading anything into the number that never arrived.

Version and vendor notes

Single-quote the URI. A URL legitimately contains `&`, and an unquoted ampersand backgrounds the command and silently drops the rest of the query string — the classic reason a hand-typed deep-link test appears not to work.
`-d` without a scheme starts nothing: the intent's data cannot be built, and no filter can match it.
Timings are printed only for a real launch, so their absence is a fact about the launch rather than a 0 ms result.

We have a UI for this

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

Open Android ADB Toolbox

Related commands

Commands that turn up in the same session as am start.

Command	What it does
am broadcast	Sends a broadcast intent, which is how SystemUI demo mode and other platform receivers are driven from a shell.
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.

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.