ithinkihaveacat/emumanager

Android Emulator Manager

Important: Use Script First

ALWAYS use scripts/emumanager over raw sdkmanager, avdmanager, or emulator commands. The script is located in the scripts/ subdirectory of this skill's folder. It provides features that raw commands do not:

• Automatic system image selection for device types (--mobile, --wear, --tv)
• Boot completion detection with timeout
• Sensible defaults and helpful error messages
• Diagnostics via doctor subcommand

When to read the script source: If the script doesn't do exactly what you need, or fails due to missing dependencies, read the script source. It encodes solutions to SDK quirks and boot detection edge cases—use it as reference when building similar functionality.

Quick Start

Environment Variables

export ANDROID_HOME="${ANDROID_HOME:-$HOME/.local/share/android-sdk}"
export ANDROID_USER_HOME="${ANDROID_USER_HOME:-$HOME/.android}"

Prerequisites

• Java 17 or higher
• Hardware acceleration: KVM on Linux, HVF (Hypervisor Framework) on macOS
• Network access for downloading SDK components

Highest-Value Commands

# First-time setup (installs cmdline-tools, platform-tools, build-tools, emulator)
scripts/emumanager bootstrap

# Diagnose issues (Java version, hardware acceleration, disk space)
scripts/emumanager doctor

# Create a mobile/phone AVD with latest API
scripts/emumanager create avd my_phone --mobile

# Start the AVD
scripts/emumanager start avd my_phone

# List all AVDs (shows running status)
scripts/emumanager list avd

# Show detailed AVD information
scripts/emumanager info avd my_phone

Subcommand Overview

bootstrap

Set up SDK environment. Installs cmdline-tools, platform-tools, build-tools, emulator, and a platform.

scripts/emumanager bootstrap
scripts/emumanager bootstrap --no-emulator  # Skip emulator installation

doctor

Run diagnostics to check for common issues: Java version, hardware acceleration, SDK tools, disk space, orphaned AVD files.

scripts/emumanager doctor

list

List local resources (AVDs or installed SDK packages).

# List AVDs
scripts/emumanager list avd              # Show all AVDs with status
scripts/emumanager list avd --names-only # Just AVD names
scripts/emumanager list avd --running-only
scripts/emumanager list avd --stopped-only

# List Packages
scripts/emumanager list package          # List all installed SDK packages
scripts/emumanager list package --outdated # List packages with updates

info

Show detailed information about an AVD.

scripts/emumanager info avd my_phone

create

Create a new AVD.

scripts/emumanager create avd my_phone --mobile   # Mobile/phone (default)
scripts/emumanager create avd my_watch --wear     # Wear OS
scripts/emumanager create avd my_tv --tv          # Android/Google TV
scripts/emumanager create avd my_car --auto       # Android Automotive

# With specific system image
scripts/emumanager create avd my_avd "system-images;android-36;google_apis_playstore;arm64-v8a"

start

Start an AVD. Waits for boot to complete.

scripts/emumanager start avd my_phone              # Quick Boot (fast)
scripts/emumanager start avd my_phone --cold-boot  # Cold boot (bypass snapshots)
scripts/emumanager start avd my_phone --wipe-data  # Factory reset + cold boot

stop

Stop a running AVD.

scripts/emumanager stop avd my_phone

delete

Delete an AVD and clean up files. Stops the AVD first if running.

scripts/emumanager delete avd my_phone

download

Download a specific system image or SDK package.

scripts/emumanager download package "system-images;android-36;google_apis_playstore;arm64-v8a"

catalog

List obtainable packages (system images) from the remote registry. Installed packages are marked with *.

scripts/emumanager catalog package

update

Update all installed SDK packages to latest versions.

scripts/emumanager update package

Device Types

The create command supports device type flags that automatically select the latest appropriate system image for the host architecture:

<!-- markdownlint-disable MD013 -->

| Flag | Device Type | System Image Pattern | | -------------------- | ----------------- | -------------------------------------- | | --mobile/--phone | Mobile/Phone | google_apis_playstore | | --wear/--watch | Wear OS | android-wear / android-wear-signed | | --tv | Android/Google TV | android-tv / google-tv | | --auto | Automotive | android-automotive-playstore |

<!-- markdownlint-restore MD013 -->

If no device type or image is specified, defaults to mobile/phone.

Start Mode Options

<!-- markdownlint-disable MD013 -->

| Mode | Flag | Description | | ------------- | ------------- | ------------------------------------ | | Quick Boot | (default) | Fast startup using snapshots | | Cold Boot | --cold-boot | Bypass Quick Boot, perform full boot | | Factory Reset | --wipe-data | Wipe all data and cold boot |

<!-- markdownlint-restore MD013 -->

Common Workflows

First-Time Setup

scripts/emumanager bootstrap
scripts/emumanager doctor

Creating and Running a Phone Emulator

scripts/emumanager create avd my_phone --mobile
scripts/emumanager start avd my_phone

Creating a Wear OS Emulator

scripts/emumanager create avd my_watch --wear
scripts/emumanager start avd my_watch

Factory Resetting an AVD

scripts/emumanager start avd my_phone --wipe-data

Checking for SDK Updates

scripts/emumanager list package --outdated
scripts/emumanager update package

Safety Notes

• Script requires Java 17+ to run SDK tools
• Hardware acceleration (KVM/HVF) is required for x86_64/arm64 emulators
• System image downloads can be several GB
• Some operations require network access
• The script avoids destructive actions unless explicitly requested
• Use ANDROID_SERIAL environment variable when multiple emulators are running

Reference Documentation

• references/command-index.md - Detailed subcommand reference
• references/troubleshooting.md - Common issues and solutions