Metadata-Version: 2.4
Name: u2-cli
Version: 0.1.1
Summary: CLI tool for executing uiautomator2 commands to control Android devices from the AI Agent
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: typer>=0.24.1
Requires-Dist: uiautomator2>=3.5.0
Description-Content-Type: text/markdown

# u2-cli

CLI tool for controlling Android devices via [uiautomator2](https://github.com/openatx/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

```bash
pip install u2-cli
```

Or install from source:

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

## Usage

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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`

```bash
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.

```bash
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:

```json
{
  "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

```bash
# 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](https://github.com/openatx/uiautomator2) server installed on device (`u2init` or via `python -m uiautomator2 init`)
