emu-run

emu-run is a Fish shell function that launches Android AVDs from the terminal via an interactive fzf picker. No Android Studio required.

---

The Problem

Launching an Android emulator without Android Studio means remembering AVD names, running long emulator -avd ... commands, and having no visibility into which emulators are already running or what their hardware config looks like.

The Solution

A single Fish function that wraps the emulator CLI with a fuzzy-finder picker, live running-status indicators, an inline AVD config preview pane, and ADB boot confirmation. All triggered by typing emu-run.

---

Disclaimer

This project was developed and tested on Linux (CachyOS) with Android SDK installed via Android Studio. The macOS PATH defaults are documented but untested by the author.

This is a personal tooling script. It does not modify any system files or emulator state beyond what the official emulator and adb CLIs already do.

Trademark Notice: Android is a trademark of Google LLC. This project is not affiliated with, endorsed by, or sponsored by Google LLC in any way.

---

Features

• Interactive AVD picker via fzf with a styled TUI (rounded borders, custom colours)
• Running-status indicators, AVDs already running are labelled [running] in the list
• Inline preview pane showing CPU, RAM, screen, ABI, and Play Store info from the AVD's config.ini
• Boot flags: cold boot, wipe data, disable audio
• ADB boot confirmation, polls adb devices for up to 30 s and prints the serial + quick-start commands on success
• Dependency check, detects missing emulator, adb, or fzf and prints actionable fix hints
• No Android Studio required

---

TUI Preview

╭─ Android Emulator Launcher  [ESC: Cancel] ──────────────────────────────╮
│  AVD ›                                                                   │
│  ▶ * Pixel_9_API_36  [running]           AVD: Pixel_9_API_36            │
│      Pixel_7_API_34                                                      │
│      Nexus_5X_API_30                     ── Config ──────────────────── │
│                                          hw.cpu.ncore = 4               │
│                                          hw.ramSize = 2048              │
│                                          hw.screen.density = 420        │
│                                          abi.type = x86_64              │
│                                          PlayStore.enabled = true       │
╰──────────────────────────────────────────────────────────────────────────╯

---

Requirements

Software:

Tool	Notes
fish	fishshell.com
emulator	Android SDK — $ANDROID_HOME/emulator must be on PATH
adb	Android SDK platform-tools — $ANDROID_HOME/platform-tools must be on PATH
fzf	github.com/junegunn/fzf

---

Installation

1. Clone the repository

git clone https://github.com/isotjs/emu-run.git
cd emu-run

2. Copy functions to Fish

cp emu-run.fish ~/.config/fish/functions/emu-run.fish
cp _emu_preview.fish ~/.config/fish/functions/_emu_preview.fish

The functions are auto-loaded by Fish on next shell start. To use them immediately in the current session:

source emu-run.fish
source _emu_preview.fish

3. Ensure Android SDK is on your PATH

# Linux default
set -Ux ANDROID_HOME $HOME/Android/Sdk
# macOS default: $HOME/Library/Android/sdk

fish_add_path $ANDROID_HOME/emulator
fish_add_path $ANDROID_HOME/platform-tools

---

Usage

emu-run [OPTIONS]

Run emu-run with no arguments to open the interactive AVD picker.

Options

Flag	Effect
--cold	Cold boot — ignore saved snapshot
--wipe	Wipe user data on start
--no-audio	Disable emulator audio
--help	Show usage

Flags can be combined:

emu-run --cold --no-audio
emu-run --wipe

---

How It Works

1. Dependency check, exits early with actionable fix hints if emulator, adb, or fzf are missing.
2. AVD discovery, runs emulator -list-avds and cross-references pgrep output to tag already-running instances as [running].
3. fzf picker, presents the enriched list with a live preview pane powered by _emu_preview.fish, which reads config.ini from ~/.android/avd/.
4. Launch — builds the emulator flag string and starts the process detached from the shell (disown).
5. ADB polling, waits up to 30 s for adb devices to confirm the emulator is online, then prints the serial and common ADB commands.

---

File Overview

File	Purpose
emu-run.fish	Main launcher function
_emu_preview.fish	Internal fzf preview helper, reads and displays AVD config.ini

---

Contributing

Issues and pull requests are welcome at github.com/isotjs/emu-run.

If you test this on macOS or a non-standard SDK path, reporting what worked (or didn't) helps broaden compatibility.

---

License

This project is licensed under the GNU General Public License v3.0.