ADB Actions

Actions

ADB shell-based device actions that bypass the accessibility service

Access these methods through agent.actions.adb. These actions use ADB shell commands instead of the accessibility service, providing an alternative when the accessibility service is unavailable or unreliable.

Available since: App version 2.141 (153)

`tap()`

TypeScript

tap(x: number, y: number): Promise<void>

Performs a single tap at the specified screen coordinates using ADB shell input.

Parameters

Name	Type	Description
`x`	`number`	X coordinate on screen
`y`	`number`	Y coordinate on screen

Returns

Promise<void>Resolves when tap is complete

Examples

Simple tap

TypeScript

await agent.actions.adb.tap(100, 200);

`hold()`

TypeScript

hold(x: number, y: number, duration: number): Promise<void>

Performs a long press at the specified coordinates using ADB shell input.

Parameters

Name	Type	Description
`x`	`number`	X coordinate on screen
`y`	`number`	Y coordinate on screen
`duration`	`number`	Hold duration in milliseconds

Returns

Promise<void>Resolves when hold is complete

Examples

Long press for 1 second

TypeScript

await agent.actions.adb.hold(500, 500, 1000);

`swipe()`

TypeScript

swipe(x1: number, y1: number, x2: number, y2: number, duration: number): Promise<void>

Performs a swipe gesture from one point to another using ADB shell input.

Parameters

Name	Type	Description
`x1`	`number`	Starting X coordinate
`y1`	`number`	Starting Y coordinate
`x2`	`number`	Ending X coordinate
`y2`	`number`	Ending Y coordinate
`duration`	`number`	Duration in milliseconds

Returns

Promise<void>Resolves when swipe is complete

Examples

Swipe up

TypeScript

await agent.actions.adb.swipe(500, 1500, 500, 500, 300);

`swipePoly()`

TypeScript

swipePoly(startX: number, startY: number, sequence: {x: number, y: number, duration?: number}[], duration: number): Promise<void>

Swipes through multiple points sequentially using ADB shell input. Each segment is executed as a separate ADB swipe command. Optionally supports per-segment duration.

Parameters

Name	Type	Description
`startX`	`number`	Starting X coordinate
`startY`	`number`	Starting Y coordinate
`sequence`	`{x, y, duration?}[]`	Array of points to swipe through. Each point can optionally specify its own duration in ms.
`duration`	`number`	Total duration in ms. Divided equally among segments if per-point durations are not specified. Use 0 for default (~500ms total).

Returns

Promise<void>Resolves when all swipe segments are complete

Examples

Draw an L shape

TypeScript

await agent.actions.adb.swipePoly(100, 100, [
  { x: 100, y: 500 },
  { x: 400, y: 500 }
], 600);

With per-segment duration

TypeScript

await agent.actions.adb.swipePoly(100, 100, [
  { x: 100, y: 500, duration: 200 },
  { x: 400, y: 500, duration: 300 }
], 0);

`doubleTap()`

TypeScript

doubleTap(x: number, y: number, interval?: number): Promise<void>

Performs a double tap at the specified coordinates using ADB shell input.

Parameters

Name	Type	Description
`x`	`number`	X coordinate on screen
`y`	`number`	Y coordinate on screen
`interval?`	`number`	Interval between taps in ms (default: 100)

Returns

Promise<void>Resolves when double tap is complete

Examples

Double tap

TypeScript

await agent.actions.adb.doubleTap(500, 500);

Double tap with custom interval

TypeScript

await agent.actions.adb.doubleTap(500, 500, 200);

`goHome()`

TypeScript

goHome(): Promise<void>

Returns to the home screen using ADB keyevent.

Returns

Promise<void>Resolves when navigation is complete

Examples

TypeScript

await agent.actions.adb.goHome();

`goBack()`

TypeScript

goBack(): Promise<void>

Presses the system back button using ADB keyevent.

Returns

Promise<void>Resolves when back action is complete

Examples

TypeScript

await agent.actions.adb.goBack();

`recents()`

TypeScript

recents(): Promise<void>

Opens the recent apps screen using ADB keyevent.

Returns

Promise<void>Resolves when recent apps screen is shown

Examples

TypeScript

await agent.actions.adb.recents();

`dpad()`

TypeScript

dpad(direction: "up" | "down" | "left" | "right" | "center"): Promise<void>

Sends a D-pad navigation event using ADB keyevent.

Parameters

Name	Type	Description
`direction`	`"up" \| "down" \| "left" \| "right" \| "center"`	Direction to navigate

Returns

Promise<void>Resolves when navigation is complete

Examples

TypeScript

await agent.actions.adb.dpad("down");

TypeScript

await agent.actions.adb.dpad("center"); // Select/Enter

`inputKey()`

TypeScript

inputKey(keyCode: number, duration?: number): Promise<void>

Sends a key input event using ADB keyevent. Supports long press via duration parameter.

Parameters

Name	Type	Description
`keyCode`	`number`	Android KeyEvent code (e.g., 66 for Enter, 67 for Backspace)
`duration?`	`number`	Press duration in ms. 0 for normal press, >0 for long press (default: 0)

Returns

Promise<void>Resolves when key event is complete

Examples

Press Enter

TypeScript

await agent.actions.adb.inputKey(66);

Long press a key

TypeScript

await agent.actions.adb.inputKey(66, 1000);

`writeText()`

TypeScript

writeText(text: string): Promise<void>

Types text using ADB shell input. Special characters are automatically escaped.

Parameters

Name	Type	Description
`text`	`string`	Text to type

Returns

Promise<void>Resolves when text is typed

Examples

TypeScript

await agent.actions.adb.writeText("Hello World");

`launchApp()`

TypeScript

launchApp(packageName: string): Promise<void>

Launches an app by its package name using ADB monkey command.

Parameters

Name	Type	Description
`packageName`	`string`	The app's package name (e.g., com.android.chrome)

Returns

Promise<void>Resolves when app launch command is sent

Examples

TypeScript

await agent.actions.adb.launchApp("com.android.chrome");

`toggleScreenLock()`

TypeScript

toggleScreenLock(): Promise<void>

Toggles screen lock by pressing the power button using ADB keyevent 26 (KEYCODE_POWER). Turns the screen off if on, or on if off.

Returns

Promise<void>Resolves when key event is complete

Examples

Turn screen off

TypeScript

await agent.actions.adb.toggleScreenLock();

`isDeviceLocked()`

TypeScript

isDeviceLocked(): Promise<boolean>

Checks if the device is locked. Returns true if the screen is off or the keyguard (lock screen) is showing.

Returns

Promise<boolean>true if device is locked, false if unlocked

Examples

Check lock state

TypeScript

const locked = await agent.actions.adb.isDeviceLocked();
console.log("Device locked:", locked);

`unlockDevice()`

TypeScript

unlockDevice(): Promise<boolean>

Attempts to unlock the device by pressing the power button. Handles the case where the screen is on but locked (keyguard showing) — pressing power would turn the screen off, so it detects this and presses power again. Returns true if the device is now unlocked. Does not handle PIN/pattern entry.

Returns

Promise<boolean>true if device is now unlocked, false if unlock failed

Examples

Unlock before automation

TypeScript

const unlocked = await agent.actions.adb.unlockDevice();
if (!unlocked) {
  console.log("Could not unlock device");
  return;
}

`paste()`

TypeScript

paste(): Promise<void>

Pastes clipboard contents using ADB keyevent 279 (KEYCODE_PASTE).

Returns

Promise<void>Resolves when paste is complete

Examples

Copy text then paste via ADB

TypeScript

await agent.actions.copyText("Hello World");
await agent.actions.adb.paste();

`screenContent()`

TypeScript

screenContent(): Promise<AndroidNode>

Gets the current screen content (UI hierarchy) via ADB uiautomator dump. Returns the same AndroidNode structure as the regular screenContent() method.

Returns

Promise<AndroidNode>Root node of the accessibility tree

Examples

Get screen content via ADB

TypeScript

const screen = await agent.actions.adb.screenContent();
const button = screen.findTextOne("Submit");

`listApps()`

TypeScript

listApps(): Promise<string[]>

Gets the list of installed package names via ADB pm list packages.

Returns

Promise<string[]>Array of installed package names

Examples

List installed apps

TypeScript

const apps = await agent.actions.adb.listApps();
console.log(apps); // ["com.android.chrome", "com.google.android.youtube", ...]

`screenshot()`

TypeScript

screenshot(maxWidth: number, maxHeight: number, quality: number, cropX1?: number, cropY1?: number, cropX2?: number, cropY2?: number): Promise<{...}>

Takes a screenshot via ADB screencap. Returns the image as a base64-encoded JPEG string along with dimension metadata.

Parameters

Name	Type	Description
`maxWidth`	`number`	Maximum width to scale down to
`maxHeight`	`number`	Maximum height to scale down to
`quality`	`number`	JPEG quality (1-100)
`cropX1?`	`number`	Crop left coordinate
`cropY1?`	`number`	Crop top coordinate
`cropX2?`	`number`	Crop right coordinate
`cropY2?`	`number`	Crop bottom coordinate

Returns

Promise<{ screenshot, compressedWidth, compressedHeight, originalWidth, originalHeight }>Screenshot data with base64 image and dimensions

Examples

Take a screenshot via ADB

TypeScript

const result = await agent.actions.adb.screenshot(720, 1280, 80);
console.log(result.originalWidth, result.originalHeight);

Take a cropped screenshot

TypeScript

const result = await agent.actions.adb.screenshot(720, 1280, 80, 0, 0, 360, 640);

`allScreensContent()`

TypeScript

allScreensContent(): Promise<AndroidNode[]>

Gets the UI hierarchy from all screens/windows via ADB. Returns an array of AndroidNode objects, one per window.

Returns

Promise<AndroidNode[]>Array of root nodes, one per screen/window

Examples

Get all screens content via ADB

TypeScript

const screens = await agent.actions.adb.allScreensContent();
for (const screen of screens) {
  const buttons = screen.findText("OK");
  console.log(buttons.length);
}

`nodeAction()`

TypeScript

nodeAction(node: AndroidNode | object, actionInt: number, data?: object, fieldsToIgnore?: string[]): Promise<{actionPerformed: boolean}>

Performs an accessibility action on a node via ADB. This is the ADB equivalent of agent.actions.nodeAction(). Uses UiAutomation through the ADB touch server instead of the accessibility service. Also available as node.adbPerformAction().

Parameters

Name	Type	Description
`node`	`AndroidNode \| object`	The node to perform action on
`actionInt`	`number`	Action constant (use agent.constants.ACTION_*)
`data?`	`object`	Additional action data
`fieldsToIgnore?`	`string[]`	Fields to ignore when matching node

Returns

Promise<{ actionPerformed: boolean }>Whether the action was successfully performed

Examples

Click a button via ADB

TypeScript

const screen = await agent.actions.adb.screenContent();
const button = screen.findTextOne("Submit");
if (button) {
  await agent.actions.adb.nodeAction(button, agent.constants.ACTION_CLICK);
}

Using adbPerformAction on a node

TypeScript

const screen = await agent.actions.adb.screenContent();
const button = screen.findTextOne("Submit");
if (button) {
  await button.adbPerformAction(agent.constants.ACTION_CLICK);
}

`logcat()`

TypeScript

logcat(options?: { args?: string; packageName?: string; filter?: string; priority?: string; regex?: string; buffer?: string; limit?: number; order?: 'asc' | 'desc' }): Promise<{ logs: string[]; count: number; command: string | null }>

Reads device logs via `adb shell logcat -d` (dump and exit). Two usage modes are supported: pass an `args` string for full control over logcat flags (escape hatch for power users), or use the structured filter options (packageName, filter, priority, etc.) and let the platform build the command. The `limit` is always enforced — even when `args` is supplied, `-t <limit>` is auto-appended unless `args` already contains `-t` or `-T`.

Parameters

Name	Type	Description
`options.args?`	`string`	Raw logcat argument string (e.g. "-b crash *:E"). If provided, structured filter options are ignored.
`options.packageName?`	`string`	Filter to a specific app — uses `--pid=$(pidof -s <package>)`, so the app must be currently running.
`options.filter?`	`string`	Tag filter spec, e.g. "MyTag:V *:S". Takes precedence over `priority`.
`options.priority?`	`"V" \| "D" \| "I" \| "W" \| "E" \| "F" \| "S"`	Minimum log priority (Verbose, Debug, Info, Warn, Error, Fatal, Silent). Used only if `filter` is not set.
`options.regex?`	`string`	Only return lines matching this regex (passed as logcat `-e`).
`options.buffer?`	`"main" \| "system" \| "radio" \| "events" \| "crash" \| "all"`	Log buffer to read from.
`options.limit?`	`number`	Maximum number of log lines to return. Default 100, max 5000.
`options.order?`	`"asc" \| "desc"`	Time ordering: "asc" = oldest first, "desc" = newest first. Default "desc".

Returns

Promise<{ logs: string[]; count: number; command: string | null }>Object containing the log lines array, count, and the actual logcat command that was executed (useful for debugging).

Examples

Get latest 50 errors

TypeScript

const result = await agent.actions.adb.logcat({ priority: "E", limit: 50 });
console.log(result.command); // "logcat -d -v threadtime -t 50 *:E 2>&1"
result.logs.forEach(line => console.log(line));

Filter by package (app must be running)

TypeScript

const result = await agent.actions.adb.logcat({
  packageName: "com.android.chrome",
  limit: 200,
  order: "asc",
});

Read crash buffer

TypeScript

const result = await agent.actions.adb.logcat({ buffer: "crash", limit: 100 });

Search by regex

TypeScript

const result = await agent.actions.adb.logcat({ regex: "ANR|FATAL", limit: 100 });

Tag filter spec

TypeScript

const result = await agent.actions.adb.logcat({ filter: "ActivityManager:I *:S", limit: 100 });

Raw args (escape hatch)

TypeScript

// Limit is auto-appended as "-t 30" since args has no -t.
const result = await agent.actions.adb.logcat({
  args: "-b system *:W",
  limit: 30,
});