Обзор интерфейса командной строки 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

Просмотреть на GitHub

Android CLI

Для установки навыка 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-name>

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

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

Параметры:

• --all - Установить или обновить все навыки Android одновременно. Если этот параметр опущен (и не указан --skill ), будет установлен только навык android-cli .
• --agent - Список агентов, для которых нужно установить или обновить навык, разделенных запятыми. Если этот параметр опущен, навык будет установлен для всех обнаруженных агентов.
  • [<skill-name>] — Название навыка, который вы хотите установить или обновить. Если оно опущено (и не указан --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-name>

Описание: Удаление навыка. Если не указаны конкретные агенты, навык будет удален для всех агентов. Аргументы (обязательные):

• <skill-name> - Название навыка, который нужно удалить.

Параметры:

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