Tổng quan về giao diện dòng lệnh Android

Android CLI là một giao diện dòng lệnh giúp bạn dễ dàng và hiệu quả hơn khi tạo bản dựng cho Android bằng bất kỳ công cụ nào bạn chọn. Nền tảng này tiêu chuẩn hoá các năng lực phát triển cốt lõi cho quy trình làm việc ưu tiên tác nhân, cung cấp điểm truy cập vào các công cụ, kỹ năng và kiến thức chính thức mà bạn cần để phát triển hiệu quả hơn. Công cụ này cũng có thể tinh giản quy trình CI, bảo trì và mọi quy trình tự động hoá khác dựa trên tập lệnh cho bản chất ngày càng phân tán của quá trình phát triển Android.

Ví dụ: một tác nhân hoặc tập lệnh có thể sử dụng CLI để tự động hoá quá trình thiết lập môi trường, tạo khung cho các dự án mới từ mẫu và quản lý thiết bị ảo ngay từ thiết bị đầu cuối. Công cụ này cũng cho phép các đặc vụ của bạn truy cập vào các kỹ năng của Android và Cơ sở kiến thức chuyên biệt về Android để đảm bảo rằng các dự án của bạn áp dụng các mẫu và phương pháp hay nhất mà Android đề xuất.

Cài đặt Android CLI

Để cài đặt Android CLI, hãy làm theo các bước sau:

  1. Tải CLI Android xuống.

  2. Để đảm bảo bạn đang sử dụng phiên bản mới nhất, hãy cập nhật Android CLI:

    android update

Để kiểm tra xem Android CLI đã được cài đặt trên máy của bạn hay chưa, hãy chạy which android hoặc command -v android: nếu lệnh này trả về một đường dẫn, thì tức là Android CLI đã được cài đặt.

Thiết lập cho nhân viên hỗ trợ

Để giúp các trợ lý ảo hiểu và sử dụng Android CLI, hãy chạy init để cài đặt kỹ năng android-cli:

android init

Vấn đề đã biết

  • Lệnh android emulator cho Windows hiện đang bị vô hiệu hoá.

Nếu bạn gặp bất kỳ vấn đề nào hoặc muốn gửi ý kiến phản hồi, vui lòng báo cáo lỗi.

Định cấu hình CLI Android

Tạo tệp .androidrc để tự động áp dụng cờ và lựa chọn mỗi khi bạn gọi Android CLI. Lưu tệp ở vị trí sau đây, tuỳ thuộc vào hệ điều hành của bạn:

  • macOS và Linux: ~/.androidrc
  • Windows: %USERPROFILE%\.androidrc

Thêm các cờ bạn muốn tự động áp dụng cho tệp, mỗi cờ trên một dòng.

Ví dụ: để Android CLI sử dụng một SDK Android cụ thể theo mặc định mỗi lần, hãy thêm cờ --sdk vào tệp của bạn:

--sdk=<path-to-sdk>

Tuỳ chọn chung

Đây là các cờ không bắt buộc mà bạn có thể dùng với các lệnh CLI Android khác.

-h, --help

Cách sử dụng: android <command> -h

Nội dung mô tả: Hiển thị tài liệu trợ giúp cho công cụ hoặc lệnh cụ thể đang được đề cập.

Ví dụ:

  • android -h
  • android create -h

--sdk

Cách sử dụng: android --sdk=<path-to-sdk> <command>

Nội dung mô tả: Đường dẫn đến SDK Android mà bạn muốn dùng cho lệnh tiếp theo. Bạn có thể sử dụng chế độ cài đặt --sdk để tạm thời ghi đè SDK Android mặc định thay vì thay đổi biến môi trường chung mỗi khi muốn chuyển đổi. Để kiểm tra xem bạn đang dùng SDK Android nào theo mặc định, hãy chạy android info.

Ví dụ: android --sdk=<path/to/sdk> sdk list

Lệnh

Phần này liệt kê tất cả các lệnh CLI Android và mô tả chức năng của các lệnh đó. Tất cả các lệnh này đều phải bắt đầu bằng android, ví dụ: android create, android run, v.v. Các đối tượng sửa đổi không bắt buộc được đặt trong dấu ngoặc vuông [], còn các đối số bắt buộc thì không.

create

Cách sử dụng: android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]

Nội dung mô tả: Khởi chạy một dự án mới từ mẫu. Để xem các lựa chọn về mẫu, hãy chạy android create -h.

Đối số (bắt buộc):

  • -o, --output – Đường dẫn thư mục dự án đích.

Lựa chọn:

  • --dry-run – Mô phỏng toàn bộ quy trình tạo dự án mà không thực sự lưu bất kỳ tệp nào. Ví dụ: bạn có thể chạy thử nghiệm để xem chức năng của các mẫu khác nhau trước khi cam kết sử dụng một mẫu.
  • --verbose – Cho phép đầu ra chi tiết, bao gồm cả những thông tin như tệp nào đang được sao chép từ mẫu.
  • --name=<application-name> – Tên của thư mục dự án. Nếu bạn bỏ qua, thư mục đầu ra sẽ được sử dụng.
  • <template-name> – Tên của mẫu dùng để tạo dự án mới. Nếu bạn bỏ qua, empty-activity-agp-9 sẽ được dùng.

Ví dụ: android create --dry-run --verbose empty-activity-agp-9

create list

Cách sử dụng: android create list

Nội dung mô tả: Liệt kê tất cả các mẫu có sẵn để tạo một dự án mới.

describe

Cách sử dụng: android describe [--project_dir=<project-directory>]

Nội dung mô tả: Phân tích một dự án Android để tạo siêu dữ liệu mô tả. Lệnh này xác định và xuất các đường dẫn đến tệp JSON mô tả chi tiết cấu trúc của dự án, bao gồm cả các mục tiêu bản dựng và vị trí cấu phần phần mềm đầu ra tương ứng (ví dụ: tệp APK). Thông tin này cho phép các công cụ và lệnh khác xác định vị trí của các cấu phần phần mềm bản dựng một cách hiệu quả.

Lựa chọn:

  • --project_dir – Thư mục dự án cần mô tả. Nếu bỏ qua, thư mục hiện tại sẽ được sử dụng.

Ví dụ: android describe --project_dir=/path/to/your/project

docs

Cách sử dụng:

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

Mô tả: Lệnh android docs là một quy trình gồm 2 bước để truy cập vào Cơ sở kiến thức Android ngay từ CLI. Trước tiên, hãy tìm tài liệu liên quan đến truy vấn của bạn bằng lệnh search. Kết quả tìm kiếm sẽ bao gồm các URL đặc biệt bắt đầu bằng kb://. Sau đó, bạn có thể dùng các URL này với lệnh fetch để xuất các lệnh tài liệu ra thiết bị đầu cuối.

Ví dụ:

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

emulator create

Cách sử dụng: android emulator create [--list-profiles] [--profile=<profile-name>]

Nội dung mô tả: Tạo một thiết bị ảo.

Lựa chọn:

  • --list-profiles – Liệt kê các hồ sơ thiết bị có thể dùng để tạo thiết bị.
  • --profile=<profile-name> – Tạo một thiết bị có hồ sơ được chỉ định. Nếu bạn bỏ qua bước này, hồ sơ medium_phone sẽ được tạo.

emulator list

Cách sử dụng: android emulator list

Nội dung mô tả: Liệt kê các thiết bị ảo hiện có.

emulator start

Cách sử dụng: android emulator start <device-name>

Nội dung mô tả: Khởi chạy thiết bị ảo được chỉ định.

Đối số (bắt buộc):

  • <device-name> – Tên thiết bị để bắt đầu (ví dụ: medium_phone). Sử dụng android emulator list để xem các thiết bị có sẵn.

Ví dụ: android emulator start medium_phone

emulator stop

Cách sử dụng: android emulator stop <device-serial-number>

Mô tả: Dừng thiết bị ảo được chỉ định.

Đối số (bắt buộc):

  • <device-serial-number> – Số sê-ri của thiết bị cần dừng.

Ví dụ: android emulator stop emulator-5554

info

Cách sử dụng: android info

Nội dung mô tả: Hiển thị đường dẫn đến SDK Android mặc định được dùng. Để thay đổi SDK Android được dùng, hãy sử dụng --sdk.

init

Cách sử dụng: android init

Mô tả: Thiết lập môi trường cho các tác nhân bằng cách cài đặt kỹ năng android-cli.

layout

Cách sử dụng: android layout [--pretty] [--output] [--diff]

Nội dung mô tả: Trả về bố cục của giao diện người dùng của ứng dụng Android đang hoạt động (được kết nối thông qua một thiết bị thực hoặc trình mô phỏng) ở định dạng JSON.

Lựa chọn:

  • -p, --pretty – Định dạng đầu ra JSON bằng cách thụt lề và ngắt dòng để con người có thể đọc được.
  • -o, --output – Chỉ định vị trí lưu tệp để lưu cây bố cục. Nếu bị bỏ qua, JSON sẽ được in trực tiếp vào stdout.
  • -d, --diff – Trả về danh sách chỉ gồm các phần tử bố cục đã thay đổi kể từ lần chụp nhanh nội bộ gần đây nhất (lần chạy bố cục gần đây nhất), thay vì toàn bộ cây bố cục.

Ví dụ:: android layout --output=./hierarchy.json

skills add

Kỹ năng Android là những chỉ dẫn đặc biệt được thiết kế để giúp các trợ lý ảo hiểu rõ hơn và thực hiện các mẫu cụ thể tuân theo các phương pháp hay nhất và hướng dẫn về hoạt động phát triển Android. Để tìm hiểu thêm, hãy xem bài viết Giới thiệu về các kỹ năng trên Android.

Cách sử dụng: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

Nội dung mô tả: Cài đặt các kỹ năng Android vào thư mục kỹ năng cho tất cả các tác nhân được phát hiện. Nếu bạn không có thư mục tác nhân hiện có và không chỉ định tác nhân cụ thể, thì các kỹ năng sẽ được cài đặt cho Gemini và Antigravity tại ~/.gemini/antigravity/skills.

Lựa chọn:

  • --all – Thêm tất cả các kỹ năng Android cùng một lúc. Nếu bạn bỏ qua (và không chỉ định --skill), thì chỉ kỹ năng android-cli được cài đặt.
  • --agent – Danh sách tác nhân được phân tách bằng dấu phẩy để cài đặt kỹ năng. Nếu bạn bỏ qua, kỹ năng sẽ được cài đặt cho tất cả các tác nhân được phát hiện.
  • --skill – Tên kỹ năng mà bạn muốn cài đặt. Nếu bạn bỏ qua (và không chỉ định --all), thì chỉ kỹ năng android-cli được cài đặt.

Ví dụ: android skills add --agent='gemini' edge-to-edge

skills find

Cách sử dụng: android skills find <string>

Mô tả: Tìm những kỹ năng khớp với một chuỗi cho trước.

Đối số (bắt buộc):

  • string – Chuỗi khớp với nội dung mô tả kỹ năng.

Ví dụ: android skills find 'performance'

skills list

Cách sử dụng: android skills list [--long]

Nội dung mô tả: Liệt kê các kỹ năng hiện có.

Lựa chọn:

  • --long – Đưa ra thông tin bổ sung cho từng kỹ năng, bao gồm cả nội dung mô tả về kỹ năng và những tác nhân đã cài đặt kỹ năng đó.

skills remove

Cách sử dụng: android skills remove [--agent] --skill=<skill-name>

Mô tả: Xoá một kỹ năng. Nếu bạn không chỉ định các tác nhân cụ thể, thì kỹ năng sẽ bị xoá đối với tất cả các tác nhân.

Đối số (bắt buộc):

  • --skill – Tên của kỹ năng cần xoá.

Lựa chọn:

  • --agent – Danh sách các tác nhân được phân tách bằng dấu phẩy mà bạn muốn xoá kỹ năng. Nếu bạn bỏ qua, kỹ năng này sẽ bị xoá đối với tất cả các nhân viên.

Ví dụ: android skills remove --agent='gemini' --skill=edge-to-edge

screen capture

Cách sử dụng: android screen capture [--output] [--annotate]

Nội dung mô tả: Chụp ảnh màn hình của thiết bị thông minh được kết nối.

Lựa chọn:

  • -o, --output – Chỉ định vị trí tệp để lưu ảnh chụp màn hình. Nếu bị bỏ qua, dữ liệu PNG thô sẽ được in trực tiếp vào stdout.
  • -a, --annotate – Vẽ các hộp giới hạn được gắn nhãn xung quanh tất cả các phần tử trên giao diện người dùng được phát hiện trên hình ảnh, để sử dụng với lệnh resolve.

Ví dụ: android screen capture --output=ui.png

screen resolve

Cách sử dụng: android screen resolve --screenshot=<path> --string=<string>

Nội dung mô tả: Dịch nhãn trực quan từ ảnh chụp màn hình có chú thích (được chụp bằng screen capture) thành toạ độ thực trên màn hình (x, y). Hữu ích cho việc tạo tập lệnh nhấp vào các phần tử mà không cần phải tính toán vị trí của chúng theo cách thủ công.

Cờ:

  • --screenshot – Đường dẫn đến ảnh chụp màn hình có chú thích.
  • --string – Một chuỗi chứa ít nhất một phần giữ chỗ tương ứng với nhãn phần tử trên giao diện người dùng ở định dạng #<number>. Phần #<number> sẽ được thay thế bằng toạ độ màn hình.

Ví dụ:

Nếu nhãn 5 ở toạ độ (500, 1000), thì lệnh

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

trả về đầu ra

input tap 500 1000

sdk install

Cách sử dụng: android sdk install <package[@version]> [--beta] [--canary] [--force]

Nội dung mô tả: Cài đặt(các) gói SDK được chỉ định.

Đối số (bắt buộc):

  • package[@version] – Danh sách các gói cần cài đặt, được phân tách bằng dấu cách. Nếu bạn không chỉ định phiên bản, thì phiên bản mới nhất của gói trong kênh (theo mặc định là kênh ổn định) sẽ được cài đặt.

Lựa chọn:

  • --beta – Bao gồm các gói beta.
  • --canary – Bao gồm các gói thử nghiệm.
  • --force – Buộc hạ cấp xuống phiên bản cũ hơn.

Ví dụ:

  • android sdk install platforms/android-34 build-tools/34.0.0 – Cài đặt các phiên bản mới nhất của gói Nền tảng SDK Android 34 và Bộ công cụ bản dựng SDK 34.0.0 từ kênh ổn định.
  • android sdk install platforms/android-34@2 – Cài đặt phiên bản 2 của gói Nền tảng SDK Android 34.
  • android sdk install --canary system-images/android-35/google_apis/x86_6 – Cài đặt phiên bản mới nhất của hình ảnh hệ thống Android 35 từ kênh canary.
  • android sdk install --force platforms/android-33@1 – Quay lại phiên bản 1 của gói Nền tảng SDK Android 33 từ Kênh ổn định.

sdk list

Cách sử dụng: android sdk list <package-pattern>

Nội dung mô tả: Liệt kê các gói SDK đã cài đặt và có sẵn.

Đối số (bắt buộc):

  • <package-pattern> – Lọc các gói theo mẫu. Hỗ trợ biểu thức chính quy.

Lựa chọn:

  • --all – Hiện tất cả các gói đã cài đặt và có sẵn.
  • --all-versions – Hiện tất cả phiên bản cho từng gói.
  • --beta – Bao gồm các gói beta.
  • --canary – Bao gồm các gói thử nghiệm.

sdk remove

Cách sử dụng: android sdk remove <package-name>

Nội dung mô tả: Xoá một gói khỏi SDK.

Đối số (bắt buộc):

  • <package-name> – Tên của gói cần xoá.

Ví dụ: android sdk remove build-tools/36.1.0

run

Cách sử dụng: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

Nội dung mô tả: Triển khai một ứng dụng Android cho một thiết bị thông minh hoặc trình mô phỏng đã kết nối. Thao tác này không thực hiện bất kỳ bước tạo bản dựng nào; bạn phải cung cấp(các) đường dẫn đến tệp APK mà bạn muốn cài đặt.

Đối số (bắt buộc):

  • --apks – Danh sách đường dẫn được phân tách bằng dấu phẩy đến(các) tệp APK mà bạn muốn cài đặt. Đường dẫn này tương ứng với vị trí hiện tại của bạn trong hệ thống tệp.

Lựa chọn:

  • --activity – Tên của hoạt động sẽ khởi chạy sau khi APK được cài đặt. Nếu có nhiều hoạt động, bạn phải chỉ định một hoạt động để khởi chạy ban đầu.
  • --debug – Triển khai ứng dụng ở chế độ gỡ lỗi. Sau khi chạy ứng dụng ở chế độ gỡ lỗi, bạn phải kết nối trình gỡ lỗi từ một IDE (chẳng hạn như Android Studio) hoặc một công cụ dòng lệnh để bắt đầu gỡ lỗi.
  • --device – Số sê-ri của thiết bị mục tiêu hoặc trình mô phỏng. Chỉ cần thiết nếu có nhiều thiết bị được kết nối. Để tìm số sê-ri của thiết bị, hãy chạy adb devices.
  • --type – Loại thành phần để bắt đầu. Hãy sử dụng phương thức này nếu bạn muốn bắt đầu một dịch vụ nền ngay lập tức thay vì một hoạt động trên giao diện người dùng. Các loại được hỗ trợ:
    • ACTIVITY
    • WATCH_FACE
    • TILE
    • COMPLICATION
    • DECLARATIVE_WATCH_FACE

Ví dụ:

  • android run --apks=app/build/outputs/apk/debug/app-debug.apk – Triển khai một APK duy nhất cho thiết bị mặc định.
  • android run --apks=base.apk,density-hdpi.apk,lang-en.apk – Triển khai nhiều APK cho thiết bị mặc định.
  • android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService – Kiểm thử một dịch vụ không có hoạt động.
  • android run --apks=app-debug.apk --device=emulator-5554 – Triển khai APK cho một thiết bị cụ thể.

sdk update

Cách sử dụng: android sdk update [--beta] [--canary] [<package-name>]

Nội dung mô tả: Cập nhật một hoặc tất cả các gói lên phiên bản mới nhất trong kênh (theo mặc định là kênh ổn định). Nếu bạn không chỉ định gói nào, tất cả các gói sẽ được cập nhật.

Lựa chọn:

  • <package-name> – Tên của gói cần cập nhật.
  • --beta – Bao gồm các gói beta.
  • --canary – Bao gồm các gói thử nghiệm.
  • --force – Buộc hạ cấp xuống phiên bản cũ hơn.

Ví dụ:

  • android sdk update – Kiểm tra và cài đặt bản cập nhật cho mọi thứ trong SDK.
  • android sdk update build-tools/34.0.0 – Cập nhật gói Công cụ xây dựng SDK Android 34.0.0 lên phiên bản mới nhất trong kênh ổn định.
  • android sdk update --canary platforms/android-35 – Cập nhật gói Nền tảng SDK Android 35 lên phiên bản mới nhất trong kênh canary.

update

Cách sử dụng: android update

Nội dung mô tả: Cập nhật CLI Android.

-V, --version

Nội dung mô tả: Hiện phiên bản hiện tại của Android CLI.