With adb shell am and pm, how do you reset an Android app and relaunch one screen to reproduce a tester's bug repeatably?
answer
- two shell tools, two jobs
- stop the process, then wipe its data
- launch an explicit component with extras
- install flags that keep or grant
- quoting twice through the shell
basics
~20 sUse pm for the package and am for the running app: am force-stop and pm clear return it to a fresh-install state, pm grant sets permissions, and am start -n with extras opens the exact screen, so every attempt starts identically.
solid answer
~50 s`pm`, the package manager, acts on what is installed, and `am`, the activity manager, acts on what is running. A clean repro starts with `adb shell am force-stop com.example.shop`, which stops everything tied to the package, and `adb shell pm clear com.example.shop`, which deletes all of its data. `pm grant` and `pm revoke` put each permission the manifest declares into a known state. Then `adb shell am start -W -n com.example.shop/.LoginActivity --es prefill_user qa7` opens that exact activity with a string extra and waits for the launch to complete. `-S` force-stops the app before starting it. For the build itself, `adb install -r` replaces the APK and keeps its data, `-g` grants every manifest permission, `-d` allows a version-code downgrade and `-t` installs a test APK. Script these steps and every attempt starts from the same state.
code
console · 5 lines$ adb install -r -g app-debug.apk
$ adb shell am force-stop com.example.shop
$ adb shell pm clear com.example.shop
$ adb shell pm grant com.example.shop android.permission.CAMERA
$ adb shell am start -W -n com.example.shop/.LoginActivity --es prefill_user qa7go deeper
Recall which tool does what: pm for installed packages and permissions, am for starting and stopping. Know pm clear and am start -n.
Explain the reset sequence and why each step is needed, the typed extras on am start, and what install -r, -g, -d and -t change.
Show a scripted, repeatable repro from a tester's report, including debugger attach at startup and the double quoting that breaks commands.
Weigh a shared repro script that every tester and CI job runs against ad hoc manual steps, and decide which device state the team treats as the baseline.
## Two tools, two jobs Inside `adb shell` the device offers two command-line tools that QA engineers and app developers use every day. You can run either one directly, for example `adb shell pm list packages -3`, without opening an interactive shell first. | Tool | Acts on | Typical commands | |---|---|---| | `pm` (package manager) | installed packages and their permissions | `list packages`, `path`, `clear`, `grant`, `revoke`, `uninstall` | | `am` (activity manager) | running components and processes | `start`, `force-stop`, `kill`, `broadcast`, `set-debug-app`, `dumpheap` | A tester reports that the shop app freezes right after login. You will try many fixes, so each attempt has to start from the **same state**. If it does not, you will never know whether a fix worked. ## Resetting to a known state 1. `adb shell am force-stop com.example.shop` stops everything associated with the package. 2. `adb shell pm clear com.example.shop` deletes all data associated with the package: databases, preferences and files. The result is a fresh-install state, but the app stays installed. 3. `adb shell pm grant com.example.shop android.permission.CAMERA` (or `pm revoke`) sets a runtime permission. On Android 6.0 (API level 23) and higher it can be any permission the manifest declares. How the app asks for and handles permissions belongs to the lesson on the manifest and permissions. Do not confuse `am force-stop` with `am kill`. `am kill` ends only the processes that are **safe to kill**, the ones whose loss does not affect what the user sees. That is why it is commonly used to simulate background process death, which the lesson on activities and fragments covers. `am force-stop` stops the package outright. ## Launching exactly one screen `am start` builds an intent from flags: - `-n com.example.shop/.LoginActivity` names a component, so the intent is **explicit**. `-a android.intent.action.VIEW -d <uri>` builds an implicit one instead; how an implicit intent resolves is covered with intents. - Extras are typed: `--es` adds a string, `--ez` a boolean, `--ei` an int, `--el` a long and `--eu` a URI. - `-W` waits for the launch to complete, `-S` force-stops the target app first, `-R <count>` repeats the launch and `-D` enables debugging. To debug a crash that happens during startup, `adb shell am set-debug-app -w com.example.shop` makes the next launch wait for a debugger. `--persistent` keeps that setting, and `am clear-debug-app` removes it. ## Installing the build under test `adb install` accepts the install options documented for `pm install`, among them: - `-r` reinstalls an existing app and **keeps its data**, which is how you upgrade over a tester's state. - `-d` allows a version-code downgrade, and `-g` grants every permission the manifest lists. - `-t` is needed for a test APK. `install-multiple` installs a set of split APKs together. - `adb shell pm uninstall -k` removes the package but keeps its data and cache directories. ## Other am and pm commands worth knowing - `pm list packages -3 shop` shows only third-party packages whose name contains `shop`, and `pm path <package>` prints where the APK lives. - `am broadcast` sends an intent to receivers. How receivers are declared and exported is covered with intents and IPC. - `am display-size 1280x800` and `am display-density 480` make a large device behave like a smaller or denser screen, and `am display-size reset` undoes the override. - `am instrument -w <test_package>/<runner_class>` runs instrumentation tests. `-w` is required for test runners, and `--no-window-animation` turns window animations off for the run. - Many of these commands accept `--user <id>` on a device with several users. ## Quoting through two shells Since Platform Tools 23, adb passes arguments the way `ssh` does, so your local shell takes one layer of quotes before the device sees the command. `adb shell setprop key 'two words'` therefore fails, because the device receives two separate words. Quote twice instead: `adb shell setprop key "'two words'"`. The same applies to an `--es` extra that contains a space. ## Common mistakes - Expecting `force-stop` to wipe data. It does not: run `pm clear`. - Upgrading with a plain uninstall and install, which destroys the state you were trying to reproduce. Use `install -r`. - Granting a permission the manifest never declares, then wondering why the grant did nothing.
- What is the difference between `am force-stop` and `am kill`?`am force-stop <package>` stops everything associated with the package. `am kill <package>` ends only the processes that are safe to kill without affecting the user experience. That is why it is used to simulate the system reclaiming a backgrounded app, while `force-stop` is a hard stop.
- The freeze happens in the first second of launch. How do you attach a debugger in time?Run `adb shell am set-debug-app -w com.example.shop` so the app waits for a debugger when it starts. Add `--persistent` to keep the setting across launches, and clear it afterwards with `am clear-debug-app`.
- Why does `adb shell setprop key 'two words'` fail when the same command works in an interactive shell?Since Platform Tools 23, adb handles arguments like `ssh`. Your local shell strips the quotes, so the device receives `setprop key two words`. Quote twice, `"'two words'"`, so one layer survives to the device.
- am force-stop also wipes the app's stored data
- pm clear only empties the cache directory
- adb install -r reinstalls from scratch and deletes user data
- pm grant can hand over a permission the manifest never declares
- am kill immediately kills whatever app is in the foreground