Ironbee Android Devtools CLI

IronBee Android DevTools CLI

Command-line interface for driving an Android emulator over a single bridge — adb. Part of IronBee DevTools. Collects the same data categories as the other platforms — screenshots, video, logs (logcat), the UI/accessibility tree, and performance metrics — and drives the UI via taps, swipes, key events, text input, and deep links.

It also captures HTTP(S) traffic in-process via a Frida OkHttp hook — no proxy, no CA install, certificate pinning bypassed — and can mock or intercept those requests and pin a W3C trace id across the app's API calls. This path covers OkHttp-based stacks (React Native/Expo, Retrofit, Android HttpURLConnection) over HTTP/1.1 and HTTP/2; native / Flutter / Cronet are not covered. It provisions frida-server on first use, so it needs a rootable emulator image (Google APIs or AOSP — not a Play Store image).

Scope: Android emulator only. Physical devices and on-device debugging (tracepoints/logpoints/etc.) are out of scope. For browser UIs use ../ironbee-browser-devtools-cli/SKILL.md; for Node.js processes use ../ironbee-node-devtools-cli/SKILL.md; for server APIs use ../ironbee-backend-devtools-cli/SKILL.md.

Installation

# Install this skill (skills.sh)
npx skills add ironbee-ai/ironbee-devtools-skills

# Install the CLI binary (same package as the rest of IronBee DevTools)
npm install -g @ironbee-ai/devtools

Requires Node.js >= 22.16.0 (engines.node in the package): the backend db domain's SQLite engine and the FTS5 scenario-search strategy run on Node's built-in node:sqlite, which replaced the last native dependency.

You also need the Android SDK with adb (and emulator for managed mode). The CLI resolves them from ANDROID_HOME / ANDROID_SDK_ROOT or the OS-default SDK location (macOS ~/Library/Android/sdk, Windows %LOCALAPPDATA%\Android\Sdk, Linux ~/Android/Sdk). Override with ANDROID_ADB_PATH / ANDROID_EMULATOR_PATH if they live elsewhere.

Port note

All IronBee DevTools CLIs default to daemon port 2020. To run the Android daemon alongside browser (2020), node (2021), and backend (2022) daemons, start it on its own port and pass --port to every Android CLI call:

PLATFORM=android ironbee-android-devtools-cli daemon start --port 2023
ironbee-android-devtools-cli --port 2023 device list-targets

Quick Start

# 1. Start daemon (if not running)
ironbee-android-devtools-cli daemon start

# 2. List connectable targets (running emulators + defined AVDs)
ironbee-android-devtools-cli --json device list-targets

# 3. Connect (attach to a running emulator by serial)
ironbee-android-devtools-cli --session-id my-app device connect --serial emulator-5554

# 4. Launch the app under test
ironbee-android-devtools-cli --session-id my-app device launch-app --package-name com.example.app

# 5. Read the UI tree (structured, gives refs)
ironbee-android-devtools-cli --session-id my-app --json a11y take-ui-snapshot

# 6. Tap an element by ref, then re-read to verify
ironbee-android-devtools-cli --session-id my-app interaction tap --ref e5
ironbee-android-devtools-cli --session-id my-app --json a11y take-ui-snapshot

Global Options

AI Agent Recommended:

ironbee-android-devtools-cli --json --quiet --session-id "android-session" <command>

Verification model (raw read → trigger → verify)

There is no assert tool. Trigger an action (tap, launch an app, deep link), then read raw observations and decide for yourself. Default to the UI tree (a11y take-ui-snapshot) — it is structured, gives stable refs, and is the cheap way to confirm state. Do NOT screenshot after every action: content take-screenshot is heavy (capture + encode + upload). Take one only when the UI tree is insufficient (visual-only state: rendering, images, layout, custom-drawn views) or once to confirm after a screen change.

Emulator performance numbers are NOT representative of a real device (the emulator runs on the host CPU) — use o11y get-perf-metrics comparatively only.

Tool Domains

Jira / Linear are platform-agnostic shared issue-tracker domains (like scenario/execute) — registered on every platform CLI, but only when credentials are configured: jira needs JIRA_BASE_URL plus JIRA_EMAIL + JIRA_API_TOKEN (Cloud) or JIRA_PAT (Server/DC); linear needs LINEAR_API_KEY. Without creds the jira / linear subcommand group does not exist. Write tools (add-comment, attach-file, create/update-issue, transition-issue / set-state, link-issue, report-verification) additionally require JIRA_WRITE_ENABLED=true / LINEAR_WRITE_ENABLED=true (default off ⇒ read-only intake tools only). Close the loop after a verification run: ironbee-android-devtools-cli jira report-verification --key PROJ-123 --result pass --report "..." --artifacts ./artifacts/evidence.png (linear: same shape with --state instead of --transition). See jira / linear.

Full scenario surface on this CLI. The Android CLI registers the scenario CRUD subcommands (scenario-add / scenario-update / scenario-delete / scenario-list / scenario-search / scenario-recorded-actions) plus a direct scenario-run subcommand under the default group — e.g. ironbee-android-devtools-cli default scenario-run --name <name> (with --args / --param key=value / --timeout-ms, and --resume / --step-by-step / --refresh for step-based scenarios). scenario-run is also reachable from inside run execute via await callTool('scenario-run', { name: '...' }). See the scenario reference. Inside a scenario script only callTool is available (no page binding — that is browser-only).

Connection model (one target per session)

Connect with device connect. Launch modes:

Target selection order: explicit --serial > the single running emulator > booting --avd-name (or ANDROID_DEFAULT_AVD). When multiple emulators are running and no serial/avd is given, connect fails and lists targets — enumerate them first with device list-targets.

CLI Management Commands

Daemon

ironbee-android-devtools-cli daemon status
ironbee-android-devtools-cli daemon start
ironbee-android-devtools-cli daemon stop
ironbee-android-devtools-cli daemon restart
ironbee-android-devtools-cli daemon info

Session

ironbee-android-devtools-cli session list
ironbee-android-devtools-cli session info <session-id>
ironbee-android-devtools-cli session delete <session-id>

Tools

ironbee-android-devtools-cli tools list
ironbee-android-devtools-cli tools search <query>
ironbee-android-devtools-cli tools info <tool-name>

Config

ironbee-android-devtools-cli config

Android-specific configuration

Examples

Trigger-and-verify a login flow

SESSION="--session-id login"

ironbee-android-devtools-cli $SESSION device connect --serial emulator-5554
ironbee-android-devtools-cli $SESSION device launch-app --package-name com.example.app

# Read the UI tree and find the username field
ironbee-android-devtools-cli $SESSION --json a11y take-ui-snapshot

# Type into fields, then tap login
ironbee-android-devtools-cli $SESSION interaction input-text --resource-id "com.example.app:id/username" --text "alice"
ironbee-android-devtools-cli $SESSION interaction input-text --resource-id "com.example.app:id/password" --text "secret"
ironbee-android-devtools-cli $SESSION interaction tap --text "Sign in"

# Wait for traffic to settle, then re-read to confirm
ironbee-android-devtools-cli $SESSION sync wait-for-network-idle
ironbee-android-devtools-cli $SESSION --json a11y take-ui-snapshot

Correlate a UI action with logcat

SESSION="--session-id logs"

# Start following logcat, capture the followId
ironbee-android-devtools-cli $SESSION --json o11y log-follow

# Trigger the action
ironbee-android-devtools-cli $SESSION interaction tap --text "Checkout"

# Drain the buffered lines, filtered to errors
ironbee-android-devtools-cli $SESSION --json o11y log-get-followed --follow-id <id> --level ERROR

Capture (and trace-correlate) app HTTP traffic

Network capture is forward-looking — start it, then trigger traffic, then read. Requires a rootable emulator image.

SESSION="--session-id net"

ironbee-android-devtools-cli $SESSION device connect --serial emulator-5554
ironbee-android-devtools-cli $SESSION device launch-app --package-name com.example.app

# Pin a trace id the backend can later be searched by, then start capture
ironbee-android-devtools-cli $SESSION --json o11y new-trace-id
ironbee-android-devtools-cli $SESSION --json o11y get-http-requests   # first call starts capture

# Trigger traffic in the app, then read what was captured (headers/bodies opt-in)
ironbee-android-devtools-cli $SESSION interaction tap --text "Refresh"
ironbee-android-devtools-cli $SESSION --json o11y get-http-requests --url-pattern "*/api/*" --include-headers --include-bodies

Mock or intercept a response

# Short-circuit an endpoint with a canned response
ironbee-android-devtools-cli --json stub mock-http-response --url-glob "https://api.example.com/me" --status 200 --body '{"name":"Alice"}'

# Or mutate an outgoing request's headers
ironbee-android-devtools-cli --json stub intercept-http-request --url-glob "https://api.example.com/*" --set-headers '{"X-Test":"1"}'

ironbee-android-devtools-cli --json stub list
ironbee-android-devtools-cli stub clear

Batch with execute

# Run multiple tool calls in one request — Android exposes only callTool (no `page`)
ironbee-android-devtools-cli run execute --code "await callTool('device_status', {}, true); await callTool('a11y_take-ui-snapshot', {}, true);"

Interactive Mode

ironbee-android-devtools-cli interactive

Shell Completions

eval "$(ironbee-android-devtools-cli completion bash)"
eval "$(ironbee-android-devtools-cli completion zsh)"