diff --git a/codex-public-marketplace-submission/plugin.json b/codex-public-marketplace-submission/plugin.json index 419890e..79fafe7 100644 --- a/codex-public-marketplace-submission/plugin.json +++ b/codex-public-marketplace-submission/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "android-cli", - "version": "1.0.0", + "version": "1.0.1", "description": "Use the Android CLI to create Android projects, run apps on devices and emulators, manage the Android SDK, and search official Android documentation.", "author": { "name": "Google / Android", diff --git a/codex-public-marketplace-submission/skills/android-cli/SKILL.md b/codex-public-marketplace-submission/skills/android-cli/SKILL.md index e0a5f9f..c9ebe6d 100644 --- a/codex-public-marketplace-submission/skills/android-cli/SKILL.md +++ b/codex-public-marketplace-submission/skills/android-cli/SKILL.md @@ -2,14 +2,14 @@ name: android-cli description: Provides instructions for installing and using the `android` CLI. The `android` command-line tool is a critical tool for Android development and helps - you create new Android projects, install APKs onto devices and emulators and launch - and run apps on them, manage and interact with Android virtual devices (including - screenshots and UI inspection), manage Android SDK components, look up official - Android documentation, and discover and install official Android skills. + you create new Android projects, run Android apps on devices, manage and interact + with Android virtual devices (including screenshots and UI inspection), manage Android + SDK components, look up official Android documentation, and discover and install + official Android skills. license: Complete terms in LICENSE.txt metadata: author: Google LLC - last-updated: '2026-10-16' + last-updated: '2026-09-12' keywords: - android-cli - sdk @@ -30,8 +30,7 @@ interacting with devices, and managing the CLI environment. If the android tool is not in the path, install it. To install run the following command: -- Linux x86-64: curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh \| bash -- Linux ARM64: curl -fsSL https://dl.google.com/android/cli/latest/linux_arm64/install.sh \| bash +- Linux: curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh \| bash - Mac Arm: curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh \| bash - Mac Intel: curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh \| bash - Windows: curl -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\\i.cmd" \&\& "%TEMP%\\i.cmd" @@ -58,103 +57,11 @@ For example: `android create empty-activity --name="My App" --output=./my-app` Use the `android layout` command to inspect the UI layout of an Android application in JSON format. Use the `android screen` command to visually inspect the UI and obtain bounding coordinates for visual regions. -`android layout` dumps the UI as JSON. `android screen capture -o ` saves a PNG. -Both auto-select the device when only one is connected. -### UI Dump - -`android layout` returns a JSON tree of the UI elements on screen. - -Each JSON object represents a UI element in the Android app. The following properties may be present: -- `text` - any literal text the element contains -- `resource-id` - the Android resource id used to refer to the element -- `content-desc` - a description of a UI element for use by accessibility tools -- `interactions` - the set of user interactions the element supports. May contain one or more of: `CHECKABLE`, `CLICKABLE`, `FOCUSABLE`, `SCROLLABLE`, `LONG-CLICKABLE`, `PASSWORD` -- `state` - the set of states the element is in. May contain one or more of `CHECKED`, `FOCUSED`, `SELECTED` -- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]` -- `center` - the screen coordinates of the center of the element, in the format `[x,y]` -- `off-screen` - if true, the element is in the UI hierarchy but not within the bounds of the screen; it may require scrolling to view. -- `hidden` - if true, the element is in the UI hierarchy but not visible or interactive on screen. - -Use `layout` as a primary means of examining an Android app. - -By default, `layout` only returns elements that have content or are interactive: -- elements with non-empty `text` or `contentDesc` properties -- elements with non-empty `interactions` or `state` -To return all elements, use the `--full` flag - -If `layout` continues to fail, use `android screen capture --annotate` to inspect the app. - -### Screenshot - -`android screen capture -o ` saves a PNG of the current device screen to `` - -Use `screen capture` as a secondary means of examining an Android app -Examples: -- Understanding the content of an on-screen image -- Looking at a `WebView` (web content does not always appear in the ui dump) -- Trying to find a UI element by its visual appearance - -**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android screen` BEFORE doing anything else. - -### Annotated Screenshot - -`android screen capture --annotate -o ` -`android screen resolve --screenshot --string ` - -The `--annotate` command adds numerical labels and bounding boxes around UI elements. Use this command to locate UI elements that cannot -be located in the `layout` output. - -**IMPORTANT** : When using `android screen capture --annotate`, always *VISUALLY* examine the resulting PNG file. - -To refer to these labels in input commands, use `screen resolve` to convert labels into coordinates: - -`android screen resolve --screenshot --string "#3"` returns ` ` - -To save turns, you can combine shell commands: - -`adb shell input $(android screen resolve --screenshot screen.png --string "tap #34")` - -This command taps on region #34 from `screen.png` - -### Input - -Use `adb shell input` for interacting with Android devices. -Refer to the `"interactions"` property of an element for what interactions can be performed on a particular element. - -Interact with UI elements with their `center` coordinate or their `bounds` coordinates: -`json -{ -"key": -248568265, -"class": "android.widget.Button", -"bounds": "[138,9][167,38]", -"center": "[152,23]" -}` -To tap on this button, you would execute `adb shell input tap 152 23`. This taps the center. - - { - "key": 12487234, - "class": "com.example.ui.ScrollableList", - "bounds": "[100,200][400,600]", - "center": "[250,400]" - } - -To scroll down on this list, you would execute `adb shell input swipe 250 400 250 200 500`. This swipes from the center to the top over 500ms. - -#### Text Input - -To enter text, ensure the field is focused and execute `adb shell input text ""`. - -- **Spaces (`%s`):** Replace spaces with `%s` (Android ignores text after raw spaces): `adb shell input text "Hello%sworld"` (enters `"Hello world"`). -- **Special characters:** Escape shell metacharacters (`&`, `$`, `(`, `)`, `!`): `adb shell input text "AT\&T"` or `adb shell input text 'Price:\$10'`. -- **Submit / Enter:** `adb shell input keyevent 66` - -### Android Interaction Rules - -1. Always ensure text input fields have `"FOCUSED"` in their `"state"` list before entering text. -2. If an element has `"SCROLLABLE"` in its `"interactions"` list, try scrolling it when looking for missing UI elements. -3. Always scroll slowly when executing scroll inputs. The 5th argument to `adb shell input swipe` controls scroll duration. -4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout` again to see if anything changes. +**IMPORTANT:** Before using `android layout` or `android screen`, you MUST read +this reference: [interact.md](references/interact.md) The reference file +[interact.md](references/interact.md) contains instructions for properly +interacting with Android devices. Follow its instructions exactly. ### Running journey tests @@ -162,107 +69,10 @@ Journey tests involve device interaction; use the `android layout` and `android screen` commands to evaluate Journeys. The instructions for device interaction apply here as well. -A journey is an XML-specified test of an Android app's behavior. It consists of a list of `` elements. For example: -`xml - - -A sample journey to illustrate the format - - - -Tap the "Home" icon - - -Verify that the app is on its Home screen - - -` - -Evaluate a journey by proceeding through the `` list in sequential order. Evaluate each `` block individually. -A journey succeeds if all elements in the `` list succeed. - -A journey is a test case for an app. The journey XML is the source of truth; if the app disagrees with the journey, the app has failed. -Additionally, if the app exits, crashes, or freezes, journey evaluation stops and the journey fails. - -**IMPORTANT** - Execute each step EXACTLY as written, and independently of other steps! If an action says to `"tap the first search result"`, -you MUST find the search results and tap the first one. Do this even if you believe you know the intent behind the action. - -#### Taking Actions - -Some `` elements specify UI interactions to perform on the running Android app. Perform the interaction and verify that the app does -not crash or behave in an unexpected manner. This is the *only* verification you should perform for an ``. - -If the interaction cannot be performed as specified, the journey fails. -Example: -`Click the red button` -If you determine a red button is not present in the UI, the journey fails. - -If the text of an `` specifies a list of actions, break it into sub-actions and evaluate them individually: -Example: -`Search for soda and add the first result to the cart` -This should be evaluated as: -`Search for soda -Add the first result to the cart` - -If an `` contains something that is not a specification for a UI interaction, alert the user that the journey is malformed and exit -early, specifying the error in question. - -#### Verifying Expectations - -`` elements that begin with "check" or "verify" specify expectations for the current state of the Android app. Determine the current -state of the app and check if the expectations are met. - -Determine the current state of the app by inspecting the current screen of the device without interacting with it. -Example: -`Check if "Switch 2" is visible on the screen` -This requires only inspecting the current screen, not scrolling or interacting. If "Switch 2" is not currently visible, the action fails. - -If the expectations are not met, mark the `` as a failure and the journey evaluation ends. A single `` may contain -multiple expectations. -Example: -`Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed` -This `` fails if ANY of the following are false: -- The app is on the Home screen -- There is a Home icon, and it is blue -- A temperature is displayed - -#### Handling failure - -When running a journey, evaluate it as a test. Failure is acceptable, and often expected. Proper reporting of failures is the priority. - -Keep debugging and troubleshooting to a minimum; assume that tools are showing you the correct output every time. The goal is to determine -if the *current* Android app can correctly handle the *current* steps outlined in the journey. Suggestions for bug fixes, clarification, or -other improvements should be kept to journey evaluation summary at the end. - -#### Summarizing - -After evaluating the whole journey, output a markdown (.md) file describing the results. - -The file should have the following format: - - # Journey: - - ## Results - - - ### Action: Click the blue button ✅ - - **Commands**: - - - `adb shell input swipe 490 200 500 500 500` - - `adb shell input tap 45 920` - - - - **Comment**: The journey step doesn't specify that the button requires scrolling to see - - ### Action: Check if "Switch 2" is visible on the screen ✅ - - **Screenshot**: [switch_2_screenshot.png](path/to/screenshot) - - **Comment**: Confirmed both in layout and visually - - ### Action: The home screen is shown ❌ - - **Comment**: The settings page was shown - - - ### Action: Swipe down to view active notifications +**IMPORTANT:** Before evaluating a journey, you MUST read this reference: +[journeys.md](references/journeys.md) The reference file +[journeys.md](references/journeys.md) contains instructions for correctly +evaluating an Android journey. Follow its instructions exactly. ## Doc searching @@ -290,15 +100,8 @@ Manage Android Virtual Devices (AVDs) using the `android emulator` command ## Capturing screenshots -`android screen capture -o ` (or `--output=`) - -Saves a PNG of the current device screen. When exactly one device or emulator is -connected it is selected automatically. With more than one, pass -`--device=`; `adb devices` lists the serials (`android info` does not -report connected devices). - -**IMPORTANT:** Always *VISUALLY* examine the resulting PNG before doing anything -else. +Capture an image of the current screen of a connected Android device and output +it to a file using the `android screen` command. ## Managing skills @@ -311,79 +114,53 @@ Update the Android CLI using the `android update` command. ## `android help` output Usage: android [-Vhv] [--sdk=PARAM] [COMMAND] - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - auth Authentication commands. Log in to and out of Google services for - Android CLI - completion Installs shell autocomplete configuration for Android CLI in the - current user profile - create Creates a new Android project from available templates. You can - specify the project name, output directory, `minSdk` value, and - dry-run execution + completion Installs shell autocomplete configuration for the Android CLI in + the current user profile + create Create a new Android project from available templates. Allows + specifying project name, output directory, minSdk, and dry-run + execution describe Analyzes an Android project to generate descriptive metadata. This command identifies and outputs the paths to JSON files that detail the project's structure, including build targets and their - corresponding output artifact locations (such as APKs). This + corresponding output artifact locations (e.g., APKs). This information enables other tools and commands to locate build artifacts efficiently - device Manage physical Android devices. Create remote physical device - reservations - docs Searches and fetches developer documentation from the official - Android Knowledge Base - emulator Manages Android Virtual Devices (AVDs). Includes commands to - start, stop, list, and view details about emulators - help Shows the help information for a specified command - info Prints environment information including SDK location, connected - devices, and configuration variables - init Initializes the environment for Android CLI. Sets up required + docs Android documentation commands for searching and fetching + developer documentation from the official knowledge base + emulator Manage Android Virtual Devices (AVDs). Includes commands to start, + stop, list, and view details about emulators + help Shows the help of all commands + info Print environment information including SDK location, connected + devices, and configuration variables. Use specific fields to + narrow the output + init Initializes the environment for the Android CLI. Sets up required configurations, directories, and default skills - input Interact with Android apps by performing gestures and key events - on UI elements - install Installs an Android app (one or more APKs) on a connected device - or emulator without activating any components, using incremental - optimizations for faster deployment than `adb` - layout Returns the layout tree of an app - run Deploys and launches an Android app on a connected device or - emulator - screen Captures and inspects the screen of a connected Android device or - emulator - sdk Manages the Android SDK installation. Includes commands to - install, update, remove, and list available and installed SDK - packages - skills Manages Android CLI skills. Includes commands to install, remove, + install Install an Android Application (one or more APKs) to a connected + device or emulator without activating any components using + incremental optimizations for faster deployment than adb + layout Returns the layout tree of an application + run Build, deploy, and launch an Android application on a connected + device or emulator + screen Commands to view the device + sdk Manage the Android SDK installation. Includes commands to install, + update, remove, and list available and installed SDK packages + skills Manage Android CLI skills. Includes commands to install, remove, list, and search for skills by keyword - studio Connects Android CLI to a running Android Studio instance to - analyze files, find declarations and usages, render Compose - previews, and look up library versions - update Updates Android CLI to the latest version - - auth - Usage: android auth [-h] [COMMAND] - Authentication commands. Log in to and out of Google services for - Android CLI - - Options: - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - login Log in to Google services for Android CLI - logout Log out from Google services for Android CLI - status Prints the currently signed-in account + studio Android Studio commands + update Update the Android CLI to the latest version completion Usage: android completion [-h] [] - Installs shell autocomplete configuration for Android CLI in the + Installs shell autocomplete configuration for the Android CLI in the current user profile Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -391,42 +168,35 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Positional Parameters: - If provided, prints the completion configuration script for - the specified shell without installing it. Supports Bash - and Zsh + If provided, print the given shell completion without + installing. Supported: bash, zsh create - Usage: android create [-h] [--application-id=PARAM] [--force] [--list] - [--min-sdk=PARAM] [--name=PARAM] [--namespace=PARAM] - [--output=PARAM] [] - Creates a new Android project from available templates. You can - specify the project name, output directory, `minSdk` value, and - dry-run execution + Usage: android create [-h] [--applicationId=PARAM] [--list] [--minSdk=PARAM] + [--name=PARAM] [--namespace=PARAM] [--output=PARAM] + [] + Create a new Android project from available templates. Allows + specifying project name, output directory, minSdk, and dry-run + execution Options: - --application-id=PARAM The app ID for the app, for example - `com.example.myapp` - --force Allow creating the project in a - non-empty directory, overwriting - existing files - -h, --help Shows the help message for the specified - command - --list List all available templates - --min-sdk=PARAM The `minSdk` value supported by the app - (the default value is defined in the - template) - --name=PARAM The name of the app, for example `My - Application` - --namespace=PARAM The namespace for resources and package - name for Kotlin source files - -o, --output=PARAM The destination project directory path - (the default value is `.`) + --applicationId=PARAM The application ID for the application + (e.g. 'com.example.myapp') + -h, --help Show the help message for this command + --list List all available templates + --minSdk=PARAM The 'minSdk' supported by the application + (default is defined in the template) + --name=PARAM The name of the application (e.g. 'My + Application') + --namespace=PARAM The namespace for resources and package + name for Kotlin source files + -o, --output=PARAM The destination project directory path + (default is '.') android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for - troubleshooting - -V, --version Print version information and exit + --sdk=PARAM Path to the Android SDK + -v, --verbose Enable verbose output for troubleshooting + -V, --version Print version information and exit Positional Parameters: The template name @@ -436,12 +206,11 @@ Update the Android CLI using the `android update` command. Analyzes an Android project to generate descriptive metadata. This command identifies and outputs the paths to JSON files that detail the project's structure, including build targets and their corresponding - output artifact locations (such as APKs). This information enables - other tools and commands to locate build artifacts efficiently + output artifact locations (e.g., APKs). This information enables other + tools and commands to locate build artifacts efficiently Options: - -h, --help Shows the help message for the specified - command + -h, --help Show the help message for this command --project_dir=PARAM The project directory to describe android options: @@ -449,46 +218,29 @@ Update the Android CLI using the `android update` command. -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit - device - Usage: android device [-h] [COMMAND] - Manage physical Android devices. Create remote physical device - reservations - - Options: - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - remote Manage remote physical devices. Includes commands to list, - reserve, connect to, and manage remote device reservations - docs Usage: android docs [-h] [COMMAND] - Searches and fetches developer documentation from the official Android - Knowledge Base + Android documentation commands for searching and fetching developer + documentation from the official knowledge base Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - fetch Fetches an Android documentation article from a URL starting - with `kb://` - search Searches Android documentation. Enclose keywords in quotes + search Search Android documentation. Enclose keywords in quotes + fetch Fetch an Android documentation article from a URL (kb://...) emulator Usage: android emulator [-h] [COMMAND] - Manages Android Virtual Devices (AVDs). Includes commands to start, + Manage Android Virtual Devices (AVDs). Includes commands to start, stop, list, and view details about emulators Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -496,18 +248,18 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Commands: create Creates a virtual device - list Lists available virtual devices - remove Deletes a virtual device - start Launches the specified virtual device. This command returns - when the emulator is fully started and ready to use + start Launches the specified virtual device. This command will + return when the emulator is fully started and ready to use stop Stops the specified virtual device + list Lists available virtual devices + remove Delete a virtual device help Usage: android help [-h] [COMMAND] - Shows the help information for a specified command + Shows the help of all commands Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -519,11 +271,12 @@ Update the Android CLI using the `android update` command. info Usage: android info [-h] [] - Prints environment information including SDK location, connected - devices, and configuration variables + Print environment information including SDK location, connected + devices, and configuration variables. Use specific fields to narrow + the output Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -531,64 +284,39 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Positional Parameters: - The specific field to print the value of. If omitted, - prints all fields + The specific field to print the value of. If omitted print + all init Usage: android init [-h] - Initializes the environment for Android CLI. Sets up required + Initializes the environment for the Android CLI. Sets up required configurations, directories, and default skills Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit - input - Usage: android input [-h] [--device=PARAM] [COMMAND] - Interact with Android apps by performing gestures and key events on UI - elements - - Options: - --device=PARAM Device serial number or emulator ID (as reported - by 'adb devices') - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - key Press a hardware button, navigation key, or Android keycode - scroll Scroll a container element, optionally until a target - element appears - swipe Swipe from a UI element matching a selector in a given - direction - tap Tap on a UI element matching a selector - text Type text into a UI element matching a selector - install Usage: android install [-h] [--apks=PARAM] [--device=PARAM] [--install-options=PARAM] [--use-delta-install] - Installs an Android app (one or more APKs) on a connected device or - emulator without activating any components, using incremental - optimizations for faster deployment than `adb` + Install an Android Application (one or more APKs) to a connected + device or emulator without activating any components using incremental + optimizations for faster deployment than adb Options: --apks=PARAM The paths to the APKs, comma separated --device=PARAM The device serial number - -h, --help Shows the help message for the - specified command - --install-options=PARAM Additional options or flags to pass to - package manager install (for example, - `-g`, `-d`) + -h, --help Show the help message for this command + --install-options=PARAM Additional options/flags to pass to + package manager install (e.g. -g,-d) --use-delta-install Use fast delta install (speeds up incremental updates by transferring only modified code and resources; - default: `true`) + default: true) android options: --sdk=PARAM Path to the Android SDK @@ -599,16 +327,16 @@ Update the Android CLI using the `android update` command. layout Usage: android layout [-dhp] [--device=PARAM] [--flat] [--full] [--no-idle] [--output=PARAM] - Returns the layout tree of an app + Returns the layout tree of an application Options: --device=PARAM The device serial number -d, --diff Deprecated; no-op flag. Will be removed in a future release --flat Returns a flat list instead of a tree - --full Returns the full tree, including non-interactive + --full Return the full tree, including non-interactive and hidden elements - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --no-idle Don't wait for layout idle state when fetching layout -o, --output=PARAM Writes the layout to the specified file or @@ -623,26 +351,24 @@ Update the Android CLI using the `android update` command. run Usage: android run [-h] [--activity=PARAM] [--apks=PARAM] [--debug] [--device=PARAM] [--install-options=PARAM] [--type=PARAM] [--use-delta-install] - Deploys and launches an Android app on a connected device or emulator + Build, deploy, and launch an Android application on a connected device + or emulator Options: --activity=PARAM The activity name --apks=PARAM The paths to the APKs, comma separated --debug Run in debug mode --device=PARAM The device serial number - -h, --help Shows the help message for the - specified command - --install-options=PARAM Additional options or flags to pass to - package manager install (for example, - `-g`, `-d`) - --type=PARAM The component type (`ACTIVITY`, - `WATCH_FACE`, `TILE`, `COMPLICATION`, - `DECLARATIVE_WATCH_FACE`, - `WEAR_WIDGET`) + -h, --help Show the help message for this command + --install-options=PARAM Additional options/flags to pass to + package manager install (e.g. -g,-d) + --type=PARAM The component type (ACTIVITY, + WATCH_FACE, TILE, COMPLICATION, + DECLARATIVE_WATCH_FACE, WEAR_WIDGET) --use-delta-install Use fast delta install (speeds up incremental updates by transferring only modified code and resources; - default: `true`) + default: true) android options: --sdk=PARAM Path to the Android SDK @@ -652,11 +378,10 @@ Update the Android CLI using the `android update` command. screen Usage: android screen [-h] [COMMAND] - Captures and inspects the screen of a connected Android device or - emulator + Commands to view the device Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -664,89 +389,80 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Commands: capture Outputs the device screen to a PNG - resolve Targets UI elements visually. Substitutes bounding box - coordinates from an annotated screenshot into a string, - replacing all instances of `#N` with the center coordinates - of the bounding box labeled `N` + resolve Target UI elements visually. Substitutes bounding box + coordinates from a annotated screenshot into a string. + Replaces all instances of '#N' with the center coordinates + of the bounding box labeled 'N' sdk - Usage: android sdk [-h] [--ignore-outdated-xmls] [--platform=PARAM] - [COMMAND] - Manages the Android SDK installation. Includes commands to install, + Usage: android sdk [-h] [--platform=PARAM] [COMMAND] + Manage the Android SDK installation. Includes commands to install, update, remove, and list available and installed SDK packages Options: - -h, --help Shows the help message for the specified - command - --ignore-outdated-xmls When installing or updating packages, do - not update other packages' XML files - --platform=PARAM Target platform `_` (for - example, `linux_x86_64`, `mac_arm64`, or - `windows_x86`); defaults to the current - host + -h, --help Show the help message for this command + --platform=PARAM Target platform _ (e.g. + linux_x86_64, mac_arm64, windows_x86), + defaults to current host android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for - troubleshooting - -V, --version Print version information and exit + --sdk=PARAM Path to the Android SDK + -v, --verbose Enable verbose output for troubleshooting + -V, --version Print version information and exit Commands: - install Installs SDK packages - list Lists installed and available SDK packages - remove Removes packages from the SDK - update Updates one or all packages to the latest version + install Install SDK packages + update Update one or all packages to the latest version + remove Remove packages from the SDK + list List installed and available SDK packages skills Usage: android skills [-h] [COMMAND] - Manages Android CLI skills. Includes commands to install, remove, - list, and search for skills by keyword + Manage Android CLI skills. Includes commands to install, remove, list, + and search for skills by keyword Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - add Installs a specific skill by its ID to your environment - find Searches for available skills in the repository matching a + add Install a specific skill by its ID to your environment + remove Remove an installed skill by its ID + list List installed and available skills + find Search for available skills in the repository matching a keyword - list Lists installed and available skills - remove Removes an installed skill by its ID - update Updates installed skills + update Update installed skills studio Usage: android studio [-h] [COMMAND] - Connects Android CLI to a running Android Studio instance to analyze - files, find declarations and usages, render Compose previews, and look - up library versions + Android Studio commands Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - analyze-file Analyzes a file in Android Studio - check Checks the status of running Android Studio - instances - find-declaration Finds the declaration of a symbol - find-usages Finds usages of a symbol - open-file Opens a file in Android Studio - render-compose-preview Renders a Compose preview in Android Studio - version-lookup Looks up the latest available versions of - Maven artifacts, Android versions, and SDK - tools + find-declaration Find declaration of a symbol + find-usages Find usages of a symbol + open-file Open a file in Android Studio + check Check the status of running Studio instances + analyze-file Analyze a file in Android Studio + render-compose-preview Render a Compose preview in Android Studio + version-lookup Looks up the latest available versions on + the internet of maven artifacts, Android + versions, and more update Usage: android update [-h] [--url=PARAM] - Updates Android CLI to the latest version + Update the Android CLI to the latest version Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --url=PARAM The URL to download the update from android options: diff --git a/codex-public-marketplace-submission/skills/android-cli/references/interact.md b/codex-public-marketplace-submission/skills/android-cli/references/interact.md new file mode 100644 index 0000000..2f2a4c4 --- /dev/null +++ b/codex-public-marketplace-submission/skills/android-cli/references/interact.md @@ -0,0 +1,113 @@ +Run `android layout --help` and `android screen --help`. + +## UI Dump + +`android layout` returns a flat JSON list of the UI elements on screen. `android +layout --diff` returns a flat JSON list of the UI elements that have changed +since the last call to `layout` or `layout --diff` + +Each JSON object represents a UI element in the Android app. The following +properties may be present: + +- `text` - any literal text the element contains +- `resourceId` - the Android resource id used to refer to the element +- `contentDesc` - a description of a UI element for use by accessibility tools +- `interactions` - the set of user interactions the element supports. May contain one or more of: `checkable`, `clickable`, `focusable`, `scrollable`, `long-clickable`, `password` +- `state` - the set of states the element is in. May contain one or more of `checked`, `focused`, `selected` +- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]` +- `center` - the screen coordinates of the center of the element, in the format `[x,y]` +- `off-screen` - if true, the element is in the UI hierarchy but not visible; it may require scrolling to view. + +Use `layout` as a primary means of examining an Android app. Use `layout --diff` +to focus on changes and to keep your context small. Example: When entering +digits into a calculator, use `layout --diff` to output only the digit readout +element. + +`layout` may fail due to the app displaying a WebView or animation; in these +cases, use `android screen capture --annotate` to inspect the app. This failure +will likely resolve after navigating away from the current screen. + +## Screenshot + +`android screen capture -o ` saves a PNG of the current device screen +to `` + +Use `screen capture` as a secondary means of examining an Android app +Examples: + +- Understanding the content of an on-screen image +- Looking at a `WebView` (web content does not always appear in the ui dump) +- Trying to find a UI element by its visual appearance + +**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android +screen` BEFORE doing anything else. + +## Annotated Screenshot + +`android screen capture --annotate -o ` +`android screen resolve --screen --string ` + +The `--annotate` command adds numerical labels and bounding boxes around UI +elements. Use this command to locate UI elements that cannot be located in the +`layout` output. + +**IMPORTANT** : When using `android screen --annotate`, always *VISUALLY* examine +the resulting PNG file. + +To refer to these labels in input commands, use `screen resolve` to convert +labels into coordinates: + +`android screen resolve --screen --string "#3"` returns ` ` + +To save turns, you can combine shell commands: + +`adb shell input $(android screen resolve --screen screen.png --string "tap #34")` + +This command taps on region #34 from `screen.png` + +## Input + +Use `adb shell input` for interacting with Android devices. Refer to the +`"interactions"` property of an element for what interactions can be performed +on a particular element. + +Interact with UI elements with their `center` coordinate or their `bounds` +coordinates: +`json +{ +"key": -248568265, +"class": "android.widget.Button", +"bounds": "[138,9][167,38]", +"center": "[152,23]" +}` + +To tap on this button, you would execute `adb shell input tap 152 23`. This taps +the center. + + { + "key": 12487234, + "class": "com.example.ui.ScrollableList", + "bounds": "[100,200][400,600]", + "center": "[250,400]" + } + +To scroll down on this list, you would execute `adb shell input swipe 250 400 +250 200 500`. This swipes from the center to the top over 500ms. + +### Text Input + +To enter text, ensure the field is focused and execute `adb shell input text +""`. + +- **Spaces (`%s`):** Replace spaces with `%s` (Android ignores text after raw spaces): `adb shell input text "Hello%sworld"` (enters `"Hello world"`). +- **Special characters:** Escape shell metacharacters (`&`, `$`, `(`, `)`, `!`): `adb shell input text "AT\&T"` or `adb shell input text 'Price:\$10'`. +- **Submit / Enter:** `adb shell input keyevent 66` + +## Android Interaction Rules + +1. Always ensure text input fields have `"focused"` in their `"state"` list before entering text. +2. If an element has `"scrollable"` in its `"interactions"` list, try scrolling it when looking for missing UI elements. +3. Always scroll slowly when executing scroll inputs. The 5th argument to `adb + shell input swipe` controls scroll duration. +4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout --diff` to see if anything changes. \ No newline at end of file diff --git a/codex-public-marketplace-submission/skills/android-cli/references/journeys.md b/codex-public-marketplace-submission/skills/android-cli/references/journeys.md new file mode 100644 index 0000000..f3cc163 --- /dev/null +++ b/codex-public-marketplace-submission/skills/android-cli/references/journeys.md @@ -0,0 +1,120 @@ +A journey is an XML-specified test of an Android app's behavior. It consists of +a list of `` elements. For example: +`xml + + +A sample journey to illustrate the format + + + +Tap the "Home" icon + + +Verify that the app is on its Home screen + + +` + +Evaluate a journey by proceeding through the `` list in sequential +order. Evaluate each `` block individually. +A journey succeeds if all elements in the `` list succeed. + +A journey is a test case for an app. The journey XML is the source of truth; if +the app disagrees with the journey, the app has failed. +Additionally, if the app exits, crashes, or freezes, journey evaluation stops +and the journey fails. + +**IMPORTANT** - Execute each step EXACTLY as written, and independently of other +steps! If an action says to `"tap the first search result"`, +you MUST find the search results and tap the first one. Do this even if you +believe you know the intent behind the action. + +## Taking Actions + +Some `` elements specify UI interactions to perform on the running +Android app. Perform the interaction and verify that the app does +not crash or behave in an unexpected manner. This is the *only* verification +you should perform for an ``. + +If the interaction cannot be performed as specified, the journey fails. +Example: +`Click the red button` +If you determine a red button is not present in the UI, the journey fails. + +If the text of an `` specifies a list of actions, break it into +sub-actions and evaluate them individually: +Example: +`Search for soda and add the first result to the cart` +This should be evaluated as: +`Search for soda +Add the first result to the cart` + +If an `` contains something that is not a specification for a UI +interaction, alert the user that the journey is malformed and exit +early, specifying the error in question. + +## Verifying Expectations + +`` elements that begin with "check" or "verify" specify expectations +for the current state of the Android app. Determine the current +state of the app and check if the expectations are met. + +Determine the current state of the app by inspecting the current screen of the +device without interacting with it. +Example: +`Check if "Switch 2" is visible on the screen` +This requires only inspecting the current screen, not scrolling or interacting. +If "Switch 2" is not currently visible, the action fails. + +If the expectations are not met, mark the `` as a failure and the +journey evaluation ends. A single `` may contain +multiple expectations. +Example: +`Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed` +This `` fails if ANY of the following are false: + +- The app is on the Home screen +- There is a Home icon, and it is blue +- A temperature is displayed + +## Handling failure + +When running a journey, evaluate it as a test. Failure is acceptable, and often +expected. Proper reporting of failures is the priority. + +Keep debugging and troubleshooting to a minimum; assume that tools are showing +you the correct output every time. The goal is to determine +if the *current* Android app can correctly handle the *current* steps outlined +in the journey. Suggestions for bug fixes, clarification, or +other improvements should be kept to journey evaluation summary at the end. + +## Summarizing + +After evaluating the whole journey, output a markdown (.md) file describing the +results. + +The file should have the following format: + + # Journey: + + ## Results + + + ### Action: Click the blue button ✅ + - **Commands**: + + - `adb shell input swipe 490 200 500 500 500` + - `adb shell input tap 45 920` + + + - **Comment**: The journey step doesn't specify that the button requires scrolling to see + + ### Action: Check if "Switch 2" is visible on the screen ✅ + - **Screenshot**: [switch_2_screenshot.png](path/to/screenshot) + - **Comment**: Confirmed both in layout and visually + + ### Action: The home screen is shown ❌ + - **Comment**: The settings page was shown + + + ### Action: Swipe down to view active notifications \ No newline at end of file diff --git a/plugins/android-cli/.claude-plugin/plugin.json b/plugins/android-cli/.claude-plugin/plugin.json index 613d348..45e4d69 100644 --- a/plugins/android-cli/.claude-plugin/plugin.json +++ b/plugins/android-cli/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "android-cli", - "version": "1.0.0", + "version": "1.0.1", "displayName": "Android CLI", "description": "Use the Android CLI (android) to create Android projects, run apps on devices and emulators, manage the SDK, look up official Android docs and install Android skills.", "author": { @@ -10,5 +10,11 @@ "homepage": "https://developer.android.com/tools/agents/android-cli", "repository": "https://github.com/android/android-cli-plugin", "license": "Apache-2.0", - "keywords": ["android", "cli", "kotlin", "emulator", "sdk"] + "keywords": [ + "android", + "cli", + "kotlin", + "emulator", + "sdk" + ] } diff --git a/plugins/android-cli/.codex-plugin/plugin.json b/plugins/android-cli/.codex-plugin/plugin.json index 2a06445..6a228ee 100644 --- a/plugins/android-cli/.codex-plugin/plugin.json +++ b/plugins/android-cli/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "android-cli", - "version": "1.0.0", + "version": "1.0.1", "description": "Use the Android CLI (android) to create Android projects, run apps on devices and emulators, manage the SDK, look up official Android docs and install Android skills.", "author": { "name": "Google / Android", diff --git a/plugins/android-cli/skills/android-cli/SKILL.md b/plugins/android-cli/skills/android-cli/SKILL.md index e0a5f9f..c9ebe6d 100644 --- a/plugins/android-cli/skills/android-cli/SKILL.md +++ b/plugins/android-cli/skills/android-cli/SKILL.md @@ -2,14 +2,14 @@ name: android-cli description: Provides instructions for installing and using the `android` CLI. The `android` command-line tool is a critical tool for Android development and helps - you create new Android projects, install APKs onto devices and emulators and launch - and run apps on them, manage and interact with Android virtual devices (including - screenshots and UI inspection), manage Android SDK components, look up official - Android documentation, and discover and install official Android skills. + you create new Android projects, run Android apps on devices, manage and interact + with Android virtual devices (including screenshots and UI inspection), manage Android + SDK components, look up official Android documentation, and discover and install + official Android skills. license: Complete terms in LICENSE.txt metadata: author: Google LLC - last-updated: '2026-10-16' + last-updated: '2026-09-12' keywords: - android-cli - sdk @@ -30,8 +30,7 @@ interacting with devices, and managing the CLI environment. If the android tool is not in the path, install it. To install run the following command: -- Linux x86-64: curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh \| bash -- Linux ARM64: curl -fsSL https://dl.google.com/android/cli/latest/linux_arm64/install.sh \| bash +- Linux: curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh \| bash - Mac Arm: curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh \| bash - Mac Intel: curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh \| bash - Windows: curl -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\\i.cmd" \&\& "%TEMP%\\i.cmd" @@ -58,103 +57,11 @@ For example: `android create empty-activity --name="My App" --output=./my-app` Use the `android layout` command to inspect the UI layout of an Android application in JSON format. Use the `android screen` command to visually inspect the UI and obtain bounding coordinates for visual regions. -`android layout` dumps the UI as JSON. `android screen capture -o ` saves a PNG. -Both auto-select the device when only one is connected. -### UI Dump - -`android layout` returns a JSON tree of the UI elements on screen. - -Each JSON object represents a UI element in the Android app. The following properties may be present: -- `text` - any literal text the element contains -- `resource-id` - the Android resource id used to refer to the element -- `content-desc` - a description of a UI element for use by accessibility tools -- `interactions` - the set of user interactions the element supports. May contain one or more of: `CHECKABLE`, `CLICKABLE`, `FOCUSABLE`, `SCROLLABLE`, `LONG-CLICKABLE`, `PASSWORD` -- `state` - the set of states the element is in. May contain one or more of `CHECKED`, `FOCUSED`, `SELECTED` -- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]` -- `center` - the screen coordinates of the center of the element, in the format `[x,y]` -- `off-screen` - if true, the element is in the UI hierarchy but not within the bounds of the screen; it may require scrolling to view. -- `hidden` - if true, the element is in the UI hierarchy but not visible or interactive on screen. - -Use `layout` as a primary means of examining an Android app. - -By default, `layout` only returns elements that have content or are interactive: -- elements with non-empty `text` or `contentDesc` properties -- elements with non-empty `interactions` or `state` -To return all elements, use the `--full` flag - -If `layout` continues to fail, use `android screen capture --annotate` to inspect the app. - -### Screenshot - -`android screen capture -o ` saves a PNG of the current device screen to `` - -Use `screen capture` as a secondary means of examining an Android app -Examples: -- Understanding the content of an on-screen image -- Looking at a `WebView` (web content does not always appear in the ui dump) -- Trying to find a UI element by its visual appearance - -**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android screen` BEFORE doing anything else. - -### Annotated Screenshot - -`android screen capture --annotate -o ` -`android screen resolve --screenshot --string ` - -The `--annotate` command adds numerical labels and bounding boxes around UI elements. Use this command to locate UI elements that cannot -be located in the `layout` output. - -**IMPORTANT** : When using `android screen capture --annotate`, always *VISUALLY* examine the resulting PNG file. - -To refer to these labels in input commands, use `screen resolve` to convert labels into coordinates: - -`android screen resolve --screenshot --string "#3"` returns ` ` - -To save turns, you can combine shell commands: - -`adb shell input $(android screen resolve --screenshot screen.png --string "tap #34")` - -This command taps on region #34 from `screen.png` - -### Input - -Use `adb shell input` for interacting with Android devices. -Refer to the `"interactions"` property of an element for what interactions can be performed on a particular element. - -Interact with UI elements with their `center` coordinate or their `bounds` coordinates: -`json -{ -"key": -248568265, -"class": "android.widget.Button", -"bounds": "[138,9][167,38]", -"center": "[152,23]" -}` -To tap on this button, you would execute `adb shell input tap 152 23`. This taps the center. - - { - "key": 12487234, - "class": "com.example.ui.ScrollableList", - "bounds": "[100,200][400,600]", - "center": "[250,400]" - } - -To scroll down on this list, you would execute `adb shell input swipe 250 400 250 200 500`. This swipes from the center to the top over 500ms. - -#### Text Input - -To enter text, ensure the field is focused and execute `adb shell input text ""`. - -- **Spaces (`%s`):** Replace spaces with `%s` (Android ignores text after raw spaces): `adb shell input text "Hello%sworld"` (enters `"Hello world"`). -- **Special characters:** Escape shell metacharacters (`&`, `$`, `(`, `)`, `!`): `adb shell input text "AT\&T"` or `adb shell input text 'Price:\$10'`. -- **Submit / Enter:** `adb shell input keyevent 66` - -### Android Interaction Rules - -1. Always ensure text input fields have `"FOCUSED"` in their `"state"` list before entering text. -2. If an element has `"SCROLLABLE"` in its `"interactions"` list, try scrolling it when looking for missing UI elements. -3. Always scroll slowly when executing scroll inputs. The 5th argument to `adb shell input swipe` controls scroll duration. -4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout` again to see if anything changes. +**IMPORTANT:** Before using `android layout` or `android screen`, you MUST read +this reference: [interact.md](references/interact.md) The reference file +[interact.md](references/interact.md) contains instructions for properly +interacting with Android devices. Follow its instructions exactly. ### Running journey tests @@ -162,107 +69,10 @@ Journey tests involve device interaction; use the `android layout` and `android screen` commands to evaluate Journeys. The instructions for device interaction apply here as well. -A journey is an XML-specified test of an Android app's behavior. It consists of a list of `` elements. For example: -`xml - - -A sample journey to illustrate the format - - - -Tap the "Home" icon - - -Verify that the app is on its Home screen - - -` - -Evaluate a journey by proceeding through the `` list in sequential order. Evaluate each `` block individually. -A journey succeeds if all elements in the `` list succeed. - -A journey is a test case for an app. The journey XML is the source of truth; if the app disagrees with the journey, the app has failed. -Additionally, if the app exits, crashes, or freezes, journey evaluation stops and the journey fails. - -**IMPORTANT** - Execute each step EXACTLY as written, and independently of other steps! If an action says to `"tap the first search result"`, -you MUST find the search results and tap the first one. Do this even if you believe you know the intent behind the action. - -#### Taking Actions - -Some `` elements specify UI interactions to perform on the running Android app. Perform the interaction and verify that the app does -not crash or behave in an unexpected manner. This is the *only* verification you should perform for an ``. - -If the interaction cannot be performed as specified, the journey fails. -Example: -`Click the red button` -If you determine a red button is not present in the UI, the journey fails. - -If the text of an `` specifies a list of actions, break it into sub-actions and evaluate them individually: -Example: -`Search for soda and add the first result to the cart` -This should be evaluated as: -`Search for soda -Add the first result to the cart` - -If an `` contains something that is not a specification for a UI interaction, alert the user that the journey is malformed and exit -early, specifying the error in question. - -#### Verifying Expectations - -`` elements that begin with "check" or "verify" specify expectations for the current state of the Android app. Determine the current -state of the app and check if the expectations are met. - -Determine the current state of the app by inspecting the current screen of the device without interacting with it. -Example: -`Check if "Switch 2" is visible on the screen` -This requires only inspecting the current screen, not scrolling or interacting. If "Switch 2" is not currently visible, the action fails. - -If the expectations are not met, mark the `` as a failure and the journey evaluation ends. A single `` may contain -multiple expectations. -Example: -`Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed` -This `` fails if ANY of the following are false: -- The app is on the Home screen -- There is a Home icon, and it is blue -- A temperature is displayed - -#### Handling failure - -When running a journey, evaluate it as a test. Failure is acceptable, and often expected. Proper reporting of failures is the priority. - -Keep debugging and troubleshooting to a minimum; assume that tools are showing you the correct output every time. The goal is to determine -if the *current* Android app can correctly handle the *current* steps outlined in the journey. Suggestions for bug fixes, clarification, or -other improvements should be kept to journey evaluation summary at the end. - -#### Summarizing - -After evaluating the whole journey, output a markdown (.md) file describing the results. - -The file should have the following format: - - # Journey: - - ## Results - - - ### Action: Click the blue button ✅ - - **Commands**: - - - `adb shell input swipe 490 200 500 500 500` - - `adb shell input tap 45 920` - - - - **Comment**: The journey step doesn't specify that the button requires scrolling to see - - ### Action: Check if "Switch 2" is visible on the screen ✅ - - **Screenshot**: [switch_2_screenshot.png](path/to/screenshot) - - **Comment**: Confirmed both in layout and visually - - ### Action: The home screen is shown ❌ - - **Comment**: The settings page was shown - - - ### Action: Swipe down to view active notifications +**IMPORTANT:** Before evaluating a journey, you MUST read this reference: +[journeys.md](references/journeys.md) The reference file +[journeys.md](references/journeys.md) contains instructions for correctly +evaluating an Android journey. Follow its instructions exactly. ## Doc searching @@ -290,15 +100,8 @@ Manage Android Virtual Devices (AVDs) using the `android emulator` command ## Capturing screenshots -`android screen capture -o ` (or `--output=`) - -Saves a PNG of the current device screen. When exactly one device or emulator is -connected it is selected automatically. With more than one, pass -`--device=`; `adb devices` lists the serials (`android info` does not -report connected devices). - -**IMPORTANT:** Always *VISUALLY* examine the resulting PNG before doing anything -else. +Capture an image of the current screen of a connected Android device and output +it to a file using the `android screen` command. ## Managing skills @@ -311,79 +114,53 @@ Update the Android CLI using the `android update` command. ## `android help` output Usage: android [-Vhv] [--sdk=PARAM] [COMMAND] - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - auth Authentication commands. Log in to and out of Google services for - Android CLI - completion Installs shell autocomplete configuration for Android CLI in the - current user profile - create Creates a new Android project from available templates. You can - specify the project name, output directory, `minSdk` value, and - dry-run execution + completion Installs shell autocomplete configuration for the Android CLI in + the current user profile + create Create a new Android project from available templates. Allows + specifying project name, output directory, minSdk, and dry-run + execution describe Analyzes an Android project to generate descriptive metadata. This command identifies and outputs the paths to JSON files that detail the project's structure, including build targets and their - corresponding output artifact locations (such as APKs). This + corresponding output artifact locations (e.g., APKs). This information enables other tools and commands to locate build artifacts efficiently - device Manage physical Android devices. Create remote physical device - reservations - docs Searches and fetches developer documentation from the official - Android Knowledge Base - emulator Manages Android Virtual Devices (AVDs). Includes commands to - start, stop, list, and view details about emulators - help Shows the help information for a specified command - info Prints environment information including SDK location, connected - devices, and configuration variables - init Initializes the environment for Android CLI. Sets up required + docs Android documentation commands for searching and fetching + developer documentation from the official knowledge base + emulator Manage Android Virtual Devices (AVDs). Includes commands to start, + stop, list, and view details about emulators + help Shows the help of all commands + info Print environment information including SDK location, connected + devices, and configuration variables. Use specific fields to + narrow the output + init Initializes the environment for the Android CLI. Sets up required configurations, directories, and default skills - input Interact with Android apps by performing gestures and key events - on UI elements - install Installs an Android app (one or more APKs) on a connected device - or emulator without activating any components, using incremental - optimizations for faster deployment than `adb` - layout Returns the layout tree of an app - run Deploys and launches an Android app on a connected device or - emulator - screen Captures and inspects the screen of a connected Android device or - emulator - sdk Manages the Android SDK installation. Includes commands to - install, update, remove, and list available and installed SDK - packages - skills Manages Android CLI skills. Includes commands to install, remove, + install Install an Android Application (one or more APKs) to a connected + device or emulator without activating any components using + incremental optimizations for faster deployment than adb + layout Returns the layout tree of an application + run Build, deploy, and launch an Android application on a connected + device or emulator + screen Commands to view the device + sdk Manage the Android SDK installation. Includes commands to install, + update, remove, and list available and installed SDK packages + skills Manage Android CLI skills. Includes commands to install, remove, list, and search for skills by keyword - studio Connects Android CLI to a running Android Studio instance to - analyze files, find declarations and usages, render Compose - previews, and look up library versions - update Updates Android CLI to the latest version - - auth - Usage: android auth [-h] [COMMAND] - Authentication commands. Log in to and out of Google services for - Android CLI - - Options: - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - login Log in to Google services for Android CLI - logout Log out from Google services for Android CLI - status Prints the currently signed-in account + studio Android Studio commands + update Update the Android CLI to the latest version completion Usage: android completion [-h] [] - Installs shell autocomplete configuration for Android CLI in the + Installs shell autocomplete configuration for the Android CLI in the current user profile Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -391,42 +168,35 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Positional Parameters: - If provided, prints the completion configuration script for - the specified shell without installing it. Supports Bash - and Zsh + If provided, print the given shell completion without + installing. Supported: bash, zsh create - Usage: android create [-h] [--application-id=PARAM] [--force] [--list] - [--min-sdk=PARAM] [--name=PARAM] [--namespace=PARAM] - [--output=PARAM] [] - Creates a new Android project from available templates. You can - specify the project name, output directory, `minSdk` value, and - dry-run execution + Usage: android create [-h] [--applicationId=PARAM] [--list] [--minSdk=PARAM] + [--name=PARAM] [--namespace=PARAM] [--output=PARAM] + [] + Create a new Android project from available templates. Allows + specifying project name, output directory, minSdk, and dry-run + execution Options: - --application-id=PARAM The app ID for the app, for example - `com.example.myapp` - --force Allow creating the project in a - non-empty directory, overwriting - existing files - -h, --help Shows the help message for the specified - command - --list List all available templates - --min-sdk=PARAM The `minSdk` value supported by the app - (the default value is defined in the - template) - --name=PARAM The name of the app, for example `My - Application` - --namespace=PARAM The namespace for resources and package - name for Kotlin source files - -o, --output=PARAM The destination project directory path - (the default value is `.`) + --applicationId=PARAM The application ID for the application + (e.g. 'com.example.myapp') + -h, --help Show the help message for this command + --list List all available templates + --minSdk=PARAM The 'minSdk' supported by the application + (default is defined in the template) + --name=PARAM The name of the application (e.g. 'My + Application') + --namespace=PARAM The namespace for resources and package + name for Kotlin source files + -o, --output=PARAM The destination project directory path + (default is '.') android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for - troubleshooting - -V, --version Print version information and exit + --sdk=PARAM Path to the Android SDK + -v, --verbose Enable verbose output for troubleshooting + -V, --version Print version information and exit Positional Parameters: The template name @@ -436,12 +206,11 @@ Update the Android CLI using the `android update` command. Analyzes an Android project to generate descriptive metadata. This command identifies and outputs the paths to JSON files that detail the project's structure, including build targets and their corresponding - output artifact locations (such as APKs). This information enables - other tools and commands to locate build artifacts efficiently + output artifact locations (e.g., APKs). This information enables other + tools and commands to locate build artifacts efficiently Options: - -h, --help Shows the help message for the specified - command + -h, --help Show the help message for this command --project_dir=PARAM The project directory to describe android options: @@ -449,46 +218,29 @@ Update the Android CLI using the `android update` command. -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit - device - Usage: android device [-h] [COMMAND] - Manage physical Android devices. Create remote physical device - reservations - - Options: - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - remote Manage remote physical devices. Includes commands to list, - reserve, connect to, and manage remote device reservations - docs Usage: android docs [-h] [COMMAND] - Searches and fetches developer documentation from the official Android - Knowledge Base + Android documentation commands for searching and fetching developer + documentation from the official knowledge base Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - fetch Fetches an Android documentation article from a URL starting - with `kb://` - search Searches Android documentation. Enclose keywords in quotes + search Search Android documentation. Enclose keywords in quotes + fetch Fetch an Android documentation article from a URL (kb://...) emulator Usage: android emulator [-h] [COMMAND] - Manages Android Virtual Devices (AVDs). Includes commands to start, + Manage Android Virtual Devices (AVDs). Includes commands to start, stop, list, and view details about emulators Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -496,18 +248,18 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Commands: create Creates a virtual device - list Lists available virtual devices - remove Deletes a virtual device - start Launches the specified virtual device. This command returns - when the emulator is fully started and ready to use + start Launches the specified virtual device. This command will + return when the emulator is fully started and ready to use stop Stops the specified virtual device + list Lists available virtual devices + remove Delete a virtual device help Usage: android help [-h] [COMMAND] - Shows the help information for a specified command + Shows the help of all commands Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -519,11 +271,12 @@ Update the Android CLI using the `android update` command. info Usage: android info [-h] [] - Prints environment information including SDK location, connected - devices, and configuration variables + Print environment information including SDK location, connected + devices, and configuration variables. Use specific fields to narrow + the output Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -531,64 +284,39 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Positional Parameters: - The specific field to print the value of. If omitted, - prints all fields + The specific field to print the value of. If omitted print + all init Usage: android init [-h] - Initializes the environment for Android CLI. Sets up required + Initializes the environment for the Android CLI. Sets up required configurations, directories, and default skills Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit - input - Usage: android input [-h] [--device=PARAM] [COMMAND] - Interact with Android apps by performing gestures and key events on UI - elements - - Options: - --device=PARAM Device serial number or emulator ID (as reported - by 'adb devices') - -h, --help Shows the help message for the specified command - - android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for troubleshooting - -V, --version Print version information and exit - Commands: - key Press a hardware button, navigation key, or Android keycode - scroll Scroll a container element, optionally until a target - element appears - swipe Swipe from a UI element matching a selector in a given - direction - tap Tap on a UI element matching a selector - text Type text into a UI element matching a selector - install Usage: android install [-h] [--apks=PARAM] [--device=PARAM] [--install-options=PARAM] [--use-delta-install] - Installs an Android app (one or more APKs) on a connected device or - emulator without activating any components, using incremental - optimizations for faster deployment than `adb` + Install an Android Application (one or more APKs) to a connected + device or emulator without activating any components using incremental + optimizations for faster deployment than adb Options: --apks=PARAM The paths to the APKs, comma separated --device=PARAM The device serial number - -h, --help Shows the help message for the - specified command - --install-options=PARAM Additional options or flags to pass to - package manager install (for example, - `-g`, `-d`) + -h, --help Show the help message for this command + --install-options=PARAM Additional options/flags to pass to + package manager install (e.g. -g,-d) --use-delta-install Use fast delta install (speeds up incremental updates by transferring only modified code and resources; - default: `true`) + default: true) android options: --sdk=PARAM Path to the Android SDK @@ -599,16 +327,16 @@ Update the Android CLI using the `android update` command. layout Usage: android layout [-dhp] [--device=PARAM] [--flat] [--full] [--no-idle] [--output=PARAM] - Returns the layout tree of an app + Returns the layout tree of an application Options: --device=PARAM The device serial number -d, --diff Deprecated; no-op flag. Will be removed in a future release --flat Returns a flat list instead of a tree - --full Returns the full tree, including non-interactive + --full Return the full tree, including non-interactive and hidden elements - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --no-idle Don't wait for layout idle state when fetching layout -o, --output=PARAM Writes the layout to the specified file or @@ -623,26 +351,24 @@ Update the Android CLI using the `android update` command. run Usage: android run [-h] [--activity=PARAM] [--apks=PARAM] [--debug] [--device=PARAM] [--install-options=PARAM] [--type=PARAM] [--use-delta-install] - Deploys and launches an Android app on a connected device or emulator + Build, deploy, and launch an Android application on a connected device + or emulator Options: --activity=PARAM The activity name --apks=PARAM The paths to the APKs, comma separated --debug Run in debug mode --device=PARAM The device serial number - -h, --help Shows the help message for the - specified command - --install-options=PARAM Additional options or flags to pass to - package manager install (for example, - `-g`, `-d`) - --type=PARAM The component type (`ACTIVITY`, - `WATCH_FACE`, `TILE`, `COMPLICATION`, - `DECLARATIVE_WATCH_FACE`, - `WEAR_WIDGET`) + -h, --help Show the help message for this command + --install-options=PARAM Additional options/flags to pass to + package manager install (e.g. -g,-d) + --type=PARAM The component type (ACTIVITY, + WATCH_FACE, TILE, COMPLICATION, + DECLARATIVE_WATCH_FACE, WEAR_WIDGET) --use-delta-install Use fast delta install (speeds up incremental updates by transferring only modified code and resources; - default: `true`) + default: true) android options: --sdk=PARAM Path to the Android SDK @@ -652,11 +378,10 @@ Update the Android CLI using the `android update` command. screen Usage: android screen [-h] [COMMAND] - Captures and inspects the screen of a connected Android device or - emulator + Commands to view the device Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK @@ -664,89 +389,80 @@ Update the Android CLI using the `android update` command. -V, --version Print version information and exit Commands: capture Outputs the device screen to a PNG - resolve Targets UI elements visually. Substitutes bounding box - coordinates from an annotated screenshot into a string, - replacing all instances of `#N` with the center coordinates - of the bounding box labeled `N` + resolve Target UI elements visually. Substitutes bounding box + coordinates from a annotated screenshot into a string. + Replaces all instances of '#N' with the center coordinates + of the bounding box labeled 'N' sdk - Usage: android sdk [-h] [--ignore-outdated-xmls] [--platform=PARAM] - [COMMAND] - Manages the Android SDK installation. Includes commands to install, + Usage: android sdk [-h] [--platform=PARAM] [COMMAND] + Manage the Android SDK installation. Includes commands to install, update, remove, and list available and installed SDK packages Options: - -h, --help Shows the help message for the specified - command - --ignore-outdated-xmls When installing or updating packages, do - not update other packages' XML files - --platform=PARAM Target platform `_` (for - example, `linux_x86_64`, `mac_arm64`, or - `windows_x86`); defaults to the current - host + -h, --help Show the help message for this command + --platform=PARAM Target platform _ (e.g. + linux_x86_64, mac_arm64, windows_x86), + defaults to current host android options: - --sdk=PARAM Path to the Android SDK - -v, --verbose Enable verbose output for - troubleshooting - -V, --version Print version information and exit + --sdk=PARAM Path to the Android SDK + -v, --verbose Enable verbose output for troubleshooting + -V, --version Print version information and exit Commands: - install Installs SDK packages - list Lists installed and available SDK packages - remove Removes packages from the SDK - update Updates one or all packages to the latest version + install Install SDK packages + update Update one or all packages to the latest version + remove Remove packages from the SDK + list List installed and available SDK packages skills Usage: android skills [-h] [COMMAND] - Manages Android CLI skills. Includes commands to install, remove, - list, and search for skills by keyword + Manage Android CLI skills. Includes commands to install, remove, list, + and search for skills by keyword Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - add Installs a specific skill by its ID to your environment - find Searches for available skills in the repository matching a + add Install a specific skill by its ID to your environment + remove Remove an installed skill by its ID + list List installed and available skills + find Search for available skills in the repository matching a keyword - list Lists installed and available skills - remove Removes an installed skill by its ID - update Updates installed skills + update Update installed skills studio Usage: android studio [-h] [COMMAND] - Connects Android CLI to a running Android Studio instance to analyze - files, find declarations and usages, render Compose previews, and look - up library versions + Android Studio commands Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command android options: --sdk=PARAM Path to the Android SDK -v, --verbose Enable verbose output for troubleshooting -V, --version Print version information and exit Commands: - analyze-file Analyzes a file in Android Studio - check Checks the status of running Android Studio - instances - find-declaration Finds the declaration of a symbol - find-usages Finds usages of a symbol - open-file Opens a file in Android Studio - render-compose-preview Renders a Compose preview in Android Studio - version-lookup Looks up the latest available versions of - Maven artifacts, Android versions, and SDK - tools + find-declaration Find declaration of a symbol + find-usages Find usages of a symbol + open-file Open a file in Android Studio + check Check the status of running Studio instances + analyze-file Analyze a file in Android Studio + render-compose-preview Render a Compose preview in Android Studio + version-lookup Looks up the latest available versions on + the internet of maven artifacts, Android + versions, and more update Usage: android update [-h] [--url=PARAM] - Updates Android CLI to the latest version + Update the Android CLI to the latest version Options: - -h, --help Shows the help message for the specified command + -h, --help Show the help message for this command --url=PARAM The URL to download the update from android options: diff --git a/plugins/android-cli/skills/android-cli/references/interact.md b/plugins/android-cli/skills/android-cli/references/interact.md new file mode 100644 index 0000000..2f2a4c4 --- /dev/null +++ b/plugins/android-cli/skills/android-cli/references/interact.md @@ -0,0 +1,113 @@ +Run `android layout --help` and `android screen --help`. + +## UI Dump + +`android layout` returns a flat JSON list of the UI elements on screen. `android +layout --diff` returns a flat JSON list of the UI elements that have changed +since the last call to `layout` or `layout --diff` + +Each JSON object represents a UI element in the Android app. The following +properties may be present: + +- `text` - any literal text the element contains +- `resourceId` - the Android resource id used to refer to the element +- `contentDesc` - a description of a UI element for use by accessibility tools +- `interactions` - the set of user interactions the element supports. May contain one or more of: `checkable`, `clickable`, `focusable`, `scrollable`, `long-clickable`, `password` +- `state` - the set of states the element is in. May contain one or more of `checked`, `focused`, `selected` +- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]` +- `center` - the screen coordinates of the center of the element, in the format `[x,y]` +- `off-screen` - if true, the element is in the UI hierarchy but not visible; it may require scrolling to view. + +Use `layout` as a primary means of examining an Android app. Use `layout --diff` +to focus on changes and to keep your context small. Example: When entering +digits into a calculator, use `layout --diff` to output only the digit readout +element. + +`layout` may fail due to the app displaying a WebView or animation; in these +cases, use `android screen capture --annotate` to inspect the app. This failure +will likely resolve after navigating away from the current screen. + +## Screenshot + +`android screen capture -o ` saves a PNG of the current device screen +to `` + +Use `screen capture` as a secondary means of examining an Android app +Examples: + +- Understanding the content of an on-screen image +- Looking at a `WebView` (web content does not always appear in the ui dump) +- Trying to find a UI element by its visual appearance + +**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android +screen` BEFORE doing anything else. + +## Annotated Screenshot + +`android screen capture --annotate -o ` +`android screen resolve --screen --string ` + +The `--annotate` command adds numerical labels and bounding boxes around UI +elements. Use this command to locate UI elements that cannot be located in the +`layout` output. + +**IMPORTANT** : When using `android screen --annotate`, always *VISUALLY* examine +the resulting PNG file. + +To refer to these labels in input commands, use `screen resolve` to convert +labels into coordinates: + +`android screen resolve --screen --string "#3"` returns ` ` + +To save turns, you can combine shell commands: + +`adb shell input $(android screen resolve --screen screen.png --string "tap #34")` + +This command taps on region #34 from `screen.png` + +## Input + +Use `adb shell input` for interacting with Android devices. Refer to the +`"interactions"` property of an element for what interactions can be performed +on a particular element. + +Interact with UI elements with their `center` coordinate or their `bounds` +coordinates: +`json +{ +"key": -248568265, +"class": "android.widget.Button", +"bounds": "[138,9][167,38]", +"center": "[152,23]" +}` + +To tap on this button, you would execute `adb shell input tap 152 23`. This taps +the center. + + { + "key": 12487234, + "class": "com.example.ui.ScrollableList", + "bounds": "[100,200][400,600]", + "center": "[250,400]" + } + +To scroll down on this list, you would execute `adb shell input swipe 250 400 +250 200 500`. This swipes from the center to the top over 500ms. + +### Text Input + +To enter text, ensure the field is focused and execute `adb shell input text +""`. + +- **Spaces (`%s`):** Replace spaces with `%s` (Android ignores text after raw spaces): `adb shell input text "Hello%sworld"` (enters `"Hello world"`). +- **Special characters:** Escape shell metacharacters (`&`, `$`, `(`, `)`, `!`): `adb shell input text "AT\&T"` or `adb shell input text 'Price:\$10'`. +- **Submit / Enter:** `adb shell input keyevent 66` + +## Android Interaction Rules + +1. Always ensure text input fields have `"focused"` in their `"state"` list before entering text. +2. If an element has `"scrollable"` in its `"interactions"` list, try scrolling it when looking for missing UI elements. +3. Always scroll slowly when executing scroll inputs. The 5th argument to `adb + shell input swipe` controls scroll duration. +4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout --diff` to see if anything changes. \ No newline at end of file diff --git a/plugins/android-cli/skills/android-cli/references/journeys.md b/plugins/android-cli/skills/android-cli/references/journeys.md new file mode 100644 index 0000000..f3cc163 --- /dev/null +++ b/plugins/android-cli/skills/android-cli/references/journeys.md @@ -0,0 +1,120 @@ +A journey is an XML-specified test of an Android app's behavior. It consists of +a list of `` elements. For example: +`xml + + +A sample journey to illustrate the format + + + +Tap the "Home" icon + + +Verify that the app is on its Home screen + + +` + +Evaluate a journey by proceeding through the `` list in sequential +order. Evaluate each `` block individually. +A journey succeeds if all elements in the `` list succeed. + +A journey is a test case for an app. The journey XML is the source of truth; if +the app disagrees with the journey, the app has failed. +Additionally, if the app exits, crashes, or freezes, journey evaluation stops +and the journey fails. + +**IMPORTANT** - Execute each step EXACTLY as written, and independently of other +steps! If an action says to `"tap the first search result"`, +you MUST find the search results and tap the first one. Do this even if you +believe you know the intent behind the action. + +## Taking Actions + +Some `` elements specify UI interactions to perform on the running +Android app. Perform the interaction and verify that the app does +not crash or behave in an unexpected manner. This is the *only* verification +you should perform for an ``. + +If the interaction cannot be performed as specified, the journey fails. +Example: +`Click the red button` +If you determine a red button is not present in the UI, the journey fails. + +If the text of an `` specifies a list of actions, break it into +sub-actions and evaluate them individually: +Example: +`Search for soda and add the first result to the cart` +This should be evaluated as: +`Search for soda +Add the first result to the cart` + +If an `` contains something that is not a specification for a UI +interaction, alert the user that the journey is malformed and exit +early, specifying the error in question. + +## Verifying Expectations + +`` elements that begin with "check" or "verify" specify expectations +for the current state of the Android app. Determine the current +state of the app and check if the expectations are met. + +Determine the current state of the app by inspecting the current screen of the +device without interacting with it. +Example: +`Check if "Switch 2" is visible on the screen` +This requires only inspecting the current screen, not scrolling or interacting. +If "Switch 2" is not currently visible, the action fails. + +If the expectations are not met, mark the `` as a failure and the +journey evaluation ends. A single `` may contain +multiple expectations. +Example: +`Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed` +This `` fails if ANY of the following are false: + +- The app is on the Home screen +- There is a Home icon, and it is blue +- A temperature is displayed + +## Handling failure + +When running a journey, evaluate it as a test. Failure is acceptable, and often +expected. Proper reporting of failures is the priority. + +Keep debugging and troubleshooting to a minimum; assume that tools are showing +you the correct output every time. The goal is to determine +if the *current* Android app can correctly handle the *current* steps outlined +in the journey. Suggestions for bug fixes, clarification, or +other improvements should be kept to journey evaluation summary at the end. + +## Summarizing + +After evaluating the whole journey, output a markdown (.md) file describing the +results. + +The file should have the following format: + + # Journey: + + ## Results + + + ### Action: Click the blue button ✅ + - **Commands**: + + - `adb shell input swipe 490 200 500 500 500` + - `adb shell input tap 45 920` + + + - **Comment**: The journey step doesn't specify that the button requires scrolling to see + + ### Action: Check if "Switch 2" is visible on the screen ✅ + - **Screenshot**: [switch_2_screenshot.png](path/to/screenshot) + - **Comment**: Confirmed both in layout and visually + + ### Action: The home screen is shown ❌ + - **Comment**: The settings page was shown + + + ### Action: Swipe down to view active notifications \ No newline at end of file