android-emu-agent

LLM-driven Android UI control system

Usage:

android-emu-agent [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • version: Show version information.
  • daemon: Daemon lifecycle commands
  • debug: Debugger commands (JDI Bridge)
  • device: Device management commands
  • expect: Expectation and assertion commands
  • session: Session management commands
  • system: Android system surface commands
  • task: Task harness commands
  • trace: Agent trace recording and replay commands
  • ui: UI observation commands
  • action: Action execution commands
  • wait: Wait/synchronization commands
  • app: App management commands
  • artifact: Artifact and debugging commands
  • emulator: Emulator management commands
  • reliability: Reliability and forensics commands
  • file: File transfer commands
  • skills: Install the bundled Agent Skill into...

android-emu-agent version

Show version information.

Usage:

android-emu-agent version [OPTIONS]

Options:

  • --help: Show this message and exit.

android-emu-agent daemon

Daemon lifecycle commands

Usage:

android-emu-agent daemon [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • start: Start the daemon process.
  • stop: Stop the daemon process.
  • status: Show daemon status.

android-emu-agent daemon start

Start the daemon process.

Start this before any device, session, ui, action, app, or file command. The daemon owns device connections and session state. Exit 1 if the new process exits or does not become healthy within the startup wait. A timeout does not terminate the process; inspect daemon status and logs before retrying.

Examples:

# Start the daemon, then confirm it is healthy
android-emu-agent daemon start
android-emu-agent daemon status --json

Usage:

android-emu-agent daemon start [OPTIONS]

Options:

  • --help: Show this message and exit.

android-emu-agent daemon stop

Stop the daemon process.

Usage:

android-emu-agent daemon stop [OPTIONS]

Options:

  • --help: Show this message and exit.

android-emu-agent daemon status

Show daemon status.

Reports whether the daemon is running, which process owns the socket, and the daemon's version. Check the version when a source checkout and an installed release are both in use.

Examples:

# Human-readable status
android-emu-agent daemon status

# Machine-readable status, including health.version
android-emu-agent daemon status --json

Usage:

android-emu-agent daemon status [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug

Debugger commands (JDI Bridge)

Usage:

android-emu-agent debug [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • ping: Ping the JDI Bridge to verify it starts...
  • attach: Attach the debugger to a running app's JVM.
  • detach: Detach the debugger from a session.
  • status: Get the debug session status.
  • observe: Return fused app, UI snapshot, and...
  • threads: List debugger-visible VM threads.
  • events: Drain and return queued debugger events.
  • stack: Return stack trace for a debugger thread.
  • inspect: Inspect a variable path in the selected...
  • eval: Evaluate a constrained expression in the...
  • step-over: Step over and return stopped state...
  • step-into: Step into and return stopped state...
  • step-out: Step out and return stopped state atomically.
  • resume: Resume one thread or all threads.
  • break: Breakpoint commands
  • break-exception: Exception breakpoint commands
  • mapping: ProGuard/R8 mapping commands

android-emu-agent debug ping

Ping the JDI Bridge to verify it starts and responds.

Usage:

android-emu-agent debug ping [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug attach

Attach the debugger to a running app's JVM.

Usage:

android-emu-agent debug attach [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --package TEXT: App package name [required]
  • --process TEXT: Optional process name (e.g. com.example.app:remote) when multiple are debuggable
  • --keep-suspended: Do not auto-resume a fully suspended VM on attach
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug detach

Detach the debugger from a session.

Usage:

android-emu-agent debug detach [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug status

Get the debug session status.

Usage:

android-emu-agent debug status [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug observe

Return fused app, UI snapshot, and debugger context.

Usage:

android-emu-agent debug observe [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name for optional stack [default: main]
  • --max-frames INTEGER: Maximum stack frames [default: 8]
  • --stack / --no-stack: Include stack summary [default: stack]
  • --events / --no-events: Include queued debugger events [default: events]
  • --drain-events: Drain queued events
  • --event-limit INTEGER: Maximum queued events [default: 20]
  • --logpoints / --no-logpoints: Include buffered logpoint hits [default: logpoints]
  • --logpoint-limit INTEGER: Maximum logpoint hits [default: 20]
  • --ref-limit INTEGER: Maximum latest-snapshot refs [default: 20]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug threads

List debugger-visible VM threads.

Usage:

android-emu-agent debug threads [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --all: Include daemon/internal threads and increase output limit
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug events

Drain and return queued debugger events.

Usage:

android-emu-agent debug events [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug stack

Return stack trace for a debugger thread.

Usage:

android-emu-agent debug stack [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --max-frames INTEGER: Maximum frames to return [default: 10]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug inspect

Inspect a variable path in the selected frame.

Usage:

android-emu-agent debug inspect [OPTIONS] VARIABLE_PATH

Arguments:

  • VARIABLE_PATH: Variable path (e.g. user.profile.name or obj_1) [required]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --frame INTEGER: Zero-based frame index [default: 0]
  • --depth INTEGER: Nested expansion depth (1-3) [default: 1]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug eval

Evaluate a constrained expression in the selected frame.

Usage:

android-emu-agent debug eval [OPTIONS] EXPRESSION

Arguments:

  • EXPRESSION: Expression (field access or toString()) [required]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --frame INTEGER: Zero-based frame index [default: 0]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug step-over

Step over and return stopped state atomically.

Usage:

android-emu-agent debug step-over [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --timeout-seconds FLOAT: Step timeout in seconds [default: 10.0]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug step-into

Step into and return stopped state atomically.

Usage:

android-emu-agent debug step-into [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --timeout-seconds FLOAT: Step timeout in seconds [default: 10.0]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug step-out

Step out and return stopped state atomically.

Usage:

android-emu-agent debug step-out [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Thread name [default: main]
  • --timeout-seconds FLOAT: Step timeout in seconds [default: 10.0]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug resume

Resume one thread or all threads.

Usage:

android-emu-agent debug resume [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --thread TEXT: Optional thread name; omit to resume all threads
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break

Breakpoint commands

Usage:

android-emu-agent debug break [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • set: Set a breakpoint by class pattern and line...
  • remove: Remove a breakpoint by ID.
  • list: List active breakpoints.
  • hits: List buffered non-suspending breakpoint hits.

android-emu-agent debug break set

Set a breakpoint by class pattern and line number.

Usage:

android-emu-agent debug break set [OPTIONS] CLASS_PATTERN LINE

Arguments:

  • CLASS_PATTERN: Class pattern (e.g. com.example.MainActivity) [required]
  • LINE: 1-based source line number [required]

Options:

  • --session TEXT: Session ID [required]
  • --condition TEXT: Condition expression
  • --log-message TEXT: Log message template with {expr} placeholders (non-suspending logpoint)
  • --capture-stack: Capture stack on logpoint hit
  • --stack-max-frames INTEGER RANGE: Frames to capture per logpoint hit [default: 8; x>=1]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break remove

Remove a breakpoint by ID.

Usage:

android-emu-agent debug break remove [OPTIONS] BREAKPOINT_ID

Arguments:

  • BREAKPOINT_ID: Breakpoint ID [required]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break list

List active breakpoints.

Usage:

android-emu-agent debug break list [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break hits

List buffered non-suspending breakpoint hits.

Usage:

android-emu-agent debug break hits [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --breakpoint-id INTEGER: Optional breakpoint ID filter
  • --limit INTEGER: Maximum buffered hits to return [default: 100]
  • --since TEXT: Lower-bound timestamp (epoch ms, ISO 8601, or relative e.g. '10m ago')
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break-exception

Exception breakpoint commands

Usage:

android-emu-agent debug break-exception [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • set: Set an exception breakpoint by class pattern.
  • remove: Remove an exception breakpoint by ID.
  • list: List active exception breakpoints.

android-emu-agent debug break-exception set

Set an exception breakpoint by class pattern.

Usage:

android-emu-agent debug break-exception set [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --class TEXT: Exception class pattern or '_' for all [default: _]
  • --caught / --no-caught: Break on caught exceptions [default: caught]
  • --uncaught / --no-uncaught: Break on uncaught exceptions [default: uncaught]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break-exception remove

Remove an exception breakpoint by ID.

Usage:

android-emu-agent debug break-exception remove [OPTIONS] BREAKPOINT_ID

Arguments:

  • BREAKPOINT_ID: Exception breakpoint ID [required]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug break-exception list

List active exception breakpoints.

Usage:

android-emu-agent debug break-exception list [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug mapping

ProGuard/R8 mapping commands

Usage:

android-emu-agent debug mapping [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • load: Load a ProGuard/R8 mapping file for...
  • clear: Clear the loaded ProGuard/R8 mapping from...

android-emu-agent debug mapping load

Load a ProGuard/R8 mapping file for deobfuscation.

Usage:

android-emu-agent debug mapping load [OPTIONS] PATH

Arguments:

  • PATH: Path to ProGuard/R8 mapping.txt (relative to the invoking CLI directory) [required]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent debug mapping clear

Clear the loaded ProGuard/R8 mapping from this debug session.

Usage:

android-emu-agent debug mapping clear [OPTIONS]

Options:

  • --session TEXT: Session ID [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device

Device management commands

Usage:

android-emu-agent device [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List connected devices.
  • capabilities: Show target capabilities for agent planning.
  • set: Determinism controls

android-emu-agent device list

List connected devices.

Use this to find the serial to pass to 'session start --device'.

Examples:

# Show connected emulators and devices
android-emu-agent device list

# Machine-readable output for scripts and agents
android-emu-agent device list --json

Usage:

android-emu-agent device list [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device capabilities

Show target capabilities for agent planning.

Usage:

android-emu-agent device capabilities [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set

Determinism controls

Usage:

android-emu-agent device set [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • animations: Enable or disable system animations.
  • stay_awake: Enable or disable stay-awake.
  • rotation: Set screen rotation.
  • wifi: Enable or disable WiFi.
  • mobile: Enable or disable mobile data.
  • doze: Force device into or out of doze mode.

android-emu-agent device set animations

Enable or disable system animations.

Usage:

android-emu-agent device set animations [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set stay_awake

Enable or disable stay-awake.

Usage:

android-emu-agent device set stay_awake [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set rotation

Set screen rotation.

Usage:

android-emu-agent device set rotation [OPTIONS] ORIENTATION

Arguments:

  • ORIENTATION: portrait|landscape|reverse-portrait|reverse-landscape|auto [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set wifi

Enable or disable WiFi.

Usage:

android-emu-agent device set wifi [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set mobile

Enable or disable mobile data.

Usage:

android-emu-agent device set mobile [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent device set doze

Force device into or out of doze mode.

Usage:

android-emu-agent device set doze [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect

Expectation and assertion commands

Usage:

android-emu-agent expect [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • idle: Assert that the UI becomes idle.
  • text: Assert that text appears.
  • activity: Assert that the current activity appears.
  • exists: Assert that an element exists.
  • gone: Assert that an element is gone.
  • current-app: Assert the foreground app/activity.

android-emu-agent expect idle

Assert that the UI becomes idle.

Usage:

android-emu-agent expect idle [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect text

Assert that text appears.

Usage:

android-emu-agent expect text [OPTIONS] SESSION_ID TEXT

Arguments:

  • SESSION_ID: Session ID [required]
  • TEXT: Expected text [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect activity

Assert that the current activity appears.

Usage:

android-emu-agent expect activity [OPTIONS] SESSION_ID ACTIVITY

Arguments:

  • SESSION_ID: Session ID [required]
  • ACTIVITY: Expected activity substring [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect exists

Assert that an element exists.

Fails with ERR_EXPECTATION_FAILED and a non-zero exit code when the element does not appear before the timeout. Use this to verify the result of an action.

Examples:

# Verify a screen change after tapping
android-emu-agent expect exists s-abc123 --text "Welcome" --timeout-ms 5000

# Verify by resource ID, in a script that checks the exit code
android-emu-agent expect exists s-abc123 --id com.example:id/home_root --json

Usage:

android-emu-agent expect exists [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --ref TEXT: Element ref (^g1a1)
  • --text TEXT: Text selector
  • --text-contains TEXT: Text contains selector
  • --id TEXT: Resource ID selector
  • --id-matches TEXT: Resource ID regex selector
  • --desc TEXT: Content-desc selector
  • --desc-contains TEXT: Content-desc contains selector
  • --class TEXT: Class name selector
  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect gone

Assert that an element is gone.

Usage:

android-emu-agent expect gone [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --ref TEXT: Element ref (^g1a1)
  • --text TEXT: Text selector
  • --text-contains TEXT: Text contains selector
  • --id TEXT: Resource ID selector
  • --id-matches TEXT: Resource ID regex selector
  • --desc TEXT: Content-desc selector
  • --desc-contains TEXT: Content-desc contains selector
  • --class TEXT: Class name selector
  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent expect current-app

Assert the foreground app/activity.

Usage:

android-emu-agent expect current-app [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • -p, --package TEXT: Expected package
  • -a, --activity TEXT: Expected activity substring
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent session

Session management commands

Usage:

android-emu-agent session [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • start: Start a new session on a device.
  • stop: Stop a session and release its trace and...
  • info: Show session info.
  • list: List active sessions.

android-emu-agent session start

Start a new session on a device.

Returns a session_id that every ui, action, wait, and expect command needs. Get the serial from 'device list'. Structured daemon errors exit 1, including with --json.

Examples:

# Start a session and read session_id from the JSON output
android-emu-agent session start --device emulator-5554 --json

# Stop it when the task is done
android-emu-agent session stop s-abc123

Usage:

android-emu-agent session start [OPTIONS]

Options:

  • -d, --device TEXT: Device serial [required]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent session stop

Stop a session and release its trace and debugger resources.

Usage:

android-emu-agent session stop [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent session info

Show session info.

Usage:

android-emu-agent session info [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent session list

List active sessions.

Usage:

android-emu-agent session list [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system

Android system surface commands

Usage:

android-emu-agent system [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • notifications: Notification shade commands
  • quick-settings: Quick Settings commands
  • permissions: Permission commands

android-emu-agent system notifications

Notification shade commands

Usage:

android-emu-agent system notifications [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • open: Open the notification shade.
  • close: Close the notification shade.

android-emu-agent system notifications open

Open the notification shade.

Usage:

android-emu-agent system notifications open [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system notifications close

Close the notification shade.

Usage:

android-emu-agent system notifications close [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system quick-settings

Quick Settings commands

Usage:

android-emu-agent system quick-settings [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • open: Open Quick Settings.

android-emu-agent system quick-settings open

Open Quick Settings.

Usage:

android-emu-agent system quick-settings open [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system permissions

Permission commands

Usage:

android-emu-agent system permissions [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List requested and granted package...
  • grant: Grant a runtime permission; Android...
  • revoke: Revoke a runtime permission; Android...

android-emu-agent system permissions list

List requested and granted package permissions.

Usage:

android-emu-agent system permissions list [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system permissions grant

Grant a runtime permission; Android rejections exit 1, including with --json.

Usage:

android-emu-agent system permissions grant [OPTIONS] PACKAGE PERMISSION

Arguments:

  • PACKAGE: Package name [required]
  • PERMISSION: Android permission name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent system permissions revoke

Revoke a runtime permission; Android rejections exit 1, including with --json.

Usage:

android-emu-agent system permissions revoke [OPTIONS] PACKAGE PERMISSION

Arguments:

  • PACKAGE: Package name [required]
  • PERMISSION: Android permission name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent task

Task harness commands

Usage:

android-emu-agent task [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • validate: Validate task structure and request fields...
  • run: Preflight and run a task; exit 1 if any...

android-emu-agent task validate

Validate task structure and request fields without running it.

Usage:

android-emu-agent task validate [OPTIONS] PATH

Arguments:

  • PATH: Task JSON or .aea script file [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent task run

Preflight and run a task; exit 1 if any step or verifier fails.

Usage:

android-emu-agent task run [OPTIONS] PATH

Arguments:

  • PATH: Task JSON or .aea script file [required]

Options:

  • -s, --session TEXT: Session ID override
  • --continue-on-failure: Continue after failed steps or verifiers
  • --json: Output JSON
  • --http-timeout-seconds FLOAT: HTTP response wait in seconds, not a task deadline or cancellation timeout [default: 10.0]
  • --help: Show this message and exit.

android-emu-agent trace

Agent trace recording and replay commands

Usage:

android-emu-agent trace [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • start: Start recording a trace for a session.
  • stop: Stop recording and write a trace archive.
  • status: List active traces.
  • replay: Return a dry-run replay plan from a trace...
  • export: Export a trace archive to Markdown.

android-emu-agent trace start

Start recording a trace for a session.

Usage:

android-emu-agent trace start [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • -l, --label TEXT: Optional trace label
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent trace stop

Stop recording and write a trace archive.

Explicit output paths expand ~ and are relative to your current directory. Omit --output to use the daemon's default archive directory.

Usage:

android-emu-agent trace stop [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • -o, --output TEXT: Archive output path or directory, outside the trace source directory
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent trace status

List active traces.

Usage:

android-emu-agent trace status [OPTIONS]

Options:

  • -s, --session TEXT: Filter by session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent trace replay

Return a dry-run replay plan from a trace archive.

With --until-failure, include exchanges through the first HTTP error, daemon error, or failed task result (including HTTP 200). No requests are executed. Archive paths expand ~ and are relative to your current directory, even if the daemon started elsewhere.

Usage:

android-emu-agent trace replay [OPTIONS] PATH

Arguments:

  • PATH: Trace archive path [required]

Options:

  • --until-failure: Stop the dry-run replay plan at the first failed daemon exchange
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent trace export

Export a trace archive to Markdown.

Archive and explicit output paths expand ~ and are relative to your current directory. Omit --output and use --json to read the Markdown response without writing a report file.

Usage:

android-emu-agent trace export [OPTIONS] PATH

Arguments:

  • PATH: Trace archive path [required]

Options:

  • -o, --output TEXT: Markdown output path
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent ui

UI observation commands

Usage:

android-emu-agent ui [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • snapshot: Take a UI snapshot.
  • screenshot: Capture a screenshot.
  • ground: Create screenshot-to-ref grounding...

android-emu-agent ui snapshot

Take a UI snapshot.

Modes (mutually exclusive):

  • Default (compact): Interactive elements only, JSON format
  • --full: All elements, JSON format
  • --raw: Original XML hierarchy string

Structured daemon errors retain their JSON output and exit 1 in every mode.

Examples:

# Compact snapshot: interactive elements with ^refs
android-emu-agent ui snapshot s-abc123

# Readable text output while exploring a screen
android-emu-agent ui snapshot s-abc123 --format text

# Include labels and containers when a target is missing
android-emu-agent ui snapshot s-abc123 --full

Usage:

android-emu-agent ui snapshot [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --full: Include all nodes (JSON)
  • --raw: Return raw XML hierarchy
  • -f, --format TEXT: Output format: json|text [default: json]
  • --help: Show this message and exit.

android-emu-agent ui screenshot

Capture a screenshot.

Usage:

android-emu-agent ui screenshot [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --pull: Copy screenshot to local path
  • -o, --output TEXT: Output path (file or directory)
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent ui ground

Create screenshot-to-ref grounding metadata from the latest snapshot.

Usage:

android-emu-agent ui ground [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --ref TEXT: Limit to one or more refs
  • --screenshot / --no-screenshot: Capture a screenshot alongside grounding metadata [default: screenshot]
  • --pull: Copy grounding JSON to local path
  • -o, --output TEXT: Output path (file or directory)
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action

Action execution commands

Usage:

android-emu-agent action [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • tap: Tap an element.
  • long-tap: Long tap an element.
  • set-text: Replace the existing text on an element...
  • clear: Clear text.
  • back: Press back.
  • home: Press home.
  • recents: Press recents.
  • swipe: Perform swipe gesture.
  • scroll: Scroll in a direction (alias for swipe).

android-emu-agent action tap

Tap an element.

Take a fresh snapshot first and copy the complete ^ref from it. Refs are generation-scoped, so re-snapshot after every action. Use a selector when no stable ref is available.

Examples:

# Tap a ref from the latest snapshot
android-emu-agent action tap s-abc123 ^g1a1

# Tap by visible text, falling back to a resource ID
android-emu-agent action tap s-abc123 'text:"Sign in" || id:com.example:id/login_btn'

# Tap by content description
android-emu-agent action tap s-abc123 'desc:"Open navigation"'

Usage:

android-emu-agent action tap [OPTIONS] SESSION_ID REF

Arguments:

  • SESSION_ID: Session ID [required]
  • REF: Element ^ref or selector [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action long-tap

Long tap an element.

Usage:

android-emu-agent action long-tap [OPTIONS] SESSION_ID REF

Arguments:

  • SESSION_ID: Session ID [required]
  • REF: Element ^ref or selector [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action set-text

Replace the existing text on an element (an empty string clears it).

Tap the field and re-snapshot before setting text, because focusing a field can change the UI. Press back afterwards to dismiss the keyboard.

Examples:

# Fill an email field identified by a ref
android-emu-agent action set-text s-abc123 ^g2a1 "user@example.com"

# Fill a field located by resource ID
android-emu-agent action set-text s-abc123 id:com.example:id/password "secret123"

Usage:

android-emu-agent action set-text [OPTIONS] SESSION_ID REF TEXT

Arguments:

  • SESSION_ID: Session ID [required]
  • REF: Element ^ref or selector [required]
  • TEXT: Text to set [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action clear

Clear text.

Usage:

android-emu-agent action clear [OPTIONS] SESSION_ID REF

Arguments:

  • SESSION_ID: Session ID [required]
  • REF: Element ^ref or selector [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action back

Press back.

Usage:

android-emu-agent action back [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action home

Press home.

Usage:

android-emu-agent action home [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action recents

Press recents.

Usage:

android-emu-agent action recents [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action swipe

Perform swipe gesture.

Swipe direction is the finger movement: 'up' moves content up, revealing what is below.

Examples:

# Scroll a screen down to reveal lower content
android-emu-agent action swipe up --session s-abc123

# Swipe inside a specific list rather than the whole screen
android-emu-agent action swipe up --session s-abc123 --in id:com.example:id/recycler

# Shorter, slower swipe for a carousel
android-emu-agent action swipe left --session s-abc123 --distance 0.5 --duration 600

Usage:

android-emu-agent action swipe [OPTIONS] DIRECTION

Arguments:

  • DIRECTION: Direction: up, down, left, right [required]

Options:

  • -s, --session TEXT: Session ID [required]
  • --in TEXT: Container ^ref or selector; supports || fallbacks
  • -d, --distance FLOAT: Swipe distance (0.0-1.0) [default: 0.8]
  • --duration INTEGER: Swipe duration in ms [default: 300]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent action scroll

Scroll in a direction (alias for swipe).

Usage:

android-emu-agent action scroll [OPTIONS] DIRECTION

Arguments:

  • DIRECTION: Direction: up, down, left, right [required]

Options:

  • -s, --session TEXT: Session ID [required]
  • --in TEXT: Container ^ref or selector; supports || fallbacks
  • -d, --distance FLOAT: Scroll distance (0.0-1.0) [default: 0.8]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent wait

Wait/synchronization commands

Usage:

android-emu-agent wait [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • idle: Wait for UI idle.
  • activity: Wait for an activity to appear.
  • text: Wait for text to appear.
  • exists: Wait for element to exist.
  • gone: Wait for element to disappear.

android-emu-agent wait idle

Wait for UI idle.

Use this after an action that starts an animation or a screen transition, instead of sleeping. Default timeout is 10000 ms.

Examples:

# Let a transition settle before the next snapshot
android-emu-agent wait idle s-abc123 --timeout-ms 5000

Usage:

android-emu-agent wait idle [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent wait activity

Wait for an activity to appear.

Usage:

android-emu-agent wait activity [OPTIONS] SESSION_ID ACTIVITY

Arguments:

  • SESSION_ID: Session ID [required]
  • ACTIVITY: Activity substring [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent wait text

Wait for text to appear.

Use this when the next screen is identified by its content. This waits, but does not assert; use 'expect' commands for pass/fail checks.

Examples:

# Wait for a screen that appears after sign-in
android-emu-agent wait text s-abc123 "Welcome" --timeout-ms 15000

Usage:

android-emu-agent wait text [OPTIONS] SESSION_ID TEXT

Arguments:

  • SESSION_ID: Session ID [required]
  • TEXT: Text to wait for [required]

Options:

  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent wait exists

Wait for element to exist.

Usage:

android-emu-agent wait exists [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --ref TEXT: Element ref (^g1a1)
  • --text TEXT: Text selector
  • --text-contains TEXT: Text contains selector
  • --id TEXT: Resource ID selector
  • --id-matches TEXT: Resource ID regex selector
  • --desc TEXT: Content-desc selector
  • --desc-contains TEXT: Content-desc contains selector
  • --class TEXT: Class name selector
  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent wait gone

Wait for element to disappear.

Usage:

android-emu-agent wait gone [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --ref TEXT: Element ref (^g1a1)
  • --text TEXT: Text selector
  • --text-contains TEXT: Text contains selector
  • --id TEXT: Resource ID selector
  • --id-matches TEXT: Resource ID regex selector
  • --desc TEXT: Content-desc selector
  • --desc-contains TEXT: Content-desc contains selector
  • --class TEXT: Class name selector
  • --timeout-ms INTEGER: Timeout in ms
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app

App management commands

Usage:

android-emu-agent app [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • install: Install an APK on the target device.
  • uninstall: Uninstall a package from the target device.
  • reset: Clear app data for a package; fail if...
  • launch: Launch an app; fail if Android rejects the...
  • force-stop: Force stop an app.
  • deeplink: Open a deeplink URI; fail if Android...
  • intent: Launch an explicit or implicit intent;...
  • list: List installed packages.
  • current: Show current foreground app/activity.
  • task-stack: Show current task stack.
  • resolve-intent: Resolve an intent target without launching...

android-emu-agent app install

Install an APK on the target device.

Target the device by serial or by an active session. Relative APK paths are interpreted from your current directory, even if the daemon started elsewhere.

Examples:

# Install onto a specific device
android-emu-agent app install ./app-debug.apk --device emulator-5554

# Install for an active session and pre-grant runtime permissions
android-emu-agent app install ./app-debug.apk --session s-abc123 --grant-permissions

Usage:

android-emu-agent app install [OPTIONS] APK_PATH

Arguments:

  • APK_PATH: Local APK path [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --replace / --no-replace: Replace existing app [default: replace]
  • --grant-permissions: Grant all runtime permissions
  • --allow-downgrade: Allow version-code downgrade
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app uninstall

Uninstall a package from the target device.

Usage:

android-emu-agent app uninstall [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --keep-data: Keep app data and cache directories
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app reset

Clear app data for a package; fail if Android rejects the reset.

Usage:

android-emu-agent app reset [OPTIONS] SESSION_ID PACKAGE

Arguments:

  • SESSION_ID: Session ID [required]
  • PACKAGE: Package name [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app launch

Launch an app; fail if Android rejects the activity start.

Follow this with a wait so the app is ready before the first snapshot. Activity names may be bare (MainActivity), package-relative (.ui.MainActivity), or fully qualified (org.example.ui.MainActivity). Fully qualified names are preserved even when the activity's class namespace differs from the app package.

Examples:

# Launch and let the first screen settle
android-emu-agent app launch s-abc123 com.example.app
android-emu-agent wait idle s-abc123 --timeout-ms 10000

# Launch a specific activity
android-emu-agent app launch s-abc123 com.example.app --activity .DebugActivity

# Launch suspended, ready for 'debug attach'
android-emu-agent app launch s-abc123 com.example.app --wait-debugger

Usage:

android-emu-agent app launch [OPTIONS] SESSION_ID PACKAGE

Arguments:

  • SESSION_ID: Session ID [required]
  • PACKAGE: Package name [required]

Options:

  • -a, --activity TEXT: Activity name
  • --wait-debugger: Start with -D and wait for debugger
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app force-stop

Force stop an app.

Usage:

android-emu-agent app force-stop [OPTIONS] SESSION_ID PACKAGE

Arguments:

  • SESSION_ID: Session ID [required]
  • PACKAGE: Package name [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

Open a deeplink URI; fail if Android cannot start a matching activity.

Usage:

android-emu-agent app deeplink [OPTIONS] SESSION_ID URI

Arguments:

  • SESSION_ID: Session ID [required]
  • URI: URI to open [required]

Options:

  • --wait-debugger: Start with -D and wait for debugger
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app intent

Launch an explicit or implicit intent; fail if Android rejects the start.

Usage:

android-emu-agent app intent [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • -a, --action TEXT: Intent action
  • --data TEXT: Intent data URI
  • -n, --component TEXT: Explicit component (package/.Activity)
  • -p, --package TEXT: Target package
  • --wait-debugger: Start with -D and wait for debugger
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app list

List installed packages.

Usage:

android-emu-agent app list [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --scope TEXT: all|system|third-party [default: all]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app current

Show current foreground app/activity.

Usage:

android-emu-agent app current [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app task-stack

Show current task stack.

Usage:

android-emu-agent app task-stack [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent app resolve-intent

Resolve an intent target without launching it.

Usage:

android-emu-agent app resolve-intent [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -s, --session TEXT: Session ID
  • -a, --action TEXT: Intent action
  • --data TEXT: Intent data URI
  • -n, --component TEXT: Explicit component (package/.Activity)
  • -p, --package TEXT: Target package
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent artifact

Artifact and debugging commands

Usage:

android-emu-agent artifact [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • save-snapshot: Save the last snapshot to disk.
  • screenshot: Capture a screenshot artifact.
  • logs: Pull logcat logs.
  • bundle: Create a debug bundle.

android-emu-agent artifact save-snapshot

Save the last snapshot to disk.

Usage:

android-emu-agent artifact save-snapshot [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent artifact screenshot

Capture a screenshot artifact.

Usage:

android-emu-agent artifact screenshot [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --pull: Copy screenshot to local path
  • -o, --output TEXT: Output path (file or directory)
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent artifact logs

Pull logcat logs.

Failed logcat captures report an error, not a successful artifact path.

ISO 8601 and relative since filters preserve their absolute instant across host and device timezones. T-separated ISO values without an offset mean UTC. Native space-separated logcat timestamps remain device-local; integers remain line counts.

Usage:

android-emu-agent artifact logs [OPTIONS] [SESSION_ID]

Arguments:

  • [SESSION_ID]: Session ID

Options:

  • -s, --session TEXT: Session ID
  • -p, --package, --app TEXT: Filter to logs for one app package
  • --level TEXT: Deprecated alias for --type (v|d|i|w|e|f|s or verbose/debug/...)
  • --type TEXT: Log type (errors, warnings, info, debug, verbose, fatal, silent)
  • --since TEXT: Since filter: line count, logcat timestamp, ISO 8601, or relative (e.g. '10m ago')
  • --follow: Unsupported compatibility flag; use adb logcat for live streaming
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent artifact bundle

Create a debug bundle.

Usage:

android-emu-agent artifact bundle [OPTIONS] SESSION_ID

Arguments:

  • SESSION_ID: Session ID [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent emulator

Emulator management commands

Usage:

android-emu-agent emulator [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list-avds: List available Android Virtual Devices.
  • start: Start an AVD using the Android emulator CLI.
  • stop: Stop a running emulator instance.
  • snapshot: Emulator snapshot commands

android-emu-agent emulator list-avds

List available Android Virtual Devices.

Usage:

android-emu-agent emulator list-avds [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent emulator start

Start an AVD using the Android emulator CLI.

Waits for boot by default, so the command returns only once Android is ready for a session. Get AVD names from 'emulator list-avds'. A fixed --port already listed by ADB is rejected before launch, including with --no-wait-boot; the existing emulator is left untouched.

Examples:

# Boot an AVD and wait until it is ready
android-emu-agent emulator start Pixel_8_API_34

# Start from a known snapshot for deterministic runs
android-emu-agent emulator start Pixel_8_API_34 --snapshot post-onboarding

# Clean userdata, headless, for CI
android-emu-agent emulator start Pixel_8_API_34 --wipe-data --no-window

Usage:

android-emu-agent emulator start [OPTIONS] AVD_NAME

Arguments:

  • AVD_NAME: AVD name from 'emulator -list-avds' [required]

Options:

  • --snapshot TEXT: Snapshot name (letters, digits, dots, underscores, or hyphens)
  • --wipe-data: Wipe userdata before boot
  • --cold-boot: Start without loading Quick Boot or snapshot state
  • --no-snapshot-save: Do not save Quick Boot state on exit
  • --read-only: Start the AVD in read-only mode
  • --no-window: Run the emulator headless
  • --port INTEGER: Even console port from 5554 through 5584
  • --wait-boot / --no-wait-boot: Wait for boot before returning [default: wait-boot]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent emulator stop

Stop a running emulator instance.

Usage:

android-emu-agent emulator stop [OPTIONS] SERIAL

Arguments:

  • SERIAL: Running emulator serial (e.g., emulator-5554) [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent emulator snapshot

Emulator snapshot commands

Usage:

android-emu-agent emulator snapshot [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • save: Save emulator snapshot, allowing up to 60...
  • restore: Restore emulator snapshot and restart by...

android-emu-agent emulator snapshot save

Save emulator snapshot, allowing up to 60 seconds for the daemon response.

Usage:

android-emu-agent emulator snapshot save [OPTIONS] SERIAL NAME

Arguments:

  • SERIAL: Emulator serial (e.g., emulator-5554) [required]
  • NAME: Snapshot name (letters, digits, dots, underscores, or hyphens) [required]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent emulator snapshot restore

Restore emulator snapshot and restart by default.

Allow up to 180 seconds for the daemon response, or 60 seconds with --no-restart. These HTTP limits do not change the emulator console deadlines.

Usage:

android-emu-agent emulator snapshot restore [OPTIONS] SERIAL NAME

Arguments:

  • SERIAL: Emulator serial (e.g., emulator-5554) [required]
  • NAME: Snapshot name (letters, digits, dots, underscores, or hyphens) [required]

Options:

  • --restart / --no-restart: Restart after loading the snapshot [default: restart]
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability

Reliability and forensics commands

Usage:

android-emu-agent reliability [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • exit-info: Show ApplicationExitInfo for a package.
  • bugreport: Capture a system bugreport.
  • events: Dump ActivityManager events log.
  • profile: Collect a bounded app performance and...
  • perfetto: Capture a bounded native Perfetto trace...
  • simpleperf: Capture a bounded native simpleperf CPU...
  • screenrecord: Capture a bounded screen recording artifact.
  • background: Check background restrictions and standby...
  • last-anr: Show the last ANR summary from...
  • jobscheduler: Inspect JobScheduler constraints for a...
  • process: Inspect process state for a package.
  • meminfo: Dump memory info for a package.
  • gfxinfo: Dump graphics/frame timing info for a...
  • compile: Reset or force package compilation.
  • always-finish: Toggle always-finish-activities developer...
  • run-as-ls: List app-private files for debuggable apps...
  • dumpheap: Dump a heap profile and pull it locally.
  • sigquit: Send SIGQUIT to dump thread stacks.
  • oom-adj: Adjust oom_score_adj to make a process...
  • trim-memory: Send a trim memory signal to the app.
  • dropbox: DropBoxManager commands
  • pull: Pull protected artifacts (rooted/emulator)

android-emu-agent reliability exit-info

Show ApplicationExitInfo for a package.

Usage:

android-emu-agent reliability exit-info [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability bugreport

Capture a system bugreport.

Usage:

android-emu-agent reliability bugreport [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --output TEXT: Output filename (.zip)
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability events

Dump ActivityManager events log.

Usage:

android-emu-agent reliability events [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --pattern TEXT: Regex filter for events
  • --package TEXT: Filter for package name
  • --since TEXT: Logcat -t value: timestamp (MM-DD HH:MM:SS.mmm) or line count
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability profile

Collect a bounded app performance and reliability profile.

Usage:

android-emu-agent reliability profile [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --since TEXT: Logcat -t value for reliability events: timestamp or line count
  • --raw: Include raw diagnostic dumps
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability perfetto

Capture a bounded native Perfetto trace artifact.

Usage:

android-emu-agent reliability perfetto [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --duration INTEGER: Trace duration in seconds [default: 10]
  • --categories TEXT: Perfetto data source list
  • --output TEXT: Output filename
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability simpleperf

Capture a bounded native simpleperf CPU profile artifact.

Usage:

android-emu-agent reliability simpleperf [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --duration INTEGER: Record duration in seconds [default: 10]
  • --output TEXT: Output .data filename
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability screenrecord

Capture a bounded screen recording artifact.

Usage:

android-emu-agent reliability screenrecord [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --duration INTEGER: Recording duration in seconds [default: 10]
  • --bit-rate INTEGER: Screenrecord bit rate
  • --output TEXT: Output .mp4 filename
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability background

Check background restrictions and standby bucket.

Usage:

android-emu-agent reliability background [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability last-anr

Show the last ANR summary from ActivityManager.

Usage:

android-emu-agent reliability last-anr [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability jobscheduler

Inspect JobScheduler constraints for a package.

Usage:

android-emu-agent reliability jobscheduler [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability process

Inspect process state for a package.

Usage:

android-emu-agent reliability process [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability meminfo

Dump memory info for a package.

Usage:

android-emu-agent reliability meminfo [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability gfxinfo

Dump graphics/frame timing info for a package.

Usage:

android-emu-agent reliability gfxinfo [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability compile

Reset or force package compilation.

Usage:

android-emu-agent reliability compile [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • --mode TEXT: reset|speed [default: reset]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability always-finish

Toggle always-finish-activities developer setting.

Usage:

android-emu-agent reliability always-finish [OPTIONS] STATE

Arguments:

  • STATE: on|off [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability run-as-ls

List app-private files for debuggable apps using run-as.

Usage:

android-emu-agent reliability run-as-ls [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • --path TEXT: Relative path under app data [default: files/]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability dumpheap

Dump a heap profile and pull it locally.

Usage:

android-emu-agent reliability dumpheap [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • --keep-remote: Keep heap on device
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability sigquit

Send SIGQUIT to dump thread stacks.

Usage:

android-emu-agent reliability sigquit [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability oom-adj

Adjust oom_score_adj to make a process more killable (root required).

Usage:

android-emu-agent reliability oom-adj [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • --score INTEGER: oom_score_adj value [default: 1000]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability trim-memory

Send a trim memory signal to the app.

Usage:

android-emu-agent reliability trim-memory [OPTIONS] PACKAGE

Arguments:

  • PACKAGE: Package name [required]

Options:

  • --level TEXT: Trim level constant [default: RUNNING_CRITICAL]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability dropbox

DropBoxManager commands

Usage:

android-emu-agent reliability dropbox [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List DropBoxManager entries.
  • print: Print a DropBoxManager entry.

android-emu-agent reliability dropbox list

List DropBoxManager entries.

Usage:

android-emu-agent reliability dropbox list [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --package TEXT: Filter for package name
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability dropbox print

Print a DropBoxManager entry.

Usage:

android-emu-agent reliability dropbox print [OPTIONS] TAG

Arguments:

  • TAG: DropBox tag (e.g., data_app_crash) [required]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability pull

Pull protected artifacts (rooted/emulator)

Usage:

android-emu-agent reliability pull [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • anr: Pull /data/anr (root required).
  • tombstones: Pull /data/tombstones (root required).
  • dropbox: Pull /data/system/dropbox (root required).

android-emu-agent reliability pull anr

Pull /data/anr (root required).

Usage:

android-emu-agent reliability pull anr [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability pull tombstones

Pull /data/tombstones (root required).

Usage:

android-emu-agent reliability pull tombstones [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent reliability pull dropbox

Pull /data/system/dropbox (root required).

Usage:

android-emu-agent reliability pull dropbox [OPTIONS]

Options:

  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file

File transfer commands

Usage:

android-emu-agent file [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • push: Push a local file to shared storage (sdcard).
  • pull: Pull a file from shared storage (sdcard).
  • find: Find files/folders visible to shell or root.
  • list: List files/folders visible to shell or root.
  • app: App-private files (root or run-as for...

android-emu-agent file push

Push a local file to shared storage (sdcard).

Local paths expand ~ and are relative to your current directory, even if the daemon started elsewhere.

Usage:

android-emu-agent file push [OPTIONS] LOCAL_PATH

Arguments:

  • LOCAL_PATH: Local file or directory [required]

Options:

  • --remote TEXT: Remote path (default: /sdcard/Download/<name>)
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file pull

Pull a file from shared storage (sdcard).

Explicit local paths expand ~ and are relative to your current directory. Omit --local to save in the daemon's file artifacts directory.

Usage:

android-emu-agent file pull [OPTIONS] REMOTE_PATH

Arguments:

  • REMOTE_PATH: Remote file or directory [required]

Options:

  • --local TEXT: Local output path
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file find

Find files/folders visible to shell or root.

Usage:

android-emu-agent file find [OPTIONS] PATH

Arguments:

  • PATH: Root directory to search [required]

Options:

  • --name TEXT: Filename glob (e.g. .db or cache) [required]
  • --type TEXT: file|dir|any [default: any]
  • --max-depth INTEGER: Max directory depth [default: 4]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file list

List files/folders visible to shell or root.

Usage:

android-emu-agent file list [OPTIONS] PATH

Arguments:

  • PATH: Directory to list [required]

Options:

  • --type TEXT: file|dir|any [default: any]
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file app

App-private files (root or run-as for debuggable apps)

Usage:

android-emu-agent file app [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • push: Push into app-private storage via root or...
  • pull: Pull from app-private storage via root or...

android-emu-agent file app push

Push into app-private storage via root or run-as.

Local paths expand ~ and are relative to your current directory, even if the daemon started elsewhere.

When the resolved destination is an existing directory, copy inside it using the original source name, not a temporary staging name.

Usage:

android-emu-agent file app push [OPTIONS] PACKAGE LOCAL_PATH

Arguments:

  • PACKAGE: Package name [required]
  • LOCAL_PATH: Local file or directory [required]

Options:

  • --remote TEXT: App data path (default: files/<name>)
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent file app pull

Pull from app-private storage via root or run-as.

Explicit local paths expand ~ and are relative to your current directory. Omit --local to save in the daemon's file artifacts directory.

Usage:

android-emu-agent file app pull [OPTIONS] PACKAGE REMOTE_PATH

Arguments:

  • PACKAGE: Package name [required]
  • REMOTE_PATH: App data path (relative or absolute) [required]

Options:

  • --local TEXT: Local output path
  • -d, --device TEXT: Device serial
  • -s, --session TEXT: Session ID
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent skills

Install the bundled Agent Skill into coding agent directories

Usage:

android-emu-agent skills [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • install: Install the bundled Agent Skill for a...
  • list: Show where the bundled Agent Skill is...
  • path: Print the path to the bundled Agent Skill...

android-emu-agent skills install

Install the bundled Agent Skill for a coding agent.

Safe to re-run: it replaces a previous install and drops files removed upstream. Re-run it after upgrading the CLI. A source checkout is symlinked so local edits apply immediately; an installed package is copied.

Examples:

# Install for Claude Code, or for Codex
android-emu-agent skills install --agent claude
android-emu-agent skills install --agent codex

# Install into a project so the team shares it
android-emu-agent skills install --agent claude --project

# Install for any other agent
android-emu-agent skills install --dir ~/.config/some-agent/skills

# Replace a skill directory this CLI did not create
android-emu-agent skills install --force

Usage:

android-emu-agent skills install [OPTIONS]

Options:

  • --agent [claude|codex|vscode]: Target coding agent [default: claude]
  • --project: Install into the current project instead of the home directory
  • --dir TEXT: Install into an explicit directory (overrides --agent/--project)
  • --copy: Copy files even from a source checkout
  • --symlink: Symlink a source checkout (dev flow)
  • --force: Replace an existing skill directory
  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent skills list

Show where the bundled Agent Skill is installed.

Usage:

android-emu-agent skills list [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.

android-emu-agent skills path

Print the path to the bundled Agent Skill files.

Usage:

android-emu-agent skills path [OPTIONS]

Options:

  • --json: Output JSON
  • --help: Show this message and exit.