Metadata-Version: 2.4
Name: android-avd-cli
Version: 0.1.0
Summary: Android Emulator AVD CLI — manage emulators, grant root, run ADB commands
Project-URL: Homepage, https://github.com/overtimepog/android-cli
Project-URL: Repository, https://github.com/overtimepog/android-cli
Project-URL: Documentation, https://github.com/overtimepog/android-cli#readme
Project-URL: Issues, https://github.com/overtimepog/android-cli/issues
Author-email: overtimepog <overtimedev@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: adb,android,avd,emulator,magisk,root
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# android-cli

Android Emulator AVD CLI — manage emulators, grant root via Magisk, and run ADB commands from the terminal.

```bash
pip install android-cli
```

## Quick Start

```bash
# List available AVDs
android list

# Boot an emulator (headless by default)
android boot rooted-playstore33

# Wait for boot, then auto-grant root via Magisk
android root

# Check device info
android info

# Run ADB shell commands
android shell pm list packages

# Stop the emulator
android kill
```

## Installation

```bash
pip install android-cli
```

Or install from source:

```bash
git clone https://github.com/overtimepog/android-cli.git
cd android-cli
pip install -e .
```

### Prerequisites

- Android SDK with platform tools and a system image installed
- An AVD created (via Android Studio CLI or `avdmanager`)
- For root features: a Magisk-patched system image

## Commands

| Command | Description |
|---------|-------------|
| `android list` | List all available AVDs |
| `android boot <avd>` | Boot an AVD (headless by default) |
| `android status [avd]` | Show running emulators |
| `android root [avd]` | Auto-grant root via Magisk |
| `android kill [avd]` | Stop emulator(s) |
| `android shell <cmd>` | Run ADB shell commands |
| `android info [avd]` | Get device properties |
| `android snapshot <list\|save\|delete>` | Manage snapshots |
| `android sdk-path` | Show detected Android SDK path |

### Boot Options

```bash
# Show the emulator window
android boot <avd> --headed

# Skip snapshots (clean boot)
android boot <avd> --no-snapshot

# Wipe user data
android boot <avd> --wipe-data

# Boot read-only
android boot <avd> --read-only

# Wait for boot to complete
android boot <avd> --wait

# Boot, wait, and auto-grant root
android boot <avd> --root

# Boot with longer timeout
android boot <avd> --wait --timeout 300

# Pass extra emulator flags
android boot <avd> -X "-memory" -X "2048" -X "-cores" -X "4"
```

## How Root Grant Works

When a Magisk-patched emulator boots for the first time, `su -c` opens a dialog in the Magisk app asking for approval. Since the emulator runs headless, `android root`:

1. Triggers a `su` request to open the dialog
2. Tries multiple key-event patterns to auto-approve (Tab→Tab→Enter, Tab→Down→Down→Enter, etc.)
3. Retries with alternative patterns if the first attempt fails
4. Verifies root access was granted

### Root Options

```bash
# Basic root grant
android root

# Check root status without triggering dialog
android root --check

# Grant root with "Remember" checkbox checked
android root --persist

# Retry with up to 5 attempts
android root --retries 5

# Boot and auto-grant in one step
android boot <avd> --root
```

## SDK Detection

The tool auto-detects the Android SDK by checking (in order):

1. `--sdk` CLI flag
2. `ANDROID_HOME` environment variable
3. `ANDROID_SDK_ROOT` environment variable
4. Common paths (`~/Library/Android/sdk`, `~/Android/Sdk`)
5. `emulator` on PATH

## Requirements

- Python 3.8+
- Android SDK (emulator must be on PATH or SDK root set)
- ADB (platform-tools)

## License

MIT
