Android CLI 概览

Android CLI 是一种命令行界面，可让您使用任意选择的工具更轻松高效地为 Android 构建应用。它可标准化以智能体为先的工作流的核心开发能力，并提供官方工具、技能和知识的入口点，让您能够更高效地进行开发。它还可以简化持续集成、维护和任何其他脚本化自动化流程，以适应 Android 开发日益分布式的特性。

例如，代理或脚本可以使用 CLI 自动执行环境设置、从模板搭建新项目，以及直接从终端管理虚拟设备。它还可让您的代理访问 Android 技能和专门的 Android 知识库，以帮助确保您的项目应用 Android 推荐的模式和最佳实践。

安装 Android CLI

如需安装 Android CLI，请按以下步骤操作：

  1. 下载 Android CLI。

  2. 为确保您使用的是最新版本，请更新 Android CLI：

    android update

如需检查 Android CLI 是否已安装在您的计算机上，请运行 which android 或 command -v android：如果返回路径，则表示已安装。

为代理设置

为了帮助代理了解和使用 Android CLI，请运行 init 以安装 android-cli 技能：

android init

已知问题

  • 适用于 Windows 的 android emulator 命令目前已停用。

全局选项

这些是可选标志，可与其他 Android CLI 命令搭配使用。

-h, --help

用法： android <command> -h

说明：显示相应工具或特定命令的帮助手册。

示例：

  • android -h
  • android create -h

--sdk

用法： android --sdk=<path-to-sdk> <command>

说明：您要用于后续命令的 Android SDK 的路径。您可以使用 --sdk 设置来暂时替换默认 Android SDK，而不必每次想切换时都更改全局环境变量。如需查看您默认使用的 Android SDK，请运行 android info。

示例：android --sdk=<path/to/sdk> sdk list

命令

本部分列出了所有 Android CLI 命令，并介绍了它们的作用。所有这些命令都应以 android 开头，例如 android create、android run 等。可选修饰符用方括号 [] 括起来，而必需实参则不用。

create

用法： android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]

说明：从模板初始化新项目。如需查看模板选项，请运行 android create -h。

实参（必需）：

  • -o, --output - 目标项目目录路径。

选项：

  • --dry-run - 模拟整个项目创建过程，但不实际保存任何文件。例如，您可以先进行试运行，了解不同模板的功能，然后再选择其中一个。
  • --verbose - 启用详细输出，包括正在从模板复制哪些文件等信息。
  • --name=<application-name> - 项目目录的名称。如果省略，则使用输出目录。
  • <template-name> - 要创建新项目的模板的名称。 如果省略，则使用 empty-activity-agp-9。

示例：android create --dry-run --verbose empty-activity-agp-9

create list

用法： android create list

说明：列出所有可用于创建新项目的可用模板。

describe

用法： android describe [--project_dir=<project-directory>]

说明：分析 Android 项目以生成描述性元数据。 此命令可识别并输出 JSON 文件的路径，这些文件详细说明了项目的结构，包括 build 目标及其对应的输出工件位置（例如 APK 文件）。此信息可让其他工具和命令高效地找到 build 工件。

选项：

  • --project_dir - 要描述的项目目录。如果省略，则使用当前目录。

示例：android describe --project_dir=/path/to/your/project

docs

用法：

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

说明：android docs 命令是一个两步流程，用于直接从 CLI 访问 Android 知识库。首先，使用 search 命令搜索与您的查询相关的文档。搜索结果将包含以 kb:// 开头的特殊网址，然后您可以将这些网址与 fetch 命令搭配使用，以将文档命令输出到终端。

示例：

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

emulator create

用法： android emulator create [--list-profiles] [--profile=<profile-name>]

说明：创建虚拟设备。

选项：

  • --list-profiles - 列出可用于创建设备的设备配置文件。
  • --profile=<profile-name> - 创建具有指定配置的设备。如果省略此参数，系统将创建 medium_phone 个人资料。

emulator list

用法： android emulator list

说明：列出可用的虚拟设备。

emulator start

用法： android emulator start <device-name>

说明：启动指定的虚拟设备。

实参（必需）：

  • <device-name> - 要启动的设备名称（例如 medium_phone）。使用 android emulator list 可查看可用设备。

示例：android emulator start medium_phone

emulator stop

用法： android emulator stop <device-serial-number>

说明：停止指定的虚拟设备。

实参（必需）：

  • <device-serial-number> - 要停止的设备序列号。

示例：android emulator stop emulator-5554

info

用法： android info

说明：显示所用默认 Android SDK 的路径。如需更改所用的 Android SDK，请使用 --sdk。

init

用法： android init

说明：通过安装 android-cli 技能，为代理设置环境。

layout

用法： android layout [--pretty] [--output] [--diff]

说明：以 JSON 格式返回有效 Android 应用（通过实体设备或模拟器连接）的界面布局。

选项：

  • -p, --pretty - 使用缩进和换行符设置 JSON 输出的格式，以便于用户阅读。
  • -o, --output - 指定用于保存布局树的文件位置。如果省略，JSON 会直接输出到标准输出。
  • -d, --diff - 返回自上次拍摄内部快照（上次运行布局）以来发生更改的布局元素列表，而不是完整的布局树。

示例：android layout --output=./hierarchy.json

skills add

Android 技能是专门设计的指令，旨在帮助智能体更好地理解和执行遵循 Android 开发最佳实践和指南的特定模式。如需了解详情，请参阅 Android 技能简介。

用法： android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

说明：将 Android 技能安装到所有检测到的代理的技能目录中。如果您没有任何现有的代理目录，并且未指定特定代理，则技能将安装到 ~/.gemini/antigravity/skills 中，供 Gemini 和 Antigravity 使用。

选项：

  • --all - 一次性添加所有 Android 技能。如果省略此参数（且未指定 --skill），则只会安装 android-cli 技能。
  • --agent - 要为其安装技能的代理的逗号分隔列表。如果省略，则将为所有检测到的代理安装技能。
  • --skill - 要安装的技能的名称。如果省略此参数（且未指定 --all），则只会安装 android-cli 技能。

示例：android skills add --agent='gemini' edge-to-edge

skills find

用法： android skills find <string>

说明：查找与给定字符串匹配的技能。

实参（必需）：

  • string - 与技能说明匹配的字符串。

示例：android skills find 'performance'

skills list

用法： android skills list [--long]

说明：列出可用的技能。

选项：

  • --long - 输出每项技能的其他信息，包括技能说明以及已安装技能的代理。

skills remove

用法： android skills remove [--agent] --skill=<skill-name>

说明：移除技能。如果您未指定特定代理，系统会为所有代理移除该技能。

实参（必需）：

  • --skill - 要移除的技能的名称。

选项：

  • --agent - 要移除技能的客服人员列表（以逗号分隔）。如果省略，则会为所有代理移除相应技能。

示例：android skills remove --agent='gemini' --skill=edge-to-edge

screen capture

用法： android screen capture [--output] [--annotate]

说明：捕获已连接设备的屏幕截图。

选项：

  • -o, --output - 指定用于保存屏幕截图的文件位置。如果省略，原始 PNG 数据将直接打印到标准输出。
  • -a, --annotate - 在图片上检测到的所有界面元素周围绘制带标签的边界框，以便与 resolve 命令搭配使用。

示例：android screen capture --output=ui.png

screen resolve

用法： android screen resolve --screenshot=<path> --string=<string>

说明：将使用 screen capture 捕获的带注释的屏幕截图中的视觉标签转换为实际屏幕坐标 (x, y)。有助于通过脚本点击元素，而无需手动计算其位置。

标志：

  • --screenshot - 带注释的屏幕截图的路径。
  • --string - 一个字符串，其中包含至少一个与界面元素标签对应的占位符，格式为 #<number>。#<number> 部分将被屏幕坐标替换。

示例：

如果标签 5 位于坐标 (500, 1000)，则以下命令

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

返回输出

input tap 500 1000

sdk install

用法： android sdk install <package[@version]> [--beta] [--canary] [--force]

说明：安装指定的 SDK 软件包。

实参（必需）：

  • package[@version] - 以空格分隔的待安装软件包列表。如果未指定版本，则会安装渠道中的最新版本（默认情况下为稳定版渠道）。

选项：

  • --beta - 包含 Beta 版软件包。
  • --canary - 包含 Canary 版软件包。
  • --force - 强制降级到旧版本。

示例：

  • android sdk install platforms/android-34 build-tools/34.0.0 - 从稳定版渠道安装最新版本的 Android SDK Platform 34 和 SDK Build Tools 34.0.0 软件包。
  • android sdk install platforms/android-34@2 - 安装 Android SDK 平台 34 软件包的版本 2。
  • android sdk install --canary system-images/android-35/google_apis/x86_6 - 从 Canary 渠道安装最新版本的 Android 35 系统映像。
  • android sdk install --force platforms/android-33@1 - 从稳定渠道恢复到 Android SDK Platform 33 软件包的版本 1。

sdk list

用法： android sdk list <package-pattern>

说明：列出已安装和可用的 SDK 软件包。

实参（必需）：

  • <package-pattern> - 按模式过滤软件包。支持正则表达式。

选项：

  • --all - 显示所有已安装和可用的软件包。
  • --all-versions - 显示每个软件包的所有版本。
  • --beta - 包含 Beta 版软件包。
  • --canary - 包含 Canary 版软件包。

sdk remove

用法： android sdk remove <package-name>

说明：从 SDK 中移除软件包。

实参（必需）：

  • <package-name> - 要移除的软件包的名称。

示例：android sdk remove build-tools/36.1.0

run

用法： android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

说明：将 Android 应用部署到已连接的设备或模拟器。它不会执行任何构建步骤；您必须提供要安装的 APK 文件的路径。

实参（必需）：

  • --apks - 以英文逗号分隔的要安装的 APK 文件路径列表。该路径相对于您当前在文件系统中的位置。

选项：

  • --activity - APK 安装完毕后要启动的 activity 的名称。如果有多个 activity，您必须指定一个要最初启动的 activity。
  • --debug - 在调试模式下部署应用。在调试模式下运行应用后，您必须从 IDE（例如 Android Studio）或命令行工具连接调试器，才能开始调试。
  • --device - 目标设备或模拟器的序列号。仅在连接多个设备时才需要使用。如需查找设备序列号，请运行 adb devices。
  • --type - 要启动的组件类型。如果您想直接启动后台服务而不是界面 activity，请使用此方法。支持的类型：
    • ACTIVITY
    • WATCH_FACE
    • TILE
    • COMPLICATION
    • DECLARATIVE_WATCH_FACE

示例：

  • android run --apks=app/build/outputs/apk/debug/app-debug.apk - 将单个 APK 部署到默认设备。
  • android run --apks=base.apk,density-hdpi.apk,lang-en.apk - 将多个 APK 部署到默认设备。
  • android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService - 测试没有 activity 的服务。
  • android run --apks=app-debug.apk --device=emulator-5554 - 将 APK 部署到特定设备。

sdk update

用法： android sdk update [--beta] [--canary] [<package-name>]

说明：将一个或所有软件包更新为渠道中的最新版本（默认情况下为稳定版渠道）。如果您未指定软件包，则所有软件包都将更新。

选项：

  • <package-name> - 要更新的软件包的名称。
  • --beta - 包含 Beta 版软件包。
  • --canary - 包含 Canary 版软件包。
  • --force - 强制降级到旧版本。

示例：

  • android sdk update - 检查并安装 SDK 中所有内容的更新。
  • android sdk update build-tools/34.0.0 - 将 Android SDK Build Tools 34.0.0 软件包更新为稳定渠道中的最新版本。
  • android sdk update --canary platforms/android-35 - 将 Android SDK 平台 35 软件包更新为 Canary 渠道中的最新版本。

update

用法： android update

说明：更新 Android CLI。

-V, --version

说明：显示 Android CLI 的当前版本。