Android CLI

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 等)

adbGradle、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 CLIandroid 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í),先 findadd --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-codecommon、cursorgemini 等,表示該技能包設(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 --longandroid-cli 可能出現(xiàn)重復(fù)條目,屬于目錄展示層面的重復(fù),skill id 仍以 android-cli 為準(zhǔn),安裝時(shí) --skill=android-cli 即可。

9.5 使用建議與注意點(diǎn)

  1. findadd:關(guān)鍵詞用業(yè)務(wù)語(yǔ)言即可(如 billing、camera、compose),不必背全 id。
  2. list 可能拉取索引:首次或更新后會(huì)出現(xiàn)進(jìn)度條,屬正常;CI 里若要列技能,需預(yù)留超時(shí)。
  3. 與團(tuán)隊(duì)規(guī)范結(jié)合:可把「新成員 onboarding」寫(xiě)成:安裝 CLI → android init → 按崗位 add(例如負(fù)責(zé)性能的同學(xué)加 perfetto-sql,負(fù)責(zé)發(fā)布同學(xué)加 r8-analyzer)。
  4. 版本漂移:技能正文會(huì)隨 Google 側(cè)更新;重要項(xiàng)目可在 wiki 里記錄「當(dāng)時(shí) android skills list 截屏或?qū)С觥?,便于回溯?/li>

10. 運(yùn)維與踩坑備忘

  1. 分析/遙測(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))。
  2. --sdk:多版本 SDK 并存時(shí),顯式傳參避免讀到錯(cuò)誤的全局配置。
  3. 與 Gradle:構(gòu)建仍建議 ./gradlew;CLI 更擅長(zhǎng) SDK/設(shè)備/文檔/高層運(yùn)行 這條線。
  4. 權(quán)限與網(wǎng)絡(luò)sdk install、CLI update、docs 首次索引等可能依賴(lài)網(wǎng)絡(luò),企業(yè)代理需單獨(dú)配置。

11. 小結(jié)

Android CLI 把 SDK 生命周期、工程腳手架、模擬器、安裝運(yùn)行、屏幕與布局、官方文檔檢索 串成同一入口,特別適合:

  • 本地/CI 一鍵搭環(huán)境
  • 腳本化跑 APK、起模擬器
  • Agent / 自動(dòng)化 結(jié)合(describelayout、docs、skills

參考

最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成,瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明:文章內(nèi)容(如有圖片或視頻亦包括在內(nèi))由作者上傳并發(fā)布,文章內(nèi)容僅代表作者本人觀點(diǎn),簡(jiǎn)書(shū)系信息發(fā)布平臺(tái),僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容