Przegląd interfejsu wiersza poleceń Androida

Interfejs wiersza poleceń Androida to interfejs wiersza poleceń, który umożliwia łatwiejsze i wydajniejsze tworzenie aplikacji na Androida za pomocą dowolnego narzędzia. Ujednolica podstawowe kompetencje programistyczne w przypadku przepływów pracy opartych na agentach, zapewniając punkt wejścia do oficjalnych narzędzi, umiejętności i wiedzy potrzebnych do skuteczniejszego programowania. Może też usprawnić CI, konserwację i inne skryptowe automatyzacje w coraz bardziej rozproszonym środowisku programowania na Androida.

Na przykład agent lub skrypt może używać interfejsu wiersza poleceń do automatyzowania konfiguracji środowiska, tworzenia nowych projektów na podstawie szablonów i zarządzania urządzeniami wirtualnymi bezpośrednio z terminala. Zapewnia też agentom dostęp do umiejętności związanych z Androidem i specjalistycznej bazy wiedzy o Androidzie, aby mieć pewność, że w Twoich projektach stosowane są wzorce i sprawdzone metody zalecane w przypadku Androida.

Instalowanie interfejsu wiersza poleceń Androida

Aby zainstalować interfejs wiersza poleceń Androida, wykonaj te czynności:

1. Pobierz interfejs wiersza poleceń Androida.

2. Aby mieć pewność, że używasz najnowszej wersji, zaktualizuj interfejs wiersza poleceń Androida:

   android update
   

Aby sprawdzić, czy interfejs wiersza poleceń Androida jest już zainstalowany na Twoim komputerze, uruchom polecenie which android lub command -v android. Jeśli zwróci ścieżkę, oznacza to, że jest zainstalowany.

Konfiguracja dla agentów

Aby pomóc agentom w zrozumieniu i używaniu interfejsu wiersza poleceń Androida, uruchom polecenie init, aby zainstalować umiejętność android-cli:

android init

Zebrane dane

Interfejs wiersza poleceń Androida zbiera dane o podstawowym korzystaniu z narzędzia. Oto dane, które zbieramy:

• Wywołania polecenia android i jego poleceń podrzędnych, np. android run i android create.
• Nazwy użytych argumentów lub opcji niepozycyjnych, np. --sdk lub --version.
• Argumenty pozycyjne i wartości flag, które są mapowane na stały, predefiniowany zestaw opcji systemowych zarządzanych przez interfejs wiersza poleceń Androida. Zbieramy na przykład nazwy szablonów emulatora, takie jak medium_phone i large_desktop, oraz nazwy agentów, takie jak GEMINI, CLAUDE i CODEX.
• ślady stosu i komunikaty o wyjątkach, w których informacje umożliwiające identyfikację są anonimizowane przed zebraniem, aby zapewnić prywatność;

Oto kilka przykładów danych, których nie zbieramy:

• Nie zbieramy odpowiedzi interfejsu wiersza poleceń po uruchomieniu polecenia.
• Nie zbieramy danych wejściowych utworzonych przez użytkownika ani identyfikatorów zewnętrznych przekazywanych do interfejsu wiersza poleceń, takich jak konkretne współrzędne Maven, lokalne ścieżki do plików czy niestandardowe nazwy projektów. Jeśli na przykład zostanie wykonane polecenie android create --name=com.company.internal.app, zarejestrujemy, że polecenie android create zostało wykonane z argumentem --name, ale nie zapiszemy wartości com.company.internal.app.

Znane problemy

• Polecenie android emulator w systemie Windows jest obecnie wyłączone.
• Pobieranie interfejsu wiersza poleceń Androida z Windows PowerShell nie jest obecnie obsługiwane.

Jeśli napotkasz jakieś problemy lub chcesz podzielić się opinią, zgłoś błąd.

Konfigurowanie interfejsu wiersza poleceń Androida

Utwórz plik .androidrc, aby automatycznie stosować flagi i opcje za każdym razem, gdy wywołujesz interfejs wiersza poleceń Androida. Zapisz plik w tej lokalizacji, w zależności od systemu operacyjnego:

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

Dodaj flagi, które chcesz automatycznie zastosować do pliku (po jednej w wierszu).

Jeśli na przykład chcesz, aby interfejs wiersza poleceń Androida domyślnie używał określonego pakietu Android SDK, dodaj do pliku flagę --sdk:

--sdk=<path-to-sdk>

Opcje globalne

Są to opcjonalne flagi, których możesz używać z innymi poleceniami interfejsu wiersza poleceń Androida.

-h, --help

Użycie: android <command> -h

Opis: wyświetla instrukcję obsługi narzędzia lub konkretnego polecenia.

Przykłady:

• android -h
• android create -h

--sdk

Użycie: android --sdk=<path-to-sdk> <command>

Opis: ścieżka do pakietu Android SDK, którego chcesz użyć w następującym poleceniu. Możesz użyć ustawienia --sdk, aby tymczasowo zastąpić domyślny pakiet Android SDK, zamiast za każdym razem zmieniać globalne zmienne środowiskowe. Aby sprawdzić, którego pakietu SDK na Androida używasz domyślnie, uruchom polecenie android info.

Przykład: android --sdk=<path/to/sdk> sdk list

Polecenia

W tej sekcji znajdziesz listę wszystkich poleceń interfejsu wiersza poleceń Androida wraz z opisem ich działania. Wszystkie te polecenia powinny być poprzedzone znakiem android, np. android create, android run itd. Opcjonalne modyfikatory są ujęte w nawiasy kwadratowe [], a argumenty obowiązkowe nie.

create

Użycie: android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]

Opis: inicjowanie nowego projektu na podstawie szablonu. Aby wyświetlić opcje szablonu, uruchom polecenie android create -h.

Argumenty (obowiązkowe):

• -o, --output – ścieżka katalogu projektu docelowego.

Opcje:

• --dry-run – symuluje cały proces tworzenia projektu bez zapisywania plików. Możesz na przykład przeprowadzić test, aby sprawdzić, jak działają różne szablony, zanim wybierzesz jeden z nich.
• --verbose – włącza szczegółowe dane wyjściowe, w tym informacje o tym, które pliki są kopiowane z szablonu.
• --name=<application-name> – nazwa katalogu projektu. Jeśli ten parametr zostanie pominięty, użyty zostanie katalog wyjściowy.
• <template-name> – nazwa szablonu, na podstawie którego ma zostać utworzony nowy projekt. Jeśli zostanie pominięty, używana jest wartość empty-activity-agp-9.

Przykład: android create --dry-run --verbose empty-activity-agp-9

create list

Użycie: android create list

Opis: wyświetla listę wszystkich dostępnych szablonów, na podstawie których można utworzyć nowy projekt.

describe

Użycie: android describe [--project_dir=<project-directory>]

Opis: analizuje projekt aplikacji na Androida, aby wygenerować opisowe metadane. To polecenie identyfikuje i wyświetla ścieżki do plików JSON, które zawierają szczegółowe informacje o strukturze projektu, w tym o elementach docelowych kompilacji i odpowiadających im lokalizacjach artefaktów wyjściowych (np. plików APK). Te informacje umożliwiają innym narzędziom i poleceniom sprawne znajdowanie artefaktów kompilacji.

Opcje:

• --project_dir – katalog projektu do opisania. Jeśli zostanie pominięty, używany jest bieżący katalog.

Przykład: android describe --project_dir=/path/to/your/project

docs

Użycie:

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

Opis: polecenie android docs to dwuetapowy proces uzyskiwania dostępu do bazy wiedzy o Androidzie bezpośrednio z interfejsu wiersza poleceń. Najpierw wyszukaj dokumentację związaną z Twoim zapytaniem, używając polecenia search. Wyniki wyszukiwania będą zawierać specjalne adresy URL zaczynające się od kb://, których możesz następnie użyć z poleceniem fetch, aby wyświetlić w terminalu polecenia dokumentacji.

Przykłady:

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

emulator create

Użycie: android emulator create [--list-profiles] [--profile=<profile-name>]

Opis: tworzenie urządzenia wirtualnego.

Opcje:

• --list-profiles – wyświetla listę profili urządzeń, których można użyć do utworzenia urządzenia.
• --profile=<profile-name> – tworzy urządzenie z określonym profilem. Jeśli ten parametr zostanie pominięty, zostanie utworzony profil medium_phone.

emulator list

Użycie: android emulator list

Opis: lista dostępnych urządzeń wirtualnych.

emulator start

Użycie: android emulator start <device-name>

Opis: uruchamia określone urządzenie wirtualne.

Argumenty (obowiązkowe):

• <device-name> – nazwa urządzenia, na którym ma się rozpocząć odtwarzanie (np. medium_phone). Aby zobaczyć dostępne urządzenia, użyj android emulator list.

Przykład: android emulator start medium_phone

emulator stop

Użycie: android emulator stop <device-serial-number>

Opis: zatrzymuje określone urządzenie wirtualne.

Argumenty (obowiązkowe):

• <device-serial-number> – numer seryjny urządzenia, które ma zostać zatrzymane.

Przykład: android emulator stop emulator-5554

info

Użycie: android info

Opis: wyświetla ścieżkę do używanego domyślnego pakietu Android SDK. Aby zmienić używany pakiet Android SDK, użyj --sdk.

init

Użycie: android init

Opis: skonfiguruj środowisko dla agentów, instalując umiejętność android-cli.

layout

Użycie: android layout [--pretty] [--output] [--diff]

Opis: zwraca układ interfejsu aktywnej aplikacji na Androida (połączonej z urządzeniem fizycznym lub emulatorem) w formacie JSON.

Opcje:

• -p, --pretty – formatuje wyjście JSON z wcięciami i znakami nowego wiersza, aby było czytelne dla człowieka.
• -o, --output – określa lokalizację pliku, w której ma zostać zapisane drzewo układu. Jeśli ten parametr zostanie pominięty, kod JSON zostanie wydrukowany bezpośrednio na standardowe wyjście.
• -d, --diff – zwraca listę tylko tych elementów układu, które uległy zmianie od czasu utworzenia ostatniego wewnętrznego zrzutu (ostatniego uruchomienia układu), zamiast pełnego drzewa układu.

Przykład: android layout --output=./hierarchy.json

skills add

Umiejętności Androida to specjalne instrukcje, które pomagają agentom lepiej rozumieć i wykonywać określone wzorce zgodne ze sprawdzonymi metodami i wskazówkami dotyczącymi tworzenia aplikacji na Androida. Więcej informacji znajdziesz w artykule Wprowadzenie do umiejętności związanych z Androidem.

Użycie: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

Opis: zainstaluj umiejętności Androida w katalogach umiejętności wszystkich wykrytych agentów. Jeśli nie masz żadnych katalogów agentów i nie określisz konkretnych agentów, umiejętności zostaną zainstalowane w przypadku Gemini i Antigravity w lokalizacji ~/.gemini/antigravity/skills.

Opcje:

• --all – dodaj wszystkie umiejętności związane z Androidem naraz. Jeśli ten parametr zostanie pominięty (a parametr --skill nie zostanie określony), zainstalowana zostanie tylko umiejętność android-cli.
• --agent – lista agentów rozdzielona przecinkami, dla których ma zostać zainstalowana umiejętność. Jeśli ten parametr zostanie pominięty, umiejętność zostanie zainstalowana dla wszystkich wykrytych agentów.
• --skill – nazwa umiejętności, którą chcesz zainstalować. Jeśli ten parametr zostanie pominięty (a parametr --all nie zostanie określony), zainstalowana zostanie tylko umiejętność android-cli.

Przykład: android skills add --agent='gemini' edge-to-edge

skills find

Użycie: android skills find <string>

Opis: znajdź umiejętności pasujące do danego ciągu znaków.

Argumenty (obowiązkowe):

• string – ciąg znaków pasujący do opisu umiejętności.

Przykład: android skills find 'performance'

skills list

Użycie: android skills list [--long]

Opis: lista dostępnych umiejętności.

Opcje:

• --long – wyświetla dodatkowe informacje o każdej umiejętności, w tym jej opis i informacje o tym, na których agentach jest już zainstalowana.

skills remove

Użycie: android skills remove [--agent] --skill=<skill-name>

Opis: usuwanie umiejętności. Jeśli nie określisz konkretnych agentów, umiejętność zostanie usunięta w przypadku wszystkich agentów.

Argumenty (obowiązkowe):

• --skill – nazwa umiejętności do usunięcia.

Opcje:

• --agent – lista agentów rozdzielona przecinkami, z których umiejętność ma zostać usunięta. Jeśli zostanie pominięty, umiejętność zostanie usunięta u wszystkich agentów.

Przykład: android skills remove --agent='gemini' --skill=edge-to-edge

screen capture

Użycie: android screen capture [--output] [--annotate]

Opis: robi zrzut ekranu połączonego urządzenia.

Opcje:

• -o, --output – określa lokalizację pliku, w której ma zostać zapisany zrzut ekranu. Jeśli ten argument zostanie pominięty, nieprzetworzone dane PNG zostaną wydrukowane bezpośrednio na standardowe wyjście.
• -a, --annotate – rysuje oznaczone etykietami ramki ograniczające wokół wszystkich elementów interfejsu wykrytych na obrazie. Używaj go z poleceniem resolve.

Przykład: android screen capture --output=ui.png

screen resolve

Użycie: android screen resolve --screenshot=<path> --string=<string>

Opis: Tłumaczy etykiety wizualne z adnotowanego zrzutu ekranu,screen capture na rzeczywiste współrzędne ekranu (x, y). Przydatne w przypadku skryptów klikających elementy bez konieczności ręcznego obliczania ich pozycji.

Flagi:

• --screenshot – ścieżka do zrzutu ekranu z adnotacjami.
• --string – ciąg znaków, który zawiera co najmniej 1 symbol zastępczy odpowiadający etykiecie elementu interfejsu w formacie #<number>. Część #<number> zostanie zastąpiona współrzędnymi ekranu.

Przykład:

Jeśli etykieta 5 znajduje się we współrzędnych (500, 1000), polecenie

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

zwraca dane wyjściowe.

input tap 500 1000

sdk install

Użycie: android sdk install <package[@version]> [--beta] [--canary] [--force]

Opis: instaluje określone pakiety SDK.

Argumenty (obowiązkowe):

• package[@version] – lista pakietów do zainstalowania rozdzielona spacjami. Jeśli nie podasz wersji, zostanie zainstalowana najnowsza wersja pakietu na kanale (domyślnie na kanale stabilnym).

Opcje:

• --beta – uwzględnia pakiety w wersji beta.
• --canary – uwzględnia pakiety Canary.
• --force – wymusza przejście na starszą wersję.

Przykłady:

• android sdk install platforms/android-34 build-tools/34.0.0 – zainstaluj najnowsze wersje pakietów Android SDK Platform 34 i SDK Built Tools 34.0.0 z kanału stabilnego.
• android sdk install platforms/android-34@2 – zainstaluj wersję 2 pakietu Android SDK Platform 34.
• android sdk install --canary system-images/android-35/google_apis/x86_6 - Zainstaluj najnowszą wersję obrazu systemu Android 35 z kanału canary.
• android sdk install --force platforms/android-33@1 – przywróć wersję 1 pakietu Android SDK Platform 33 z kanału stabilnego.

sdk list

Użycie: android sdk list <package-pattern>

Opis: lista zainstalowanych i dostępnych pakietów SDK.

Argumenty (obowiązkowe):

• <package-pattern> – filtruj pakiety według wzorca. Obsługuje wyrażenia regularne.

Opcje:

• --all – wyświetla wszystkie zainstalowane i dostępne pakiety.
• --all-versions – wyświetla wszystkie wersje każdego pakietu.
• --beta – uwzględnia pakiety w wersji beta.
• --canary – uwzględnia pakiety Canary.

sdk remove

Użycie: android sdk remove <package-name>

Opis: usuń pakiet z pakietu SDK.

Argumenty (obowiązkowe):

• <package-name> – nazwa pakietu do usunięcia.

Przykład: android sdk remove build-tools/36.1.0

run

Użycie: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

Opis: wdrażanie aplikacji na Androida na podłączonym urządzeniu lub emulatorze. Nie wykonuje żadnych kroków kompilacji. Musisz podać ścieżki do plików APK, które chcesz zainstalować.

Argumenty (obowiązkowe):

• --apks – lista ścieżek do plików APK rozdzielona przecinkami, które chcesz zainstalować. Ścieżka jest względna w stosunku do bieżącego miejsca w systemie plików.

Opcje:

• --activity – nazwa aktywności, która ma zostać uruchomiona po zainstalowaniu pliku APK. Jeśli jest wiele aktywności, musisz określić, która z nich ma zostać uruchomiona jako pierwsza.
• --debug – wdraża aplikację w trybie debugowania. Po uruchomieniu aplikacji w trybie debugowania musisz połączyć debugger ze środowiskiem IDE, np. Androidem Studio, lub narzędziem wiersza poleceń, aby rozpocząć debugowanie.
• --device – numer seryjny urządzenia docelowego lub emulatora. Wymagane tylko wtedy, gdy połączonych jest kilka urządzeń. Aby znaleźć numery seryjne urządzeń, uruchom polecenie adb devices.
• --type – typ komponentu, od którego chcesz zacząć. Użyj tej opcji, jeśli chcesz uruchomić usługę w tle bezpośrednio zamiast działania interfejsu. Obsługiwane typy:
  • ACTIVITY
  • WATCH_FACE
  • TILE
  • COMPLICATION
  • DECLARATIVE_WATCH_FACE

Przykłady:

• android run --apks=app/build/outputs/apk/debug/app-debug.apk – wdraża pojedynczy pakiet APK na urządzeniu domyślnym.
• android run --apks=base.apk,density-hdpi.apk,lang-en.apk – wdraża wiele plików APK na urządzeniu domyślnym.
• android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService – przetestuj usługę bez aktywności.
• android run --apks=app-debug.apk --device=emulator-5554 – wdraża plik APK na konkretnym urządzeniu.

sdk update

Użycie: android sdk update [--beta] [--canary] [<package-name>]

Opis: zaktualizuj jeden lub wszystkie pakiety do najnowszej wersji na kanale (domyślnie na kanale stabilnym). Jeśli nie określisz pakietu, wszystkie pakiety zostaną zaktualizowane.

Opcje:

• <package-name> – nazwa pakietu do zaktualizowania.
• --beta – uwzględnia pakiety w wersji beta.
• --canary – uwzględnia pakiety Canary.
• --force – wymusza przejście na starszą wersję.

Przykłady:

• android sdk update – sprawdź i zainstaluj aktualizacje wszystkich elementów pakietu SDK.
• android sdk update build-tools/34.0.0 – zaktualizuj pakiet Android SDK Build-Tools 34.0.0 do najnowszej wersji w kanale stabilnym.
• android sdk update --canary platforms/android-35 – zaktualizuj pakiet Android SDK Platforms 35 do najnowszej wersji w kanale Canary.

update

Użycie: android update

Opis: aktualizacja interfejsu wiersza poleceń Androida.

-V, --version

Opis: wyświetla bieżącą wersję interfejsu wiersza poleceń Androida.