android-deploy

android-deploy

Standard build → deploy loop for an Android app, using android describe to discover APK paths reliably and android run to install/launch (handles split APKs and multi-device better than raw adb install).

Configuration

{
  "androidCli": {
    "defaultDevice": "emulator-5554",
    "defaultBuildVariant": "debug"
  }
}

Field	Purpose
androidCli.defaultDevice	Target serial when multiple devices are connected. Override per call with --device.
androidCli.defaultBuildVariant	debug or release. Drives Gradle task selection (assembleDebug vs assembleRelease).

If neither is set and ambiguity exists at runtime, ask once and save the answer.

Workflow

gradle assemble<Variant> → android describe → android run [--device=…] [--type=…] [--debug]
                                  ↓
                           verify launch via logcat

Step-by-step

1. Pre-flight: device available?

   adb devices
   

   • 0 devices → stop and route the user to android-emulator (this skill does not start emulators).
   • 1 device → use it implicitly.
   • 2+ devices → resolve target via androidCli.defaultDevice or prompt.

2. Build. Don't use android for this — it has no build subcommand.

   ./gradlew assembleDebug    # or assembleRelease per config
   

   For multi-module projects target a specific module: ./gradlew :app:assembleDebug.

3. Discover APK paths. Use android describe instead of guessing under app/build/outputs/apk/...:

   android describe --project_dir=.
   

   The output points at JSON files describing build targets and their output artifacts. Read those JSONs to get exact APK paths. This is more robust than hard-coded paths because module names and variants vary.

4. Deploy.

   android run --apks=<comma-separated-apks>
   

   • Single APK → just one path.
   • Split APKs (per-density, per-language, per-ABI) → pass all of them comma-separated:

     android run --apks=base.apk,density-hdpi.apk,lang-en.apk
     

   • Multiple devices connected → add --device=<serial>.
   • Specific activity → --activity=.feature.MainActivity (needed when the manifest declares multiple launcher activities).
   • Background service / watch face / tile / complication → --type=SERVICE --activity=.sync.DataSyncService (or other supported types).
   • Debug session → --debug, then attach the debugger from Android Studio / IDE.

5. Verify. Tail logcat for the package and confirm no immediate crash:

   adb -s <serial> logcat -T 100 --pid=$(adb -s <serial> shell pidof <pkg>)
   

Decision matrix — android run vs alternatives

Situation	Use	Don't use	Why
Standard debug install on connected device	android run	adb install	Simpler args, handles splits
Split APKs (App Bundle outputs)	android run --apks=a,b,c	adb install-multiple	Less error-prone, no order issues
Background service test	android run --type=SERVICE	am start-service	Auto-installs the APK first
Already installed, just relaunch	adb shell am start -n …	android run	Avoids reinstall
Deploy via Gradle plugin (installDebug)	./gradlew installDebug	both	Useful in CI; redundant locally if also using android run

Operating rules

1. Don't double-install. If the user already ran ./gradlew installDebug, skip android run (or vice versa).
2. Always check adb devices first. Never assume there's exactly one device.
3. Never hard-code APK paths. Use android describe output or the gradle task's reported output.
4. Prefer debug variant by default. Release builds need signing config and shouldn't be sideloaded for normal development.
5. --debug is for IDE debugger attach, not for "build a debug APK". Don't conflate with --variant=debug.
6. Never use --type without --activity. Pair them; --type alone has no target.
7. No mock APKs. If assemble* failed, surface the gradle error; don't fabricate a path or proceed.

Anti-patterns

• ❌ adb install app-debug.apk for a project that emits split APKs (will install only base, app crashes at runtime with missing resources).
• ❌ Hardcoding app/build/outputs/apk/debug/app-debug.apk instead of using android describe.
• ❌ Running ./gradlew installDebug && android run … (duplicate install).
• ❌ Forgetting --device= when multiple emulators / devices are connected — android run errors out, not silently picks one.
• ❌ Calling this skill when no device is attached. Route to android-emulator first.
• ❌ Deploying release builds without signing config — the install will fail mysteriously.

Error recovery

Error	Cause	Fix
INSTALL_FAILED_VERSION_DOWNGRADE	Existing app has higher versionCode	adb -s <serial> uninstall <pkg> then retry
INSTALL_FAILED_UPDATE_INCOMPATIBLE	Signature mismatch (debug vs release, or different keystore)	adb uninstall <pkg> then retry
Failure [INSTALL_FAILED_INSUFFICIENT_STORAGE]	Emulator out of space	Stop emulator, recreate with bigger disk, or adb shell pm clear <pkg>
more than one device/emulator	Forgot --device	Run adb devices, pick serial, retry with --device=<serial>
error: device unauthorized	USB debugging not approved on physical device	Approve the dialog on device, retry
Gradle: Unable to find APK	assemble* was skipped (cache up-to-date) but artifacts pruned	./gradlew clean assembleDebug