android-cli

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

pip install android-cli

Quick Start

# 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

pip install android-cli

Or install from source:

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

Boot Options

# 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

# 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