android input

Interact with Android apps by performing gestures and key events on UI elements.

Usage

android input [-h] [--device=PARAM]

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.

Subcommands

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

Description

android input performs user interactions and hardware inputs on a connected Android-powered device or emulator.

AI agents and test scripts can use android input in combination with android layout or android screen to discover UI elements and interact with them using gestures or keystrokes.

UI element selectors

Most input subcommands target UI elements using a selector expression. A selector is a comma-separated list of key=value or key:value pairs specifying properties that a target element must satisfy. Enclose selectors in single quotes to prevent shell interpretation of spaces, commas, or special characters.

Selectors match against the app's live accessibility node hierarchy:

  • String properties: Matched as case-insensitive substrings by default (for example, text=submit matches "Submit order"). Pass * to match any element with a non-empty value for that property. Wrap a value in slashes to match it as a case-sensitive regular expression that can match any part of the value (for example, text=/^Submit$/). Add the i flag after the closing slash for a case-insensitive regular expression (for example, text=/^submit$/i). Commas inside a regular expression do not split the selector. To match literal text that starts with /, use a regular expression such as text=/^\/help/.
    • text (synonym: txt): The visible text displayed on the element.
    • id (synonym: res): The view resource ID name (for example, id=submit_button or the full resource name com.example.app:id/submit_button).
    • class (synonyms: clazz, cls, clz): The element class name or simple class name (such as class=Button or android.widget.Button).
    • desc (synonym: content): The accessibility content description.
  • Interaction properties: Matched as boolean values (true or false).
    • clickable (synonym: click): Whether the element can be clicked.
    • checkable: Whether the element can be checked or toggled.
    • scrollable (synonym: scroll): Whether the element is a scrollable container.
    • focusable: Whether the element can receive focus.
    • longclickable (synonym: longclick): Whether the element supports long clicks.
  • State properties: Matched as boolean values (true or false).
    • checked: Whether the element is currently checked.
    • focused: Whether the element currently has focus.
    • selected: Whether the element is currently selected.

Match behavior (--match)

When a selector matches more than one element on the screen:

  • --match=single (default): Fails with an error and lists all matching elements, ensuring interactions do not trigger the wrong UI component.
  • --match=first: Interacts with the first matching element encountered in the UI hierarchy.

Available gestures and commands

  • tap <target>: Clicks the center of the targeted element.
  • text <string> <target>: Clears existing text and types <string> into the targeted element. Pass --submit to send an Enter/OK key event after typing.
  • scroll <target>: Scrolls a container element in a specified direction (--dir=up|down|left|right). Use --until=<selector> to keep scrolling until a matching element appears.
  • swipe <target>: Performs a swipe gesture starting from <target> in a direction (--dir=up|down|left|right), with optional --distance (fraction of screen) and --speed (pixels per second).
  • key <key>: Sends a hardware button or key event (such as back, home, recents, power, volume-up, volume-down, enter, tab, esc, or an integer Android keycode). Supports modifier flags --shift, --alt, and --ctrl.

Specify a target device (--device)

If multiple devices or emulators are connected, pass --device=<serial-number> (as reported by adb devices) to direct input events to a specific device.

Examples

Tap a button by its visible text:

android input tap 'text=Submit'

Tap an element matching multiple properties:

android input tap 'id=submit_btn,class=Button,clickable=true'

Tap the first matching element when multiple matches exist:

android input tap --match=first 'class=android.widget.TextView'

Type text into an input field and submit:

android input text 'user@example.com' 'id=email_input' --submit

Scroll a container down until an item appears:

android input scroll 'id=recycler_view' --dir=down --until='text=Settings'

Swipe left on a card element:

android input swipe 'id=card_view' --dir=left

Press the device Back button:

android input key back