Viewing: developer.android.com

Android CLI is a command-line interface that enables you to more easily and efficiently build for Android using any tool of your choice. It standardizes core development competencies for agent-first workflows, providing an entry point to the official tools, skills, and knowledge you need to develop more effectively. It can also streamline CI, maintenance, and any other scripted automation for the increasingly distributed nature of Android development.

For example, an agent or script can use the CLI to do tasks such as the following:

Automate environment setup
Scaffold new projects from templates
Manage virtual devices directly from your terminal
Test your app with Journeys

Android CLI also gives your agents access to Android skills and the specialized Android Knowledge Base to help ensure that your projects apply Android-recommended patterns and best practices.

Install Android CLI

To install Android CLI, follow these steps:

Download Android CLI.
To make sure you're using the latest version, update Android CLI:
```
android update
```
Tip: Run android update regularly to keep up with the latest features.

To check if Android CLI is already installed on your machine, run which android or command -v android: if it returns a path, then it's installed.

Set up for agents

To help agents understand and use Android CLI, run init to install the android-cli skill:

android init

Data collected

Android CLI collects data on basic usage of the tool. Here's the data that we collect:

Invocations of the android command and sub-commands, for example android run and android create.
Names of non-positional arguments or options used, for example --sdk or --version.
Positional arguments and flag values that map to a fixed, predefined set of system options managed by Android CLI. For example, we collect emulator template names such as medium_phone and large_desktop, and agent names such as GEMINI, CLAUDE, or CODEX.
Stack traces and exception messages, where identifying information is anonymized before collection to help ensure privacy.

Here are some examples of data that we don't collect:

We don't collect responses of the CLI when a command is run.
We don't collect user-created inputs or external identifiers passed to the CLI, such as specific Maven coordinates, local file paths, or custom project names. For example, if the command android create --name=com.company.internal.app is executed, we record that android create was executed using the --name argument but we don't store the value com.company.internal.app.

Feedback and issues

If you encounter any issues or want to provide feedback, report a bug.

Known issues

The android emulator command for Windows is currently disabled.
Downloading Android CLI from Windows PowerShell isn't currently supported.

Configure Android CLI

Create a .androidrc file to automatically apply flags and options every time you invoke Android CLI. Save the file in the following location, depending on your operating system:

macOS and Linux: ~/.androidrc
Windows: %USERPROFILE%\.androidrc

Add the flags you want to apply automatically to the file, one per line.

For example, to make Android CLI use a specific Android SDK by default every time, add the --sdk flag to your file:

--sdk=<path-to-sdk>

Global options

These are optional flags that you can use with other Android CLI commands.

`-h, --help`

Usage: android <command> -h

Description: Display the help manual for the tool or specific command in question.

Examples:

android -h
android create -h

`--sdk`

Usage: android --sdk=<path-to-sdk> <command>

Description: The path to the Android SDK that you want to use for the command that follows. You can use the --sdk setting to temporarily override the default Android SDK instead of changing your global environment variables every time you want to switch. To check which Android SDK you're using by default, run android info.

Example: android --sdk=<path/to/sdk> sdk list

Commands

This section lists all the Android CLI commands and describes what they do. All of these commands should be preceded by android, for example android create, android run, and so on. Optional modifiers are enclosed in brackets [] and mandatory arguments are not.

`create`

Usage: android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]

Description: Initialize a new project from a template. To see the template options, run android create -h.

Arguments (mandatory):

-o, --output - The destination project directory path.

Options:

--dry-run - Simulates the entire project creation process without actually saving any files. For example, you can do a dry run to see what the different templates do before committing to one.
--verbose - Enables verbose output, including information such as which files are being copied from the template.
--name=<application-name> - The name of the project directory. If omitted, the output directory is used.
<template-name> - The name of the template to create a new project from. If omitted, empty-activity-agp-9 is used.

Example: android create --dry-run --verbose empty-activity-agp-9

`create list`

Usage: android create list

Description: List all the available templates to create a new project from.

`describe`

Usage: android describe [--project_dir=<project-directory>]

Description: Analyzes an Android project to generate descriptive metadata. This command identifies and outputs the paths to JSON files that detail the project's structure, including build targets and their corresponding output artifact locations (for example, APK files). This information enables other tools and commands to locate build artifacts efficiently.

Options:

--project_dir - The project directory to describe. If omitted, the current directory is used.

Example: android describe --project_dir=/path/to/your/project

`docs`

Usage:

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

Description: The android docs command is a two-step process for accessing the Android Knowledge Base directly from the CLI. First, search for documentation related to your query using the search command. The search results will include special URLs starting with kb://, which you can then use with the fetch command to output the documentation commands to the terminal.

Examples:

android docs search 'How do I improve my app performance?'
android docs fetch kb://android/topic/performance/overview

`emulator create`

Usage: android emulator create [--list-profiles] [--profile=<profile-name>]

Description: Create a virtual device.

Options:

--list-profiles - List the device profiles that can be used to create a device.
--profile=<profile-name> - Create a device with the specified profile. If this is omitted, the medium_phone profile will be created.

`emulator list`

Usage: android emulator list

Description: List the available virtual devices.

`emulator start`

Usage: android emulator start <device-name>

Description: Launch the specified virtual device.

Arguments (mandatory):

<device-name> - The device name to start (for example, medium_phone). Use android emulator list to see the available devices.

Example: android emulator start medium_phone

`emulator stop`

Usage: android emulator stop <device-serial-number>

Description: Stop the specified virtual device.

Arguments (mandatory):

<device-serial-number> - The device serial number to stop.

Example: android emulator stop emulator-5554

`info`

Usage: android info

Description: Display the path to the default Android SDK used. To change the Android SDK used, use --sdk.

`init`

Usage: android init

Description: Set up your environment for agents by installing the android-cli skill.

`layout`

Usage: android layout [--pretty] [--output] [--diff]

Description: Returns the UI layout of the active Android app (connected through a physical device or emulator) in JSON format.

Options:

-p, --pretty - Formats the JSON output with indentation and line breaks for human readability.
-o, --output - Specifies a file location to save the layout tree. If omitted, the JSON is printed directly to stdout.
-d, --diff - Returns a list of only the layout elements that have changed since the last internal snapshot was taken (the last time layout was run), instead of the full layout tree.

Example:: android layout --output=./hierarchy.json

`run`

Usage: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

Description: Deploy an Android app to a connected device or emulator. It doesn't perform any build steps; you must provide the path(s) to the APK files that you want to install.

Arguments (mandatory):

--apks - A comma-separated list of path(s) to the APK files that you want to install. The path is relative to where you currently are in the file system.

Options:

--activity - The name of the activity to launch once the APK is installed. If there are multiple activities, you must specify one activity to launch initially.
--debug - Deploys the app in debug mode. After running the app in debug mode, you must connect your debugger from an IDE, such as Android Studio, or a command-line tool to start debugging.
--device - The serial number of the target device or emulator. Only needed if multiple devices are connected. To find the device serial numbers, run adb devices.
--type - The component type to start. Use this if you'd like to start a background service directly instead of a UI activity. Types supported:
- ACTIVITY
- WATCH_FACE
- TILE
- COMPLICATION
- DECLARATIVE_WATCH_FACE

Examples:

android run --apks=app/build/outputs/apk/debug/app-debug.apk - Deploys a single APK to the default device.
android run --apks=base.apk,density-hdpi.apk,lang-en.apk - Deploys multiple APKs to the default device.
android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService - Test a service without an activity.
android run --apks=app-debug.apk --device=emulator-5554 - Deploys the APK to a specific device.

`screen capture`

Usage: android screen capture [--output] [--annotate]

Description: Captures a screenshot of the connected device.

Options:

-o, --output - Specifies a file location to save the screenshot. If omitted, the raw PNG data will be printed directly to stdout.
-a, --annotate - Draws labeled bounding boxes around all the UI elements detected on the image, to use with the resolve command.

Example: android screen capture --output=ui.png

`screen resolve`

Usage: android screen resolve --screenshot=<path> --string=<string>

Description: Translates the visual labels from an annotated screenshot, captured using screen capture, into actual screen coordinates (x, y). Useful for scripting clicks on elements without having to manually calculate their positions.

Flags:

--screenshot - The path to the annotated screenshot.
--string - A string that includes at least one placeholder corresponding to a UI element label in the format #<number>. The #<number> part will be replaced by the screen coordinates.

Example:

If the label 5 is at coordinates (500, 1000), then the command

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

returns the output

input tap 500 1000

`sdk install`

Usage: android sdk install <package[@version]> [--beta] [--canary] [--force]

Description: Install the specified SDK package(s).

Arguments (mandatory):

package[@version] - A space-separated list of packages to install. If a version isn't specified, the latest version of the package in the channel (by default the stable channel) is installed.

Options:

--beta - Include beta packages.
--canary - Include canary packages.
--force - Force downgrading to an older version.

Examples:

android sdk install platforms/android-34 build-tools/34.0.0 - Install the latest versions of the Android SDK Platform 34 and SDK Built Tools 34.0.0 packages from the stable channel.
android sdk install platforms/android-34@2 - Install version 2 of the Android SDK Platform 34 package.
android sdk install --canary system-images/android-35/google_apis/x86_6 - Install the latest version of the Android 35 system image from the canary channel.
android sdk install --force platforms/android-33@1 - Revert to version 1 of the Android SDK Platform 33 package from the stable channel.

`sdk list`

Usage: android sdk list <package-pattern>

Description: List the installed and available SDK packages.

Arguments (mandatory):

<package-pattern> - Filter packages by pattern. Supports regular expressions.

Options:

--all - Show all installed and available packages.
--all-versions - Show all versions for each package.
--beta - Include beta packages.
--canary - Include canary packages.

`sdk remove`

Usage: android sdk remove <package-name>

Description: Remove a package from the SDK.

Arguments (mandatory):

<package-name> - The name of the package to remove.

Example: android sdk remove build-tools/36.1.0

`sdk update`

Usage: android sdk update [--beta] [--canary] [<package-name>]

Description: Update one or all packages to the latest version in the channel (by default the stable channel). If you don't specify a package, all packages will be updated.

Options:

<package-name> - The name of the package to update.
--beta - Include beta packages.
--canary - Include canary packages.
--force - Force downgrading to an older version.

Examples:

android sdk update - Check for and install updates for everything in your SDK.
android sdk update build-tools/34.0.0 - Update the Android SDK Build Tools 34.0.0 package to the latest version in the stable channel.
android sdk update --canary platforms/android-35 - Update the Android SDK Platforms 35 package to the latest version in the canary channel.

`skills add`

Android skills are special instructions designed to help agents better understand and execute specific patterns that follow best practices and guidance on Android development. To learn more, see Intro to Android skills.

Usage: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

Description: Install Android skills to the skills directories for all detected agents. If you don't have any existing agent directories and don't specify particular agents, the skills will be installed for Gemini and Antigravity at ~/.gemini/antigravity/skills. If you already have Android skills installed, skills add updates the skills to the latest version.

Note: If you customize a skill, you should rename it, or it will get overwritten when you update it using skills add.

Options:

--all - Install or update all the Android skills at once. If omitted (and --skill isn't specified), only the android-cli skill will be installed.
--agent - A comma-separated list of agents to install or update the skill for. If omitted, the skill will be installed for all detected agents.
--skill - The skill name that you want to install or update. If omitted (and --all isn't specified), only the android-cli skill will be installed or updated.

Example: android skills add --agent='gemini' edge-to-edge

`skills find`

Usage: android skills find <string>

Description: Find skills that match a given string.

Arguments (mandatory):

string - String that matches a skill description.

Example: android skills find 'performance'

`skills list`

Usage: android skills list [--long]

Description: List the available skills.

Options:

--long - Output additional information for each skill, including the description of the skill and which agents it's already installed for.

`skills remove`

Usage: android skills remove [--agent] --skill=<skill-name>

Description: Remove a skill. If you don't specify particular agents, the skill will be removed for all agents.

Arguments (mandatory):

--skill - The name of the skill to remove.

Options:

--agent - A comma-separated list of agents to remove the skill from. If omitted, the skill will be removed for all agents.

Example: android skills remove --agent='gemini' --skill=edge-to-edge

`studio check`

Preview: To use the studio commands, you must have your project open in Android Studio Quail 2 Canary 1 or higher, and have Gemini in Android Studio enabled and signed in.

The studio commands enable you or your AI agent to interact with active instances of Android Studio. By connecting to a running instance, you can use the IDE's capabilities to analyze files, find symbol declarations and usages, render Compose previews, and look up dependency versions.

Usage: android studio check

Description: Checks the status of running Android Studio instances and lists open projects. Run this command first to verify the connection between the CLI and the IDE, and to select the PID and project you want to connect to, if there are multiple.

Output example:

If connected, the output lists the PID of the running Android Studio instance, the version, and the status of open projects:

pid: 32942
version: Android Studio Quail
Projects:
    READY     MyApplication /Users/username/AndroidStudioProjects/MyApplication

`studio analyze-file`

Usage: android studio analyze-file [--pid=<pid>] [--project=<project>] <path>

Description: Analyzes a file in Android Studio for errors, warnings, and lints using the IDE's built-in inspection engine.

Arguments (mandatory):

<path> - The path of the Kotlin or Java file to analyze.

Options:

--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run the analyze-file command from within a project directory, that project is used by default.

Example:

android studio analyze-file \
  --project=MyApplication \
  /Users/username/AndroidStudioProjects/MyApplication/app/src/main/java/com/example/myapp/MainActivity.kt

`studio find-declaration`

Usage: android studio find-declaration [--short] [--context-file=<path>] [--pid=<pid>] [--project=<project>] <symbol>

Description: Finds the exact declaration site of a symbol (class, method, variable, field, constant, or Android resource) across the project using semantic resolution.

Arguments (mandatory):

<symbol> - The name of the code symbol to find the declaration for.

Options:

--context-file=<path> - Optional path to a file containing a reference to the symbol. Providing a context file helps resolve ambiguous or overloaded symbols by providing imports and scope.
--short - Simplifies the output to only display the file location and line match.
--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run the find-declaration command from within a project directory, that project is used by default.

Example:

android studio find-declaration --short HotelDetailScreen

`studio find-usages`

Usage: android studio find-usages [--short] [--pid=<pid>] [--project=<project>] <symbol>

Description: Finds all references and usages of a symbol across the entire project using semantic analysis.

Arguments (mandatory):

<symbol> - The name of the symbol to find usages for.

Options:

--short - Simplifies the output to only display the matched file locations.
--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run this command from within a project directory, that project is used by default.

Example:

android studio find-usages --short HotelDetailScreen

`studio open-file`

Usage: android studio open-file [--pid=<pid>] [--project=<project>] <path>

Description: Opens a file directly in the active editor window of Android Studio.

Arguments (mandatory):

<path> - The path of the file to open. Can be specified relative to the project root directory, or as an absolute path.

Options:

--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run the open-file command from within a project directory, that project is used by default.

Example:

android studio open-file app/src/main/java/com/example/myapp/ui/DetailScreen.kt

`studio render-compose-preview`

Usage: android studio render-compose-preview [--print-semantics] [--output-image-file=<filename>] [--pid=<pid>] [--project=<project>] <path> <composable>

Description: Renders a Jetpack Compose UI Preview and optionally returns its layout semantics tree. This is useful for visual testing or for enabling AI agents to work with the UI layout.

Arguments (mandatory):

<path> - The path to the Kotlin file containing the Compose preview.
<composable> - The name of the composable preview function (marked with @Preview).

Options:

--output-image-file=<filename> - Specifies the filename to write the resulting rendered PNG image to. If omitted, a temporary file is created.
--print-semantics - If true, prints out the rendered Compose preview's accessibility semantics tree in JSON format. This enables agents to parse the structure and interactive elements of the UI.
--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run the render-compose-preview command from within a project directory, that project is used by default.

Example:

android studio render-compose-preview \
  --output-image-file=preview_hotel.png \
  --print-semantics \
  app/src/main/java/com/example/myapp/ui/DetailScreen.kt \
  HotelDetailScreenPreview

`studio version-lookup`

Usage: android studio version-lookup [--pid=<pid>] [--project=<project>] <artifacts...>

Description: Looks up the latest available versions of common dependencies, Android platforms, and SDK tools in repositories such as Google Maven. This provides a programmatic alternative to manual dependency version checking.

Arguments (mandatory):

<artifacts...> - A space-separated list of identifiers. You can query multiple artifacts in a single command. Supported identifiers include:
- Maven libraries: The groupId:artifactId notation (for example, androidx.window:window).
- Gradle plugins: The plugin ID (for example, com.android.application).
- Keywords:
  - gradle (Gradle build tool)
  - studio (Android Studio)
  - agp (Android Gradle plugin)
  - ndk (Android NDK)
  - sdk (Android SDK)
  - emulator (Android emulator)
  - adb (Android Debug Bridge)
  - compose (Jetpack Compose BOM)
  - kotlin (Kotlin runtime and compiler)
  - android (Android OS versions)
  - platform-tools (Android SDK Platform-Tools)
  - cmdline-tools (Android SDK Command-line Tools)
  - build-tools (Android SDK Build-Tools)

Options:

--pid=<pid> - The PID of the specific Android Studio instance to connect to, if there are multiple.
--project=<project> - The name of the project open in Android Studio to query, if there are multiple. If you run the version-lookup command from within a project directory, that project is used by default.

Example:

android studio version-lookup \
  androidx.compose.ui:ui \
  com.android.application \
  agp \
  kotlin

`update`

Usage: android update

Description: Update the Android CLI.

`-V, --version`

Description: Show the current version of the Android CLI.

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Overview of Android CLI Stay organized with collections Save and categorize content based on your preferences.

Install Android CLI

Set up for agents

Data collected

Feedback and issues

Known issues

Configure Android CLI

Global options

-h, --help

--sdk

Commands

create

create list

describe

docs

emulator create

emulator list

emulator start

emulator stop

info

init

layout

run

screen capture

screen resolve

sdk install

sdk list

sdk remove

sdk update

skills add

skills find

skills list

skills remove

studio check

studio analyze-file

studio find-declaration

studio find-usages

studio open-file

studio render-compose-preview

studio version-lookup

update

-V, --version

More Android

Discover

Android Devices

Releases

Documentation and Downloads

Support

`-h, --help`

`--sdk`

`create`

`create list`

`describe`

`docs`

`emulator create`

`emulator list`

`emulator start`

`emulator stop`

`info`

`init`

`layout`

`run`

`screen capture`

`screen resolve`

`sdk install`

`sdk list`

`sdk remove`

`sdk update`

`skills add`

`skills find`

`skills list`

`skills remove`

`studio check`

`studio analyze-file`

`studio find-declaration`

`studio find-usages`

`studio open-file`

`studio render-compose-preview`

`studio version-lookup`

`update`

`-V, --version`