Android CLI 總覽

Android CLI 是一種指令列介面，可讓您使用任何選擇的工具，更輕鬆有效率地建構 Android 應用程式。這項認證會針對以代理程式為優先的工作流程，提供核心開發能力標準，並提供官方工具、技能和知識的入門資訊，協助您更有效率地開發。此外，隨著 Android 開發作業越來越分散，這個工具也能簡化 CI、維護作業和任何其他指令碼自動化作業。

舉例來說，代理程式或指令碼可以使用 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 檔案的路徑，詳細說明專案結構，包括建構目標和對應的輸出構件位置 (例如 APK 檔案)。這項資訊可讓其他工具和指令有效率地找出建構構件。

選項：

  • --project_dir：要說明的專案目錄。如果省略，系統會使用目前的目錄。

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

docs

使用方式：

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

說明：android docs 指令是存取 Android 知識庫的兩步驟程序，可直接從 CLI 存取。首先，使用 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 應用程式 (透過實體裝置或模擬器連線) 的 UI 版面配置。

選項：

  • -p, --pretty - 格式化 JSON 輸出內容，加入縮排和換行符號，方便使用者閱讀。
  • -o, --output：指定儲存版面配置樹狀結構的檔案位置。如果省略，JSON 會直接列印至 stdout。
  • -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 資料會直接列印至 stdout。
  • -a, --annotate：在圖片上偵測到的所有 UI 元素周圍繪製標示的定界框，以搭配 resolve 指令使用。

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

screen resolve

使用方式： android screen resolve --screenshot=<path> --string=<string>

說明：將使用 screen capture 擷取的註解螢幕截圖中的視覺標籤，轉換為實際的螢幕座標 (x, y)。這項功能有助於編寫指令碼，點選元素，不必手動計算元素位置。

旗標：

  • --screenshot - 加上註解的螢幕截圖路徑。
  • --string：字串，至少包含一個對應至 UI 元素標籤的預留位置，格式為 #<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 - 納入初期測試版套件。
  • --force - 強制降級至舊版。

這些檢查包括：

  • android sdk install platforms/android-34 build-tools/34.0.0 - 從穩定版管道安裝最新版本的 Android SDK Platform 34 和 SDK Built Tools 34.0.0 套件。
  • android sdk install platforms/android-34@2 - 安裝 Android SDK Platform 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 - 納入初期測試版套件。

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 檔案路徑清單，列出您要安裝的 APK 檔案。路徑是相對於您目前在檔案系統中的位置。

選項：

  • --activity：APK 安裝完成後要啟動的活動名稱。如果有多個活動，您必須指定要啟動的初始活動。
  • --debug - 在偵錯模式下部署應用程式。以偵錯模式執行應用程式後，您必須從 IDE (例如 Android Studio) 或指令列工具連線偵錯工具，才能開始偵錯。
  • --device - 目標裝置或模擬器的序號。只有在連線多部裝置時才需要。如要找出裝置序號，請執行 adb devices。
  • --type - 要啟動的元件類型。如要直接啟動背景服務，而非啟動 UI 活動，請使用這個方法。支援的類型：
    • 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 - 測試沒有活動的服務。
  • android run --apks=app-debug.apk --device=emulator-5554 - 將 APK 部署到特定裝置。

sdk update

使用方式： android sdk update [--beta] [--canary] [<package-name>]

說明：在管道 (預設為穩定管道) 中，將一或多個套件更新至最新版本。如未指定套件，系統會更新所有套件。

選項：

  • <package-name> - 要更新的套件名稱。
  • --beta - 包含 Beta 版套件。
  • --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 Platforms 35 套件更新至 Canary 管道的最新版本。

update

使用方式： android update

說明：更新 Android CLI。

-V, --version

說明：顯示 Android CLI 的目前版本。