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 commandsdebug: Debugger commands (JDI Bridge)device: Device management commandsexpect: Expectation and assertion commandssession: Session management commandssystem: Android system surface commandstask: Task harness commandstrace: Agent trace recording and replay commandsui: UI observation commandsaction: Action execution commandswait: Wait/synchronization commandsapp: App management commandsartifact: Artifact and debugging commandsemulator: Emulator management commandsreliability: Reliability and forensics commandsfile: File transfer commandsskills: 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 commandsbreak-exception: Exception breakpoint commandsmapping: 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 commandsquick-settings: Quick Settings commandspermissions: 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.
android-emu-agent app deeplink
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 commandspull: 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.