1. 它是什么,解決什么問(wèn)題
Android CLI 是 Google 提供的獨(dú)立命令行入口(可執(zhí)行文件通常名為 android),目標(biāo)是把 Android 開(kāi)發(fā)里常見(jiàn)、但分散在多套工具里的操作,收斂到統(tǒng)一界面里,例如:
- SDK / 平臺(tái)包的安裝、升級(jí)、卸載與列舉
- 從模板創(chuàng)建工程
- 在真機(jī)或模擬器上安裝并運(yùn)行 APK
- 模擬器(AVD)的創(chuàng)建、啟動(dòng)、停止、列舉、刪除
- 截屏、屏幕相關(guān)輔助能力
- 對(duì)工程做結(jié)構(gòu)化描述(便于自動(dòng)化工具消費(fèi))
-
在終端里搜索并拉取官方知識(shí)庫(kù)文檔(
docs search/docs fetch) - CLI 自身升級(jí)、環(huán)境信息打印等
對(duì)團(tuán)隊(duì)而言,價(jià)值主要在于:腳本化、CI 友好、與 Agent/自動(dòng)化工具銜接——尤其是 describe 輸出 JSON、layout 輸出布局樹(shù)、docs 對(duì)接知識(shí)庫(kù)這幾塊。
2. 安裝與全局選項(xiàng)
各平臺(tái)一鍵安裝腳本示例:
| 平臺(tái) | 命令 |
|---|---|
| Linux x86_64 | curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash |
| macOS ARM | curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash |
| macOS Intel | curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash |
| Windows | 下載 https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd 后執(zhí)行 |
常用全局參數(shù):
-
-h/--help:幫助 -
-V/--version:版本 -
--sdk=路徑:顯式指定 Android SDK 根目錄(多 SDK、CI 鏡像里很有用)
安裝后建議先跑:
android info
用于確認(rèn) SDK 位置、環(huán)境變量 等是否符合預(yù)期(info 可帶字段名只輸出單項(xiàng))。
3. 能力地圖:子命令一覽
根據(jù) android help 歸納,核心子命令包括:
| 領(lǐng)域 | 命令 | 典型用途 |
|---|---|---|
| SDK | android sdk |
install / update / remove / list
|
| 工程腳手架 | android create |
從模板創(chuàng)建應(yīng)用(如 empty-activity) |
| 工程元數(shù)據(jù) | android describe |
分析工程,輸出 JSON 路徑(構(gòu)建產(chǎn)物、目標(biāo)等) |
| 運(yùn)行 | android run |
指定 APK、Activity、設(shè)備序列號(hào)、組件類(lèi)型等部署運(yùn)行 |
| 模擬器 | android emulator |
create / start / stop / list / remove
|
| 屏幕 | android screen |
capture(PNG)、resolve(按視覺(jué)定位 UI) |
| 布局調(diào)試 | android layout |
導(dǎo)出當(dāng)前界面布局樹(shù)(JSON),支持 --pretty、--diff
|
| 文檔 | android docs |
search / fetch
|
| 技能包 | android skills |
add / remove / list / find(與 Agent 生態(tài)相關(guān),詳見(jiàn) 第 9 節(jié)) |
| 維護(hù) | android update |
升級(jí) CLI;可選 --url
|
| 初始化 | android init |
初始化環(huán)境(如 skills 等) |
與 adb、Gradle、Android Studio 的關(guān)系可以概括為:Android CLI 偏「環(huán)境與設(shè)備側(cè) + 官方知識(shí)庫(kù) + 部分高層自動(dòng)化」,不替代 Gradle 構(gòu)建體系,而是與之互補(bǔ)(例如 CI 里先 sdk install 再 ./gradlew assemble,最后用 android run 裝到指定設(shè)備)。
4. SDK 管理:日常最常用的子集
# 列出已安裝與可用包(含 --all 等選項(xiàng)以官方 help 為準(zhǔn))
android sdk list --all
# 安裝指定平臺(tái)(可指定版本,未寫(xiě)版本則取合適默認(rèn)/最新策略以工具行為為準(zhǔn))
android sdk install platforms/android-34
# 更新單個(gè)或全部包
android sdk update
android sdk update platforms/android-34
# 卸載
android sdk remove <pkg-name>
實(shí)踐建議:在 Dockerfile / CI YAML 里把 android sdk install 寫(xiě)死為明確版本,避免「latest」漂移導(dǎo)致構(gòu)建不可復(fù)現(xiàn)。
5. 從模板創(chuàng)建工程
# 列出模板
android create --list
# 示例:空 Activity 模板
android create empty-activity --name="My App" --output=./my-app
可按需加 --minSdk=api 等參數(shù)(以 android create -h 為準(zhǔn))。
6. 模擬器與運(yùn)行
模擬器
android emulator list
android emulator create ...
android emulator start <avd名稱(chēng)> # 文檔說(shuō)明:?jiǎn)?dòng)完成后再返回,利于腳本串聯(lián)
android emulator stop ...
android emulator remove ...
運(yùn)行 APK(示意)
android run --apks=app-debug.apk --device=<serial> --activity=<完整類(lèi)名>
--type 可用于 ACTIVITY / SERVICE 等組件類(lèi)型;--debug 用于調(diào)試模式運(yùn)行。具體組合以 android run -h 為準(zhǔn)。
7. 文檔子系統(tǒng):docs search + docs fetch
這是 Android CLI 里很有辨識(shí)度的一塊:在終端對(duì)接 Android 知識(shí)庫(kù),適合查遷移指南、示例、最佳實(shí)踐。
搜索
android docs search WorkManager
行為要點(diǎn):
- 首次可能出現(xiàn) 「Waiting for index to be ready...」,屬索引準(zhǔn)備,稍等即可。
- 結(jié)果條目里帶有
kb://android/...形式的 URL(知識(shí)庫(kù) URI),并附標(biāo)題與摘要。
拉取正文
android docs fetch "kb://android/develop/background-work/background-tasks/persistent/getting-started/index"
fetch 的參數(shù)應(yīng)使用 search 返回的 URL(見(jiàn) android docs fetch -h 說(shuō)明)。
分享場(chǎng)景:在團(tuán)隊(duì)里可以約定「先 docs search 鎖定 kb 鏈接,再 docs fetch 進(jìn) wiki / PR 描述」,比瀏覽器關(guān)鍵詞搜索更貼近官方知識(shí)結(jié)構(gòu)。
8. 調(diào)試與自動(dòng)化向能力
android describe
對(duì)工程做靜態(tài)分析,輸出「JSON 元數(shù)據(jù)文件路徑」等信息,方便其他工具定位 APK、構(gòu)建目標(biāo)等——適合作為 CI 后續(xù)步驟的輸入。
如:
Target project directory: /Users/yanyan/Desktop/sohu/sns/sns/.
Project directory exists: /Users/yanyan/Desktop/sohu/sns/sns/.
init.gradle.kts is up to date.
Parsed tasks:
.......
Task: :share_module
Variants:
Variant: flavorsDevDebug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsTest_arm64Debug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsOnline_arm64Debug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsDevRelease
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsTest_arm64Release
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsOnline_arm64Release
Output Listing File: null
Output listing file does not exist on disk.
Task: :app
Variants:
Variant: flavorsDevDebug
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsDevDebug/createFlavorsDevDebugApkListingFileRedirect/redirect.txt
APK: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk/flavorsDev/debug/hy_flavorsDev_debug_V6.21.0_1545.apk (Exists)
Variant: flavorsTest_arm64Debug
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsTest_arm64Debug/createFlavorsTest_arm64DebugApkListingFileRedirect/redirect.txt
APK: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk/flavorsTest_arm64/debug/hy_flavorsTest_arm64_debug_V6.17.0_1520.apk (Exists)
Variant: flavorsOnline_arm64Debug
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsOnline_arm64Debug/createFlavorsOnline_arm64DebugApkListingFileRedirect/redirect.txt
APK: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk/flavorsOnline_arm64/debug/hy_flavorsOnline_arm64_debug_V6.18.2_1531.apk (Exists)
Variant: flavorsDevRelease
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsDevRelease/createFlavorsDevReleaseApkListingFileRedirect/redirect.txt
APK: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk/flavorsDev/release/hy_flavorsDev_release_V6.16.0_1515.apk (Exists)
Variant: flavorsTest_arm64Release
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsTest_arm64Release/createFlavorsTest_arm64ReleaseApkListingFileRedirect/redirect.txt
Output listing file does not exist on disk.
Variant: flavorsOnline_arm64Release
Output Listing File: /Users/yanyan/Desktop/sohu/sns/sns/app/build/intermediates/apk_ide_redirect_file/flavorsOnline_arm64Release/createFlavorsOnline_arm64ReleaseApkListingFileRedirect/redirect.txt
Output listing file does not exist on disk.
Task: :report_module
Variants:
Variant: flavorsDevDebug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsTest_arm64Debug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsOnline_arm64Debug
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsDevRelease
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsTest_arm64Release
Output Listing File: null
Output listing file does not exist on disk.
Variant: flavorsOnline_arm64Release
Output Listing File: null
Output listing file does not exist on disk.
.......
這段輸出 = 「工程里有哪些模塊、每個(gè) flavor 的 debug/release 變體、IDE 用的 APK 清單文件路徑、以及當(dāng)前磁盤(pán)上是否已經(jīng)存在對(duì)應(yīng) APK」;大量 null / does not exist 多半表示 那個(gè)變體還沒(méi)構(gòu)建出 APK,而不是工程壞了。若要某一行變成 (Exists),對(duì)該 Variant 執(zhí)行一次對(duì)應(yīng)的 assemble(例如 ./gradlew :app:assembleFlavorsDevDebug)即可。
android layout
抓取當(dāng)前前臺(tái)應(yīng)用的 布局樹(shù) JSON;--pretty 美化;--diff 可與上次 dump 對(duì)比變更,比反復(fù)截屏更適合 diff 與自動(dòng)化斷言。
如:執(zhí)行android layout --pretty
[
{
"interactions": [
"clickable",
"focusable"
],
"center": "[622,1981]",
"resource-id": "rl_level_container",
"key": 3506402
},
{
"content-desc": "圈子等級(jí)",
"center": "[529,1180]",
"resource-id": "iv_level",
"key": 3506402
},
{
"text": "封神世界哈哈",
"center": "[636,1181]",
"resource-id": "tv_level_title",
"key": 3506402
}
]
android screen
capture 輸出 PNG;resolve 面向「按畫(huà)面找控件」類(lèi)工作流(預(yù)計(jì)輸入要找的文本內(nèi)容,輸出坐標(biāo)。但實(shí)際測(cè)試中失敗了,原因還未知)。
9. android skills:技能包是什么、能干什么、怎么用
9.1 定位:為什么 CLI 里會(huì)有「skills」
android skills 管理的是一組 面向 AI 編程助手(Agent)的結(jié)構(gòu)化說(shuō)明文檔(通常以 SKILL.md 等形式下發(fā)到本機(jī)),用來(lái)在 Cursor、Claude Code、Gemini、Antigravity 等環(huán)境里,統(tǒng)一告訴模型:遇到某類(lèi) Android 任務(wù)時(shí)按什么流程、約束和檢查清單來(lái)干活。
可以把它理解成:
- 對(duì)模型:可檢索的「專(zhuān)項(xiàng) playbook」,減少幻覺(jué)、對(duì)齊官方遷移路徑。
- 對(duì)團(tuán)隊(duì):把常見(jiàn)改造(AGP 升級(jí)、CameraX、R8 規(guī)則治理)沉淀成可安裝、可版本化的資產(chǎn)。
-
對(duì) Android CLI:
android init會(huì)把android-cli這一條 skill 裝到各 Agent 的技能目錄里,讓助手在回答 Android 問(wèn)題時(shí)優(yōu)先遵循同一套 CLI 能力說(shuō)明。
與倉(cāng)庫(kù)里自管的 Cursor Skills 的區(qū)別:本倉(cāng)庫(kù) .cursor/skills/ 等是項(xiàng)目或團(tuán)隊(duì)自定義的指引;android skills 下發(fā)的是 Google Android CLI 生態(tài)維護(hù)的「官方技能目錄」,由 android skills list 列出,用 add / remove 安裝到本機(jī) Agent 配置路徑。
9.2 命令與子命令用法
子命令總覽(無(wú)全局 --help,需看各子命令用法或缺參提示):
android skills [COMMAND]
Commands:
add Install a skill
remove Remove a skill
list List available skills
find Find skills by keyword
list:查看目錄里有哪些技能
# 簡(jiǎn)短列表(首次可能下載/更新索引,需等待進(jìn)度條完成)
android skills list
# 長(zhǎng)格式:含英文說(shuō)明與「Installed for」Agent 類(lèi)型
android skills list --long
# 僅看某個(gè)工程根下已安裝的技能(若 CLI 支持從工程解析安裝位置)
android skills list --project=/path/to/your/android/project
find:按關(guān)鍵詞在目錄里搜技能
# 用法:android skills find <keyword>(keyword 為位置參數(shù),不是 --keyword)
android skills find billing
android skills find compose
android skills find r8
find 的返回形態(tài)與 list --long 類(lèi)似:會(huì)列出摘要命中的若干條技能(含英文說(shuō)明與 Installed for),便于復(fù)制準(zhǔn)確的 --skill=id。
適合在不知道準(zhǔn)確 skill id 時(shí),先 find 再 add --skill=...。
add:把指定技能安裝到本機(jī) Agent
# 安裝單個(gè)技能到「當(dāng)前能檢測(cè)到的全部 Agent」(未指定 --agent 時(shí)的默認(rèn)行為)
android skills add --skill=r8-analyzer
# 只給部分 Agent 安裝(逗號(hào)分隔,具體取值以你本機(jī) CLI 提示為準(zhǔn))
android skills add --skill=agp-9-upgrade --agent=cursor,claude-code
# 在給定工程上下文中安裝(與 --project 語(yǔ)義以 CLI 為準(zhǔn))
android skills add --skill=edge-to-edge --project=/path/to/project
# 一鍵安裝目錄中的全部技能
android skills add --all
remove:卸載已安裝技能
android skills remove --skill=r8-analyzer
# 可選:只從指定 Agent 卸載
android skills remove --skill=r8-analyzer --agent=cursor
android skills remove --skill=navigation-3 --project=/path/to/project
9.3 android init 與技能的關(guān)系
執(zhí)行:
android init
在本機(jī)上的典型行為是:把 android-cli 這一條 skill 寫(xiě)入多個(gè) Agent 的技能目錄(例如 Cursor、Claude、Gemini、Antigravity 等路徑下的 skills/android-cli)。這樣助手在討論「如何用 android 命令行」時(shí),會(huì)有一份與 CLI 版本配套的權(quán)威說(shuō)明可遵循。
若你希望團(tuán)隊(duì)「換電腦后行為一致」,文檔化約定可以是:裝完 Android CLI 后執(zhí)行一次 android init,再按需 android skills add 其他專(zhuān)項(xiàng)技能。
9.4 當(dāng)前官方目錄中的技能一覽(干什么用)
下列技能名稱(chēng)與說(shuō)明整理自 android skills list --long 的輸出(2026-05 于本機(jī) CLI 校對(duì);官方目錄會(huì)隨 CLI 版本變化,若與你本機(jī)不一致,請(qǐng)以 android skills list --long 為準(zhǔn))。
每條在列表中的 「Installed for」 一般包含:antigravity、claude-code、common、cursor、gemini 等,表示該技能包設(shè)計(jì)為可被這些類(lèi)型的 Agent 消費(fèi)(實(shí)際是否已安裝到本機(jī),取決于你是否執(zhí)行過(guò) add / init)。
| Skill ID | 用途簡(jiǎn)述 |
|---|---|
android-cli |
Android CLI 總覽:工程創(chuàng)建、部署、SDK 管理、環(huán)境診斷等與 android 命令行相關(guān)的編排說(shuō)明(與本文主題直接對(duì)應(yīng))。 |
base |
通用 Android 任務(wù)編排(偏總述),與 android-cli 同屬「底座」類(lèi)說(shuō)明。 |
agp-9-upgrade |
將工程 升級(jí)/遷移到 Android Gradle Plugin 9;不用于 Kotlin Multiplatform(KMP)工程的同類(lèi)遷移。 |
camera1-to-camerax |
把 Camera1 或裸 Camera2 遷移到 CameraX(生命周期、旋轉(zhuǎn)與機(jī)型差異等)。 |
navigation-3 |
Jetpack Navigation 3:安裝與遷移,以及深鏈、多返回棧、Scenes(對(duì)話框 / BottomSheet / 列表-詳情等)、條件導(dǎo)航、與 Hilt / ViewModel / View 互操作等。 |
display-ai-glasses-with-jetpack-compose-glimmer |
Android Display AI 眼鏡 上的投影式 UI:基于 Jetpack Compose Glimmer 的設(shè)計(jì)原則、實(shí)現(xiàn)流程與眼鏡形態(tài)交互。 |
perfetto-sql |
把自然語(yǔ)言的數(shù)據(jù)分析意圖轉(zhuǎn)成 合法的 Perfetto SQL,并在本地 trace 上通過(guò) trace_processor 執(zhí)行,提取 slice / 線程 / 內(nèi)存等。 |
edge-to-edge |
Compose 邊到邊:系統(tǒng)欄區(qū)域、列表/按鈕被導(dǎo)航欄或狀態(tài)欄遮擋、IME inset、系統(tǒng)欄對(duì)比度等問(wèn)題排查與遷移。 |
play-billing-library-version-upgrade |
將 Google Play Billing Library 從舊版升級(jí)到當(dāng)前穩(wěn)定版的遷移指引。 |
r8-analyzer |
分析 Gradle 構(gòu)建與 R8 / ProGuard keep 規(guī)則:冗余規(guī)則、過(guò)寬的包級(jí) keep、可被庫(kù)自帶規(guī)則覆蓋的規(guī)則等,用于包體與混淆治理。 |
migrate-xml-views-to-jetpack-compose |
XML View → Jetpack Compose 的結(jié)構(gòu)化遷移流程(依賴(lài)、主題、布局、驗(yàn)證與 XML 清理)。 |
說(shuō)明:list --long 里 android-cli 可能出現(xiàn)重復(fù)條目,屬于目錄展示層面的重復(fù),skill id 仍以 android-cli 為準(zhǔn),安裝時(shí) --skill=android-cli 即可。
9.5 使用建議與注意點(diǎn)
-
先
find再add:關(guān)鍵詞用業(yè)務(wù)語(yǔ)言即可(如billing、camera、compose),不必背全 id。 -
list可能拉取索引:首次或更新后會(huì)出現(xiàn)進(jìn)度條,屬正常;CI 里若要列技能,需預(yù)留超時(shí)。 -
與團(tuán)隊(duì)規(guī)范結(jié)合:可把「新成員 onboarding」寫(xiě)成:安裝 CLI →
android init→ 按崗位add(例如負(fù)責(zé)性能的同學(xué)加perfetto-sql,負(fù)責(zé)發(fā)布同學(xué)加r8-analyzer)。 -
版本漂移:技能正文會(huì)隨 Google 側(cè)更新;重要項(xiàng)目可在 wiki 里記錄「當(dāng)時(shí)
android skills list截屏或?qū)С觥?,便于回溯?/li>
10. 運(yùn)維與踩坑備忘
-
分析/遙測(cè)寫(xiě)本地目錄:若環(huán)境對(duì)
~/.android/cli/...不可寫(xiě),可能出現(xiàn)與 Usage metrics / analytics 相關(guān)的啟動(dòng)失敗。CI 或沙箱里需保證該目錄可寫(xiě),或按官方后續(xù)說(shuō)明關(guān)閉/重定向(以當(dāng)前版本行為為準(zhǔn))。 -
--sdk:多版本 SDK 并存時(shí),顯式傳參避免讀到錯(cuò)誤的全局配置。 -
與 Gradle:構(gòu)建仍建議
./gradlew;CLI 更擅長(zhǎng) SDK/設(shè)備/文檔/高層運(yùn)行 這條線。 -
權(quán)限與網(wǎng)絡(luò):
sdk install、CLIupdate、docs首次索引等可能依賴(lài)網(wǎng)絡(luò),企業(yè)代理需單獨(dú)配置。
11. 小結(jié)
Android CLI 把 SDK 生命周期、工程腳手架、模擬器、安裝運(yùn)行、屏幕與布局、官方文檔檢索 串成同一入口,特別適合:
- 本地/CI 一鍵搭環(huán)境
- 腳本化跑 APK、起模擬器
- 與 Agent / 自動(dòng)化 結(jié)合(
describe、layout、docs、skills)
參考
- 安裝與各子命令說(shuō)明來(lái)自 Google Android CLI 官方幫助(
android help)。 -
android skills技能目錄:以本機(jī)android skills list --long為準(zhǔn);子命令用法以缺參時(shí)的 Usage 提示為準(zhǔn)(如android skills add、android skills remove)。 - 設(shè)備交互與 Journey 測(cè)試等延伸說(shuō)明:https://developer.android.com/agents/skills/android-cli/base/references/interact、https://developer.android.com/agents/skills/android-cli/base/references/journeys