u2-cli

CLI tool for controlling Android devices via uiautomator2, designed for use by AI agents.

All commands output structured JSON: {"success": bool, "output": str, "code": str} where code is the uiautomator2 Python expression that was executed.

Installation

pip install u2-cli

Or install from source:

git clone https://github.com/yourname/u2-cli
cd u2-cli
uv sync

Usage

# Connect to the only connected device
u2 <command>

# Connect to a specific device by serial
u2 -s <serial> <command>

Commands

device — Device state and low-level operations

u2 device info                        # Show device info
u2 device battery                     # Show battery info
u2 device wlan-ip                     # Show WLAN IP address
u2 device shell <cmd>                 # Run adb shell command
u2 device keyevent <key>              # Send key event (home, back, power, ...)
u2 device push <src> <dst>            # Push file to device
u2 device pull <src> <dst>            # Pull file from device
u2 device screen-on                   # Turn screen on
u2 device screen-off                  # Turn screen off
u2 device orientation                 # Get screen orientation
u2 device orientation <value>         # Set orientation: natural, left, right, upsidedown

app — App lifecycle

u2 app start <package>                # Start app
u2 app start <package> -a <activity>  # Start specific activity
u2 app stop <package>                 # Stop app
u2 app install <path-or-url>          # Install APK
u2 app uninstall <package>            # Uninstall app
u2 app clear <package>                # Clear app data
u2 app list                           # List installed apps
u2 app current                        # Show foreground app
u2 app wait-activity <activity>       # Wait for activity to appear (--timeout/-t)

screen — Visual state

u2 screen screenshot                  # Print PNG bytes to stdout
u2 screen screenshot <path>           # Save screenshot to file
u2 screen dump                        # Dump UI hierarchy as XML
u2 screen dump --simplify             # Dump as compact JSON (removes invisible nodes, shortens names)
u2 screen size                        # Show screen size (WxH)
u2 screen brightness                  # Get brightness (0–255)
u2 screen brightness <value>          # Set brightness

interact — Coordinate-based input

u2 interact tap <x> <y>                        # Tap at coordinates
u2 interact long-tap <x> <y>                   # Long tap (--duration/-d, default 0.5s)
u2 interact swipe <fx> <fy> <tx> <ty>          # Swipe from point to point
u2 interact drag <sx> <sy> <ex> <ey>           # Drag from point to point
u2 interact type <text>                         # Type text into focused element (supports Unicode/CJK)
u2 interact clear                               # Clear text in focused element

element — Selector-based element interaction

Selector options (at least one required): --text/-t, --resource-id/-r, --class-name/-c, --xpath/-x, --description/-d

u2 element find -t "Login"            # Find elements matching selector
u2 element wait -t "Login"            # Wait for element to appear (--timeout/-T)
u2 element exists -r "com.app:id/btn" # Check if element exists
u2 element get-text -t "Username"     # Get text content of element
u2 element set-text <value> -t "..."  # Set text on element
u2 element tap -t "Login"             # Tap matching element
u2 element long-tap -x "//button"     # Long-tap matching element

watch — UI watchers

Watchers auto-trigger actions when a matching element appears.

u2 watch add <name> -x <xpath>        # Register watcher (--action: click/back/home, --timeout/-t)
u2 watch remove <name>                # Remove named watcher (use __all__ to remove all)
u2 watch list                         # List watcher status
u2 watch run -x <xpath>               # Run one-shot unnamed watcher

Output Format

Every command returns a JSON object:

{
  "success": true,
  "output": "...",
  "code": "d(text='Login').click()"
}

• success: whether the command succeeded
• output: human-readable result or error message
• code: the uiautomator2 Python expression that was executed

Development

# Install deps
uv sync

# Run during development (no install needed)
uv run src/u2/__init__.py <cmd>

# Lint
uv run ruff check .
uv run ruff format .

# Build for PyPI
uv build

Requirements

• Python >= 3.12
• Android device with USB debugging enabled (or connected via TCP/IP)
• uiautomator2 server installed on device (u2init or via python -m uiautomator2 init)