/native

adb — Android Debug Bridge Reference

Production-grade reference for adb (Android Debug Bridge) covering the subcommands a native Android developer or CI script actually uses. Focus: app management, device control, logging, state simulation, and performance tracing.

Scope: Android development from terminal or CI — installs, instrumentation runs, debugging, demo recording, Doze / network state simulation, Perfetto tracing. Use this alongside reference/xcrun-cli.md for iOS / Android symmetric tooling.

0. Base Mechanics

adb version                    # Server / client version
adb start-server / kill-server # Restart adb daemon
adb devices -l                 # Connected devices + product / model / transport_id
adb -s <serial> <cmd>          # Target specific device
adb -d <cmd>                   # Prefer USB device
adb -e <cmd>                   # Prefer emulator

Active config knobs:

• ANDROID_HOME / ANDROID_SDK_ROOT — SDK location
• ADB_VENDOR_KEYS — additional RSA keys for unattended auth
• ANDROID_SERIAL — implicit -s target

1. App Management

2. Activity Manager (launching, killing, intents)

3. Logging & Diagnostics

4. File Transfer

5. Network & Wi-Fi ADB (Android 11+ requires pair)

# USB → Wi-Fi switchover (legacy, still works for rooted / debug devices)
adb tcpip 5555
adb connect 192.168.1.10:5555

# Android 11+ Wireless Debugging (developer options must enable "Wireless debugging")
# Tap "Pair device with pairing code" on device → shows IP:port and 6-digit code
adb pair 192.168.1.10:37123          # Then enter pairing code at prompt
adb connect 192.168.1.10:43215       # IP:port shown under "IP address & Port"

# Port forwarding
adb forward tcp:8080 tcp:8080        # PC localhost:8080 → device localhost:8080
adb reverse tcp:3000 tcp:3000        # device localhost:3000 → PC localhost:3000 (REQUIRED for Metro / Vite dev server)
adb forward --list                    # Current forwards
adb forward --remove tcp:8080         # Remove single
adb forward --remove-all              # Reset

6. Screen & Input

→ Pairs well with cue skill for automated demo recording.

7. Device State Simulation (test edge cases)

8. Properties & Settings (low-level config)

9. Perfetto Tracing (system-wide profiling)

# Trigger Perfetto trace with inline config (5-second sched trace)
adb shell perfetto -c - --txt -o /data/misc/perfetto-traces/trace.pftrace <<EOF
buffers { size_kb: 65536 }
data_sources {
  config {
    name: "linux.ftrace"
    ftrace_config { ftrace_events: "sched/sched_switch" }
  }
}
duration_ms: 5000
EOF
adb pull /data/misc/perfetto-traces/trace.pftrace
# Open at https://ui.perfetto.dev

For app-specific frame / startup tracing, use Macrobenchmark library + androidx.tracing annotations; results land in bugreport Perfetto trace.

10. Stress / Fuzz Testing

11. Crash Symbolication

# Native (NDK)
adb logcat | ndk-stack -sym ./obj/local/arm64-v8a

# Kotlin / Java with R8
# Use proguard mapping file (build/outputs/mapping/release/mapping.txt) with:
java -jar retrace.jar mapping.txt obfuscated-stacktrace.txt > readable.txt

12. Practical One-Liners

# Currently focused package
adb shell dumpsys window | awk '/mCurrentFocus/{print $NF}' | sed 's/}//'

# All installed third-party apps with version
for pkg in $(adb shell pm list packages -3 | sed 's/package://'); do
  v=$(adb shell dumpsys package "$pkg" | awk '/versionName=/{print $1; exit}')
  echo "$pkg $v"
done

# CPU/MEM top 5, refresh every 1s
adb shell top -d 1 -m 5 -s cpu

# Cold-start time (am start prints TotalTime)
adb shell am force-stop com.example.app
adb shell am start -W -n com.example/.MainActivity | grep -E "TotalTime|WaitTime"

# Auto-grant all runtime permissions on install
adb install -g app.apk

# Tail logs for one app and color CRITICAL keywords
adb logcat --pid=$(adb shell pidof com.example.app) -v color

13. Gotchas

1. pidof requires Android 7+ — pre-N use ps | grep com.example.app | awk '{print $2}'.
2. adb shell screencap raw mode — without -p, output is raw RGBA pixels; always pass -p for PNG.
3. screenrecord limits — 3-min cap, no audio, no 4K, MP4 container only. For longer or audio-included recordings use scrcpy --record file.mp4 on the host.
4. am force-stop vs kill — force-stop clears alarms, jobs, and cached processes; kill only kills background. Use force-stop for clean test isolation.
5. Wireless ADB pairing token expires — Android 11+ pairing codes are single-use and time-bound; re-pair if adb connect fails after a long idle.
6. dumpsys battery set ... requires unplug first on Android 14+ — the simulated values are ignored while a real charger is connected; call adb shell dumpsys battery unplug first.
7. dumpsys deviceidle force-idle only works while unplugged — combine with battery unplug to test Doze paths.
8. run-as requires debuggable app — release / store builds reject run-as; for prod-build debugging take a bugreport instead.
9. hidden_api_policy reset — always settings delete global hidden_api_policy after debugging; leaving relaxed policy on a device skews compliance test results.
10. adb forward does NOT survive adb kill-server — restart breaks all forwards silently; CI scripts should re-establish forwards after any server restart.

Cross-References

• reference/mobile-ci-cd.md — Gradle / fastlane / GitHub Actions integration with adb install and connectedAndroidTest
• reference/bg-execution.md — Doze / WorkManager scenarios that dumpsys deviceidle exercises
• reference/release-rollout.md — Play staged rollout that consumes bundletool + signed AAB
• reference/xcrun-cli.md — iOS counterpart

iOS ↔ Android command map (cross-platform quick reference)