Обзор интерфейса командной строки Android

Android CLI — это интерфейс командной строки, который позволяет проще и эффективнее собирать приложения для Android, используя любой инструмент по вашему выбору. Он стандартизирует основные компетенции разработчиков для рабочих процессов, ориентированных на агенты, предоставляя точку входа к официальным инструментам, навыкам и знаниям, необходимым для более эффективной разработки. Он также может оптимизировать CI, сопровождение и любую другую автоматизацию на основе скриптов в условиях все более распределенной разработки Android.

Например, агент или скрипт могут использовать интерфейс командной строки для выполнения таких задач, как следующие:

• Автоматизация настройки среды
• Создавайте новые проекты на основе шаблонов.
• Управляйте виртуальными устройствами непосредственно с вашего терминала.
• Протестируйте свое приложение с помощью Journeys.

Android CLI также предоставляет вашим агентам доступ к навыкам Android и специализированной базе знаний Android , что помогает обеспечить применение в ваших проектах рекомендуемых Android шаблонов и передовых методов.

Установите Android CLI.

Для установки Android CLI выполните следующие действия:

1. Скачайте Android CLI .

2. Чтобы убедиться, что вы используете последнюю версию, обновите Android CLI:

   android update
   

   Совет: Регулярно android update , чтобы быть в курсе последних функций.

Чтобы проверить, установлен ли Android CLI на вашем компьютере, выполните команду which android или command -v android : если она вернет путь, значит, он установлен.

Настройка для агентов

Чтобы помочь агентам понять и использовать Android CLI, запустите init для установки навыка android-cli :

android init

Собранные данные

Android CLI собирает данные об основном использовании инструмента. Вот данные, которые мы собираем:

• Вызовы команды android и её подкоманд, например android run и android create .
• Названия используемых непозиционных аргументов или параметров, например --sdk или --version .
• Позиционные аргументы и значения флагов, которые сопоставляются с фиксированным, предопределенным набором системных параметров, управляемых Android CLI. Например, мы собираем имена шаблонов эмулятора, такие как medium_phone и large_desktop , и имена агентов, такие как GEMINI , CLAUDE или CODEX .
• Трассировка стека и сообщения об исключениях, в которых идентифицирующая информация анонимизируется перед сбором для обеспечения конфиденциальности.

Вот несколько примеров данных, которые мы не собираем:

• Мы не собираем ответы от командной строки при выполнении команды.
• Мы не собираем пользовательские входные данные или внешние идентификаторы, передаваемые в CLI, такие как конкретные координаты Maven, пути к локальным файлам или пользовательские имена проектов. Например, если выполняется команда android create --name=com.company.internal.app , мы записываем, что android create была выполнена с использованием аргумента --name но не сохраняем значение com.company.internal.app .

Известные проблемы

• Команда android emulator для Windows в настоящее время отключена.
• Загрузка интерфейса командной строки Android из Windows PowerShell в настоящее время не поддерживается.

Если у вас возникнут какие-либо проблемы или вы захотите оставить отзыв, пожалуйста, сообщите об ошибке .

Настройка Android CLI

Создайте файл .androidrc , чтобы автоматически применять флаги и параметры при каждом вызове Android CLI. Сохраните файл в указанном ниже месте (в зависимости от вашей операционной системы):

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

Добавьте в файл флаги, которые вы хотите применять автоматически, по одному на строку.

Например, чтобы Android CLI всегда по умолчанию использовал определенный Android SDK, добавьте флаг --sdk в свой файл:

--sdk=<path-to-sdk>

Глобальные опции

Это необязательные флаги, которые можно использовать с другими командами командной строки Android.

-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 непосредственно из командной строки. Сначала выполните поиск документации, связанной с вашим запросом, используя команду search . Результаты поиска будут включать специальные URL-адреса, начинающиеся с 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]

Описание: Возвращает макет пользовательского интерфейса активного приложения Android (подключенного через физическое устройство или эмулятор) в формате JSON.

Параметры:

• -p, --pretty - Форматирует вывод JSON с отступами и переносами строк для удобства чтения человеком.
• -o, --output - Указывает местоположение файла для сохранения дерева компоновки. Если не указано, JSON-данные выводятся непосредственно в стандартный поток вывода.
• -d, --diff - Возвращает список только тех элементов макета, которые изменились с момента создания последнего внутреннего снимка (последнего запуска функции компоновки), вместо полного дерева макета.

Пример: ` android layout --output=./hierarchy.json

run

Использование: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

Описание: Развертывание Android-приложения на подключенном устройстве или эмуляторе. Сборка не выполняется; необходимо указать пути к APK-файлам, которые вы хотите установить.

Аргументы (обязательные):

• --apks - Список путей к APK-файлам, которые вы хотите установить, разделенных запятыми. Путь указывается относительно текущего местоположения в файловой системе.

Параметры:

• --activity - Название активности , которая будет запущена после установки APK-файла. Если активностей несколько, необходимо указать одну для первоначального запуска.
• --debug - Развертывает приложение в режиме отладки . После запуска приложения в режиме отладки необходимо подключить отладчик из IDE, например Android Studio, или из инструмента командной строки, чтобы начать отладку.
• --device - Серийный номер целевого устройства или эмулятора. Требуется только при подключении нескольких устройств. Чтобы узнать серийные номера устройств, выполните команду adb devices .
• --type - Тип компонента для запуска. Используйте это, если хотите запустить фоновую службу напрямую, а не активность пользовательского интерфейса. Поддерживаемые типы:
  • 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-файл на конкретном устройстве.

screen capture

Использование: android screen capture [--output] [--annotate]

Описание: Делает снимок экрана подключенного устройства.

Параметры:

• -o, --output - Указывает местоположение файла для сохранения снимка экрана. Если этот параметр опущен, необработанные данные PNG будут выведены непосредственно в стандартный поток вывода.
• -a, --annotate - Рисует ограничивающие рамки с подписями вокруг всех элементов пользовательского интерфейса, обнаруженных на изображении, для использования с командой resolve .

Пример: android screen capture --output=ui.png

screen resolve

Использование: android screen resolve --screenshot=<path> --string=<string>

Описание: Преобразует визуальные метки с аннотированного скриншота, полученного с помощью screen capture , в фактические координаты экрана (x, y). Полезно для создания скриптов для обработки кликов по элементам без необходимости вручную вычислять их положение.

Флаги:

• --screenshot - Путь к скриншоту с аннотацией.
• --string - Строка, содержащая как минимум один заполнитель, соответствующий метке элемента пользовательского интерфейса в формате #<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 - Включить бета-версии пакетов.
• --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 - Установка версии 2 пакета Android SDK Platform 34.
• android sdk install --canary system-images/android-35/google_apis/x86_6 - Установите последнюю версию образа системы Android 35 из канала canary.
• android sdk install --force platforms/android-33@1 - Возврат к версии 1 пакета Android SDK Platform 33 из стабильного канала.

sdk list

Использование: android sdk list <package-pattern>

Описание: Список установленных и доступных пакетов SDK.

Аргументы (обязательные):

• <package-pattern> - Фильтрация пакетов по шаблону. Поддерживает регулярные выражения.

Параметры:

• --all - Показать все установленные и доступные пакеты.
• --all-versions - Показать все версии для каждого пакета.
• --beta - Включить бета-версии пакетов.
• --canary - Включить тестовые пакеты.

sdk remove

Использование: android sdk remove <package-name>

Описание: Удаление пакета из SDK.

Аргументы (обязательные):

• <package-name> - Название пакета для удаления.

Пример: android sdk remove build-tools/36.1.0

sdk update

Использование: android sdk update [--beta] [--canary] [<package-name>]

Описание: Обновляет один или все пакеты до последней версии в канале (по умолчанию — стабильный канал). Если вы не укажете пакет, будут обновлены все пакеты.

Параметры:

• <package-name> - Название пакета для обновления.
• --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.

skills add

Навыки Android — это специальные инструкции, разработанные для того, чтобы помочь агентам лучше понимать и выполнять определенные шаблоны, соответствующие передовым методам и рекомендациям по разработке под Android. Для получения дополнительной информации см. раздел «Введение в навыки Android» .

Использование: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

Описание: Устанавливает навыки Android в каталоги навыков для всех обнаруженных агентов. Если у вас нет существующих каталогов агентов и вы не указываете конкретных агентов, навыки будут установлены для Gemini и Antigravity в ~/.gemini/antigravity/skills . Если у вас уже установлены навыки Android, skills add обновит навыки до последней версии.

Примечание: Если вы изменяете навык, вам следует переименовать его, иначе он будет перезаписан при обновлении с помощью команды skills add .

Параметры:

• --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

studio check

Предварительный просмотр: Для использования команд studio необходимо открыть проект в Android Studio Quail 2 Canary 1 или более поздней версии, а также включить и авторизовать Gemini в Android Studio.

Команды studio позволяют вам или вашему агенту ИИ взаимодействовать с активными экземплярами Android Studio. Подключившись к запущенному экземпляру, вы можете использовать возможности IDE для анализа файлов, поиска объявлений и использования символов, отображения предварительного просмотра Compose и проверки версий зависимостей.

Использование: android studio check

Описание: Проверяет состояние запущенных экземпляров Android Studio и выводит список открытых проектов. Выполните эту команду сначала, чтобы проверить соединение между CLI и IDE, а также выбрать PID и проект, к которому вы хотите подключиться, если их несколько.

Пример вывода:

При подключении в выводе отображается PID запущенного экземпляра Android Studio, его версия и статус открытых проектов:

pid: 32942
version: Android Studio Quail
Projects:
    READY     MyApplication /Users/username/AndroidStudioProjects/MyApplication

studio analyze-file

Использование: android studio analyze-file [--pid=<pid>] [--project=<project>] <path>

Описание: Анализирует файл в Android Studio на наличие ошибок, предупреждений и линтинговых ошибок, используя встроенный в IDE механизм проверки кода.

Аргументы (обязательные):

• <path> - Путь к файлу Kotlin или Java для анализа.

Параметры:

• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Название проекта, открытого в Android Studio для запроса, если их несколько. Если вы запускаете команду analyze-file из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio analyze-file \
  --project=MyApplication \
  /Users/username/AndroidStudioProjects/MyApplication/app/src/main/java/com/example/myapp/MainActivity.kt

studio find-declaration

Использование: android studio find-declaration [--short] [--context-file=<path>] [--pid=<pid>] [--project=<project>] <symbol>

Описание: Находит точное место объявления символа (класса, метода, переменной, поля, константы или ресурса Android) в проекте с помощью семантического разрешения.

Аргументы (обязательные):

• <symbol> - Название кодового символа, для которого нужно найти объявление.

Параметры:

• --context-file=<path> - Необязательный путь к файлу, содержащему ссылку на символ. Предоставление файла контекста помогает разрешить неоднозначные или перегруженные символы, предоставляя импорты и область видимости.
• --short - Упрощает вывод, отображая только местоположение файла и строку совпадения.
• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Название проекта, открытого в Android Studio для поиска, если их несколько. Если вы запускаете команду find-declaration из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio find-declaration --short HotelDetailScreen

studio find-usages

Использование: android studio find-usages [--short] [--pid=<pid>] [--project=<project>] <symbol>

Описание: Находит все упоминания и случаи использования символа во всем проекте с помощью семантического анализа.

Аргументы (обязательные):

• <symbol> - Название символа, для которого необходимо найти примеры использования.

Параметры:

• --short - Упрощает вывод, отображая только местоположения найденных файлов.
• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Название проекта, открытого в Android Studio для запроса, если их несколько. Если вы запускаете эту команду из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio find-usages --short HotelDetailScreen

studio open-file

Использование: android studio open-file [--pid=<pid>] [--project=<project>] <path>

Описание: Открывает файл непосредственно в активном окне редактора Android Studio.

Аргументы (обязательные):

• <path> - Путь к открываемому файлу. Может быть указан относительно корневого каталога проекта или в виде абсолютного пути.

Параметры:

• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Имя проекта, открытого в Android Studio для запроса, если их несколько. Если вы запускаете команду open-file из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio open-file app/src/main/java/com/example/myapp/ui/DetailScreen.kt

studio render-compose-preview

Использование: android studio render-compose-preview [--print-semantics] [--output-image-file=<filename>] [--pid=<pid>] [--project=<project>] <path> <composable>

Описание: Отображает предварительный просмотр пользовательского интерфейса Jetpack Compose и, при необходимости, возвращает дерево семантики его компоновки. Это полезно для визуального тестирования или для обеспечения работы агентов ИИ с макетом пользовательского интерфейса.

Аргументы (обязательные):

• <path> - Путь к файлу Kotlin, содержащему предварительный просмотр Compose.
• <composable> - Название составной функции предварительного просмотра (отмечена как @Preview ).

Параметры:

• --output-image-file=<filename> - Указывает имя файла, в который будет записано полученное изображение PNG. Если это имя опущено, будет создан временный файл.
• --print-semantics - Если значение равно true, выводит дерево семантики доступности отрендеренного предварительного просмотра Compose в формате JSON. Это позволяет агентам анализировать структуру и интерактивные элементы пользовательского интерфейса.
• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Название проекта, открытого в Android Studio для запроса, если их несколько. Если вы запускаете команду render-compose-preview из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio render-compose-preview \
  --output-image-file=preview_hotel.png \
  --print-semantics \
  app/src/main/java/com/example/myapp/ui/DetailScreen.kt \
  HotelDetailScreenPreview

studio version-lookup

Использование: android studio version-lookup [--pid=<pid>] [--project=<project>] <artifacts...>

Описание: Программа ищет последние доступные версии распространенных зависимостей, платформ Android и инструментов SDK в таких репозиториях, как Google Maven. Это предоставляет программную альтернативу ручной проверке версий зависимостей.

Аргументы (обязательные):

• <artifacts...> — Список идентификаторов, разделённых пробелами. Вы можете запросить несколько артефактов в одной команде. Поддерживаемые идентификаторы:
  • Библиотеки Maven: обозначение groupId:artifactId (например, androidx.window:window ).
  • Плагины Gradle: идентификатор плагина (например, com.android.application ).
  • Ключевые слова:
    • gradle (инструмент сборки Gradle)
    • studio (Android Studio)
    • agp (плагин Android Gradle)
    • ndk (Android NDK)
    • sdk (Android SDK)
    • emulator (эмулятор Android)
    • adb (Android Debug Bridge)
    • compose (Jetpack Compose BOM)
    • kotlin (среда выполнения и компилятор Kotlin)
    • android (версии ОС Android)
    • platform-tools (Android SDK Platform-Tools)
    • cmdline-tools (Инструменты командной строки Android SDK)
    • build-tools (Инструменты сборки Android SDK)

Параметры:

• --pid=<pid> - Идентификатор процесса (PID) конкретного экземпляра Android Studio, к которому следует подключиться, если их несколько.
• --project=<project> - Название проекта, открытого в Android Studio для запроса, если их несколько. Если вы запускаете команду version-lookup из каталога проекта, по умолчанию используется именно этот проект.

Пример:

android studio version-lookup \
  androidx.compose.ui:ui \
  com.android.application \
  agp \
  kotlin

update

Использование: android update

Описание: Обновить интерфейс командной строки Android.

-V, --version

Описание: Отображает текущую версию Android CLI.