SuperAPI AI Directory

android-cli

Coding & development

View repository

Updated 10-16 18:29

About this skill

Automate this: /mobile-release:doctor reports whether this CLI and the rest of the Android toolchain are installed; /mobile-release:bootstrap uses android describe for artifact discovery. All of this skill is unattended-safe — it neither signs nor publishes.

Drive the android CLI to do Android work from the terminal. Prefer it over raw sdkmanager/avdmanager/adb — it is one binary, its output is machine-readable, and it blocks until operations actually finish. Never assume it is installed.

Confidence marks used throughout this skill: [verified] — read off a primary vendor source on 2026-08-05. [snippet] — secondary source only, plausible but unconfirmed. [unverified] — not confirmed anywhere; run the check given before relying on it. See Verification notes at the end for what was and was not confirmed.

Process:

  1. Check for the binary: command -v android. If missing, install it — see Install. If the user cannot install it, switch to Fallback: legacy tooling and use sdkmanager/avdmanager/adb for the rest of the session.
  2. Run android init once per environment, and android info to confirm the SDK location.
  3. Run android describe --project_dir=<path> before any build step. It emits the JSON that tells you where build targets and output artifacts (APK/AAB) actually land. Do not guess artifact paths.
  4. Install only the SDK packages the project needs with android sdk install.
  5. Boot a device with android emulator start <avd> — it returns when the device is ready.
  6. Deploy with android run --apks=<paths from step 3>.
  7. Inspect the running UI with android layout, not screenshots. Use android screen capture only when a human needs to see pixels.
  8. Resolve any Android API or behavior question with android docs search / android docs fetch instead of answering from memory.
  9. To sign, bundle, or upload — stop here and switch skills. See What this CLI cannot do.

Contents

  • What this CLI cannot do
  • Install
  • Global options
  • 1. android init — set up the environment
  • 2. android describe — JSON project and artifact discovery
  • 3. android sdk — SDK packages
  • 4. android emulator — devices
  • 5. android run — deploy to a device
  • 6. android screen — pixels
  • 7. android layout — JSON UI tree (prefer over screenshots)
  • 8. android docs — Android Knowledge Base
  • 9. android skills — agent skills
  • Other commands
  • Fallback: legacy tooling
  • Output Format
  • Verification notes

What this CLI cannot do

The android CLI has no signing commands and no Play Store publishing commands. Verified against the full android help output for 1.0. There is no keystore verb, no AAB signing verb, no Play Console upload verb, and no track-promotion verb. android run deploys to a local device or emulator only.

When the task crosses into that territory, hand off:

Task Skill
Release keystore, Gradle signing config, apksigner/zipalign/bundletool, producing a signed AAB android-build-sign
Google Play Developer Publishing API, upload, track promotion, staged rollout, release notes play-store-publish

Do not improvise a signing or upload step with android subcommands. They do not exist.


Install

Version 1.0 (19 May 2026) is the current stable release. 0.7 (April 2026) was the first release.

Linux

# local, no elevated permissions
curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash
# global
curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install_root.sh | bash

apt-get:

curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | sudo tee /etc/apt/keyrings/google.asc >/dev/null
sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google.asc] http://dl.google.com/android/cli/latest/debian/ stable main" > /etc/apt/sources.list.d/android-cli.list'
sudo apt-get update
sudo apt-get install android-cli

macOS

brew tap android/tap && brew install android-cli
# or, direct:
curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash    # Apple silicon
curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash   # Intel
# global variants: install_root.sh

Windows

winget install --id Google.AndroidCLI
:: or, direct:
curl.exe -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"
:: global: install_admin.cmd

Direct binaries: https://dl.google.com/android/cli/latest/<platform>/android (.exe on Windows), where <platform> is one of linux_x86_64, darwin_arm64, darwin_x86_64, windows_x86_64.

Keep it current with android update. Confirm with android --version.

Install failures are usually a blocked dl.google.com on a corporate proxy or CI egress allowlist. Check that host first before debugging anything else.


Global options

Usage: android [-hV] [--sdk=PARAM] [COMMAND]
  -h, --help        Show this help message and exit.
      --sdk=PARAM   Path to the Android SDK
  -V, --version     Print version information and exit.

Pass --sdk=<path> when the environment has more than one SDK, or when android info reports the wrong one. Do not export ANDROID_HOME as a workaround before trying --sdk.


1. android init — set up the environment

android init

Initializes the environment (for example, skills) for the Android CLI. Run it once per machine or container before other commands. Follow with:

android info                 # print environment information (SDK location, etc.)
android info <field>         # print one field

[unverified] — the exact set of <field> names accepted by android info. Run android info --help on the target machine rather than guessing a field name.


2. android describe — JSON project and artifact discovery

This is the entry point for any build pipeline. Run it before building, and again after building to locate outputs.

android describe --project_dir=.

It analyzes an Android project and outputs the paths to JSON files detailing the project's structure, including build targets and their corresponding output artifact locations (for example, APKs). Parse those JSON files to find the artifact — never hardcode app/build/outputs/apk/debug/app-debug.apk, and never find for *.apk and hope.

Use it to answer, in order: what modules exist → what build targets they expose → where each target's artifact is written. Feed the resulting paths straight into android run --apks= and into android-build-sign.

If describe fails, the project is usually not a valid Gradle Android project from the given directory. Re-run with --project_dir pointing at the directory containing the root settings.gradle[.kts].


3. android sdk — SDK packages

android sdk list --all
android sdk install platforms/android-34 build-tools/34.0.0
android sdk install platforms/android-30@2          # pin a version; default is latest
android sdk update [<pkg-name>]
android sdk remove <pkg-name>

Multiple packages are space-separated on one install. Install only what the project's compileSdk/targetSdk and AGP version require — a full SDK install is slow and large in CI.


4. android emulator — devices

android emulator list
android emulator create ...
android emulator start medium_phone
android emulator stop ...
android emulator remove ...

android emulator start returns only when the emulator is fully started and ready to use. Do not write a boot-completed polling loop around it; that is the whole point of the command. If you find yourself adding adb wait-for-device or a sleep, delete it.

[unverified] — the exact flag set for emulator create and emulator remove. Run android emulator create --help on the target machine before scripting it.


5. android run — deploy to a device

android run --apks=app/build/outputs/apk/debug/app-debug.apk
android run --apks=base.apk,density-hdpi.apk,lang-en.apk        # split APKs
android run [-h] [--debug] [--activity=PARAM] [--device=PARAM] [--type=PARAM] [--apks=PARAM[,PARAM...]]

Use --device when more than one device or emulator is attached. Use --activity to launch something other than the default launcher activity. Source the --apks values from android describe (step 2), not from a guessed path.


6. android screen — pixels

android screen capture --output=ui.png
android screen resolve --screenshot=ui.png --string="input tap #5"

capture outputs the device screen to a PNG. resolve targets UI elements visually against a captured screenshot.

Reach for this when a human needs to see the screen, when verifying rendering or theming, or when layout cannot express the problem. For everything else, use layout — it is cheaper and more precise.


7. android layout — JSON UI tree (prefer over screenshots)

android layout                 # full tree
android layout --diff          # only elements changed since the last invocation
android layout --pretty
android layout --device=<id> --output=tree.json
android layout [-dhp] [--device=PARAM] [-o=PARAM]

Google's own guidance: when debugging UI errors, this is often a much faster approach than taking a screenshot. Use it as the default UI inspection tool.

--diff is the right tool for verifying an interaction: capture, act, then --diff to see exactly what changed instead of comparing two images. Note that --diff is stateful — it diffs against the previous invocation, so run a plain android layout first to establish the baseline.


8. android docs — Android Knowledge Base

android docs search "<query>"
android docs fetch <kb-url>

Always use this to get up-to-date information about Android concepts. Prefer it over answering an API, AGP, or platform-behavior question from memory, and over a generic web search — it queries Google's first-party knowledge base. search to find the right page, fetch to read it.


9. android skills — agent skills

android skills list
android skills find <string>
android skills add --skill=r8-analyzer --project=.
android skills remove <name>

add also accepts --all, --agent, and --project. Google's official skill collection lives at github.com/android/skills and is installable as a Claude Code plugin in its own right. Suggest android skills add when a task matches a first-party skill (R8/shrinking analysis, AGP upgrades, Play policy insights, Compose migrations) rather than reimplementing it.


Other commands

Command Use
android create --name="My App" -o ./my-app [template] New project from a template. --name is required; --list lists templates; -o defaults to .
android studio <check|analyze-file|find-declaration|find-usages|open-file|render-compose-preview|version-lookup> Talks to a running Android Studio instance for semantic analysis and Compose preview rendering. 1.0+. Fails without Studio open
android update Update the CLI itself
android help Help for all commands — the authority when this skill and the installed version disagree

Journeys (natural-language user flows runnable from the terminal or CI) are documented by Google at developer.android.com/tools/agents/android-cli/journeys. [unverified] — there is no journey verb in the 1.0 android help output, so the invocation path is unconfirmed. Run android help and check the docs before scripting Journeys.


Fallback: legacy tooling

For environments without the android CLI. These are equivalents, not drop-in replacements — output is human-formatted, not JSON, and none of them block until ready.

android command Legacy equivalent
android sdk list --all sdkmanager --list
android sdk install <pkg> sdkmanager "platforms;android-34" "build-tools;34.0.0" (note ; separators, not /)
android sdk update sdkmanager --update
android sdk remove <pkg> sdkmanager --uninstall "<pkg>"
android emulator list avdmanager list avd / adb devices -l
android emulator create avdmanager create avd -n <name> -k "system-images;android-34;google_apis;x86_64"
android emulator start <avd> emulator -avd <name> & then adb wait-for-device shell 'while [ "$(getprop sys.boot_completed)" != 1 ]; do sleep 1; done' — the poll loop is required here
android emulator stop adb -s <serial> emu kill
android run --apks=a.apk adb install -r a.apk && adb shell am start -n <pkg>/<activity>
android run --apks=base.apk,split.apk adb install-multiple -r base.apk split.apk
android screen capture --output=ui.png adb exec-out screencap -p > ui.png
android layout adb shell uiautomator dump /sdcard/w.xml && adb pull /sdcard/w.xml — XML, no diff mode
android describe No equivalent. Use ./gradlew tasks --all plus ./gradlew :app:assembleDebug --console=plain and read the artifact path from app/build/outputs/, or parse output-metadata.json next to the artifact
android docs search|fetch No equivalent. Fall back to developer.android.com
android info echo $ANDROID_HOME, sdkmanager --version, adb version
android create Android Studio's new-project wizard, or a template repo

The describe row is the important one: without it, artifact discovery is manual and fragile. Parse output-metadata.json (written next to the APK/AAB by AGP) rather than globbing.


Output Format

Report what you ran and what it produced. Show the command, then the decision it drove — not the raw dump. Cite artifact paths exactly as describe reported them.

Example output:

Environment

$ command -v android
/usr/local/bin/android
$ android --version
1.0

SDK at /opt/android-sdk. platforms/android-34 and build-tools/34.0.0 already installed; nothing to add.

Artifact discovery

$ android describe --project_dir=.

Two build targets:

Module Target Artifact
:app debug app/build/outputs/apk/debug/app-debug.apk
:app release app/build/outputs/bundle/release/app-release.aab (unsigned)

Deploy and verify

$ android emulator start medium_phone     # returned after boot, ~40s
$ android run --apks=app/build/outputs/apk/debug/app-debug.apk
$ android layout --pretty > baseline.json

Baseline captured. After tapping Sign in:

$ android layout --diff

Changed: com.example.app:id/error_text became visible with text "Network unavailable" — the login button fires before the connectivity check, so the error renders on a cold start with no network.

Next step

The release AAB from describe is unsigned. Signing and Play upload are not android CLI capabilities — continue with android-build-sign, then play-store-publish.

End of example.


Verification notes

  • Command list, global options, per-command syntax, and the absence of signing/publishing verbs: verified against Google's first-party android-cli skill (github.com/android/skills, devtools/android-cli/SKILL.md), which embeds the full android help output for 1.0.
  • Install commands and release dates: verified against developer.android.com/tools/agents/android-cli/download and /release-notes, as of 2026-08-05.
  • Items marked [unverified] above were not first-party confirmed. Run android help or <command> --help on the target machine before relying on them.
  • The claim that the CLI consolidates sdkmanager + avdmanager + adb comes from secondary coverage, not first-party docs. The fallback table is written from the legacy tools' own documented behavior, not from a claimed 1:1 mapping.
  • When this skill and android help disagree, android help wins. Report the discrepancy so the skill can be updated.