run-app

name	run-app
description	Use to build, install, and launch ApkAnalyzer on a connected device or emulator, or to verify a code change actually works at runtime rather than just compiling. Triggered by phrases like "run the app", "install on device", "launch the app", "try it on my phone", "deploy to device", "see if this works", "run it".

Skill: Build, Install, and Run ApkAnalyzer on a Device

Debug builds and any release build the user already has installed share the same applicationId (sk.styk.martin.apkanalyzer — no debug suffix), so installing over an existing release can hit a version conflict. Read Step 3 before installing, especially the first time on a given device.

Step 1 — Find adb

adb is often not on PATH. Try it directly first; if that fails, it lives under the Android SDK:

adb devices -l || "$ANDROID_HOME/platform-tools/adb" devices -l   # macOS/Linux

adb devices -l 2>$null; if (-not $?) { & "$env:ANDROID_HOME\platform-tools\adb.exe" devices -l }

If ANDROID_HOME isn't set either, see the setup-local-tools skill. Confirm at least one device/emulator is listed as device (not unauthorized or offline) before continuing. If multiple devices are attached, target one explicitly with -s <serial> on every adb command below.

Step 2 — Build and install

./gradlew installDebug

This assembles :app:debug and installs it via the AGP-managed install task. If it succeeds, skip to Step 4.

Step 3 — If install fails with INSTALL_FAILED_VERSION_DOWNGRADE

This happens when the device already has a build with a higher versionCode than the debug build's versionCode = 1 (see app/build.gradle.kts) — typically a release build (from the Play Store, a manual release, or a prior CI artifact) already on the device.

1. Check whether -d (allow downgrade) is enough — it only works if the existing install is itself debuggable, so this recovers cleanly with no data loss when the device already has a debug build:

   adb install -r -d app/build/outputs/apk/debug/app-debug.apk
   

2. If that still fails (the existing install is a non-debuggable release build), the only way to get the debug build on is to uninstall first — and this wipes the app's local data (DataStore prefs: recently-viewed apps, search history, color scheme). Ask the user before doing this — it's exactly the kind of hard-to-reverse action that needs confirmation, not an assumption:

   adb uninstall sk.styk.martin.apkanalyzer
   ./gradlew installDebug
   

Step 4 — Launch and verify it's actually running

Installing is not running. Launch the main activity and confirm the process is alive with no immediate crash:

adb shell am start -n sk.styk.martin.apkanalyzer/.ui.ApkAnalyzerActivity
sleep 2
adb shell pidof sk.styk.martin.apkanalyzer   # a PID means it's running; empty means it crashed on launch

If pidof comes back empty, pull the crash from logcat rather than guessing:

adb logcat -d -t 200 | grep -A 30 "FATAL EXCEPTION"

Verification

• adb devices -l showed a device (not unauthorized/offline) before installing
• Install succeeded — either directly, or via the -r -d / uninstall path in Step 3, with explicit user confirmation before any uninstall
• App launched via am start and pidof returned a PID (not empty)
• For a specific feature/screen change: actually navigated to it in the running app, not just confirmed the process didn't crash on the launch screen — see the navigate-app-adb skill to do this via adb instead of a human tapping through the device