Command reference

Every Droidline command with its parameters, return value, errors and the same call in Python, Node.js, C#, the CLI and HTTP.

Each entry shows what the command does, its parameters, what it returns and which errors it can raise, then the same call in every interface. Pick a language in any example and the whole page follows. The Python examples assume d = connect() (dl = Droidline() for server commands), the Node.js examples assume const d = await connect() (const dl = new Droidline()), and the C# examples assume await using var d = await DroidlineClient.ConnectAsync() (using var client = new DroidlineClient()).

Queries

A selector written as an object. Every condition must hold on the same element. Pass it as by and leave value out.

KeyTypeMeaning
texttextExact text
textContainstextPart of the text
textMatchestextRegular expression on the whole text
idtextresource-id, or just its name after :id/
desctextExact content-desc
descContainstextPart of the content-desc
descMatchestextRegular expression on the whole content-desc
classtextExact class name
packagetextPackage the element belongs to
clickabletrue or falseThe node's clickable flag is this value
long_clickabletrue or falseThe node's long_clickable flag is this value
checkabletrue or falseThe node's checkable flag is this value
checkedtrue or falseThe node's checked flag is this value
enabledtrue or falseThe node's enabled flag is this value
focusedtrue or falseThe node's focused flag is this value
selectedtrue or falseThe node's selected flag is this value
scrollabletrue or falseThe node's scrollable flag is this value
editabletrue or falseThe node's editable flag is this value
passwordtrue or falseThe node's password flag is this value
visibletrue or falseWhether the element is on screen. Lists keep items just past the edge in the tree; visible: true skips them
bounds[left, top, right, bottom]Exact bounds [left, top, right, bottom], as dump and find return them
hasanother queryOne of its descendants matches this query
insideanother queryOne of its ancestors matches this query
rowanother queryIts row holds an element that matches this query. The row is the item of the nearest list (RecyclerView, ListView, GridView, or a scrollable view with several children); outside lists, the nearest clickable ancestor
belowanother queryIts center is below the first match of this query. Matches come back nearest first
aboveanother queryIts center is above the first match of this query. Matches come back nearest first
left_ofanother queryIts center is left of the first match of this query. Matches come back nearest first
right_ofanother queryIts center is right of the first match of this query. Matches come back nearest first

Screen

dumpscreenshotrecordfind_imagetap_imageimage_existsfind_imageswait_image_goneocrocr_findocr_tapcurrent

dump

Return the current screen as a node tree

NameTypeDefaultMeaning
pathstringSave the tree as JSON to this local file
all_windowsboolfalseInclude system windows such as the status bar and keyboard

Returns: an object with package, activity, width, height, tree

Needs: Accessibility service

d.dump("screen.json")   # saved on your PC

screenshot

Capture the screen

Android 11+ uses the accessibility screenshot. Android 9-10 asks once for screen capture permission.

NameTypeDefaultMeaning
pathstringSave the image to this local file. The extension picks png or jpeg
formatstring png | jpeg"jpeg"Image format
qualityint80JPEG quality 1-100
scalenumber1Resize factor 0.1-1.0, useful on mobile data

Returns: an object with format, width, height, data

Needs: Accessibility service

d.screenshot("shot.png")   # saved on your PC

record

Turn recording of taps and typing on or off

Optional, and off until you turn it on. While on, the phone sends an action event for every tap, long press and text change in other apps, with the screen it happened on; password fields send no text. It turns itself off after minutes. droidline inspect uses it to write a script as you use the phone.

NameTypeDefaultMeaning
onboolrequiredtrue to start, false to stop
minutesnumber30Turn off by itself after this long

Returns: nothing

Needs: Accessibility service

d.record(True)

find_image

Find a picture on the screen

Optional, and runs on the PC: the server takes a screenshot and compares. Cut the image from a screenshot of the same phone; for a phone with another screen density, pass scales. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
imageimagerequiredPNG or JPEG of what to find, cut from a screenshot of the same phone. The SDKs and the CLI take a file path; on the wire it is base64
thresholdnumber0.9How close the match must be, from 0 to 1
timeoutnumber10 sSeconds to wait for the target to appear
regionlist<int>Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match
scaleslist<number>Sizes of the image to try, 1 being the size it was cut at, such as 0.8, 1, 1.25 for a phone with another screen density. Each size adds time
colorboolfalseAlso require the average color to agree, so a red and a green button of the same shape differ

Returns: an object with x, y, bounds, score

Errors: NOT_FOUND, NO_PERMISSION

d.find_image("ok-button.png")

tap_image

Find a picture on the screen and tap its center

Optional, and runs on the PC: the server takes a screenshot and compares. Cut the image from a screenshot of the same phone; for a phone with another screen density, pass scales. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
imageimagerequiredPNG or JPEG of what to find, cut from a screenshot of the same phone. The SDKs and the CLI take a file path; on the wire it is base64
thresholdnumber0.9How close the match must be, from 0 to 1
timeoutnumber10 sSeconds to wait for the target to appear
regionlist<int>Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match
scaleslist<number>Sizes of the image to try, 1 being the size it was cut at, such as 0.8, 1, 1.25 for a phone with another screen density. Each size adds time
colorboolfalseAlso require the average color to agree, so a red and a green button of the same shape differ

Returns: an object with x, y, score, ms

Errors: NOT_FOUND, NO_PERMISSION

d.tap_image("ok-button.png", threshold=0.85)

image_exists

Whether a picture is on the screen right now. Never waits

Optional, and runs on the PC: the server takes a screenshot and compares. Cut the image from a screenshot of the same phone; for a phone with another screen density, pass scales. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
imageimagerequiredPNG or JPEG of what to find, cut from a screenshot of the same phone. The SDKs and the CLI take a file path; on the wire it is base64
thresholdnumber0.9How close the match must be, from 0 to 1
regionlist<int>Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match
scaleslist<number>Sizes of the image to try, 1 being the size it was cut at, such as 0.8, 1, 1.25 for a phone with another screen density. Each size adds time
colorboolfalseAlso require the average color to agree, so a red and a green button of the same shape differ

Returns: a value of type bool

Errors: NO_PERMISSION

find_images

Every place a picture appears on the screen

Answers at once, with an empty list when nothing matches, unless timeout is set. Best matches come first and never overlap. Runs on the PC; for a phone with another screen density, pass scales.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
imageimagerequiredPNG or JPEG of what to find, cut from a screenshot of the same phone. The SDKs and the CLI take a file path; on the wire it is base64
thresholdnumber0.9How close the match must be, from 0 to 1
timeoutnumber0 sSeconds to wait for at least one match. 0 answers at once
regionlist<int>Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match
scaleslist<number>Sizes of the image to try, 1 being the size it was cut at, such as 0.8, 1, 1.25 for a phone with another screen density. Each size adds time
colorboolfalseAlso require the average color to agree, so a red and a green button of the same shape differ
maxint20Most matches to return

Returns: a value of type list<image_match>

Errors: NO_PERMISSION

wait_image_gone

Wait until a picture is no longer on the screen

Optional, and runs on the PC: the server takes a screenshot and compares. Cut the image from a screenshot of the same phone; for a phone with another screen density, pass scales. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
imageimagerequiredPNG or JPEG of what to find, cut from a screenshot of the same phone. The SDKs and the CLI take a file path; on the wire it is base64
thresholdnumber0.9How close the match must be, from 0 to 1
timeoutnumber10 sSeconds to wait for the target to appear
regionlist<int>Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match
scaleslist<number>Sizes of the image to try, 1 being the size it was cut at, such as 0.8, 1, 1.25 for a phone with another screen density. Each size adds time
colorboolfalseAlso require the average color to agree, so a red and a green button of the same shape differ

Returns: an object with ms

Errors: TIMEOUT, NO_PERMISSION

ocr

Read the text on the screen with OCR

Optional, and runs on the PC with Tesseract, which you install yourself along with the language data you need. Nothing is installed for you. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
langstring"eng"Tesseract languages, such as kor+eng. Each needs its language data installed

Returns: an object with text, lines

Errors: OCR_UNAVAILABLE, NO_PERMISSION

d.ocr("eng")

ocr_find

Wait until OCR reads some text on the screen and return where it is

Optional, and runs on the PC with Tesseract, which you install yourself along with the language data you need. Nothing is installed for you. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
textstringrequiredText to look for: a whole word, or part of a line
langstring"eng"Tesseract languages, such as kor+eng. Each needs its language data installed
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with text, x, y, bounds

Errors: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION

d.ocr_find("Next", "eng")

ocr_tap

Wait until OCR reads some text on the screen and tap it

Optional, and runs on the PC with Tesseract, which you install yourself along with the language data you need. Nothing is installed for you. On Android 9 and 10 screenshots need screen capture permission.

Runs on the PC: the server takes screenshots from the phone and taps through it.

NameTypeDefaultMeaning
textstringrequiredText to look for: a whole word, or part of a line
langstring"eng"Tesseract languages, such as kor+eng. Each needs its language data installed
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with text, x, y, ms

Errors: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION

d.ocr_tap("Start", "eng")

current

Foreground package and activity

Returns: an object with package, activity

Needs: Accessibility service

d.current()

Coordinates

taplong_tapswipe

tap

Tap a screen coordinate

NameTypeDefaultMeaning
xintrequiredX in screen pixels
yintrequiredY in screen pixels

Returns: an object with ms

Needs: Accessibility service

d.tap(540, 1200)

long_tap

Press and hold a coordinate

NameTypeDefaultMeaning
xintrequiredX in screen pixels
yintrequiredY in screen pixels
msint800Hold time in milliseconds

Returns: an object with ms

Needs: Accessibility service

d.long_tap(540, 1200, 800)

swipe

Swipe between two points, or in a direction

NameTypeDefaultMeaning
x1int|stringrequiredStart X, or a direction: up, down, left, right
y1intStart Y
x2intEnd X
y2intEnd Y
msint300Duration in milliseconds

Returns: an object with ms

Needs: Accessibility service

d.swipe(540, 1600, 540, 400, 300)

Elements

touchlong_touchscroll_to

touch

Wait for an element and tap it

If the node refuses the click, the center of its bounds is tapped instead. via tells which path worked: node, parent or gesture.

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with via, ms

Shorthand: touchById(value), touchByText(value), touchByDesc(value)

Errors: NOT_FOUND, NOT_CLICKABLE, NO_ACCESSIBILITY

Needs: Accessibility service

d.touch("text", "Log in")

long_touch

Wait for an element and press and hold it

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
msint800Hold time in milliseconds
nthint0Index when several elements match, starting at 0
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with via, ms

Needs: Accessibility service

d.long_touch("text", "Message")

scroll_to

Scroll until an element is visible

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
directionstring down | up | left | right"down"Direction the content moves toward
max_swipesint20Give up after this many swipes
nthint0Index when several elements match, starting at 0

Returns: an object with swipes

Needs: Accessibility service

d.scroll_to("text", "Settings")

Input

inputclearsendkey

input

Wait for a field and set its text

Uses the accessibility set-text action. Fields that ignore it fall back to the Droidline keyboard when it is selected.

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
textstringrequiredText to enter
appendboolfalseKeep existing text and add to the end
nthint0Index when several elements match, starting at 0
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with via, ms

Needs: Accessibility service

d.input("id", "email", "me@example.com")

clear

Empty a text field

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with ms

Needs: Accessibility service

d.clear("id", "email")

sendkey

Send a key name, a key code, or text

back, home, recents, notifications, quick_settings and lock use accessibility global actions. Other keys and text go through the Droidline keyboard to the focused field.

NameTypeDefaultMeaning
keystring|intKey name (enter, tab, del, space, escape, up, down, left, right, back, home...), Android key code, or text to type
textstringType this text literally, even if it equals a key name

Returns: an object with via

Errors: NO_IME, BAD_ARGS

Needs: Accessibility service

d.sendkey("enter")

Checks

existswaitwait_gonewait_idlefindfind_allget_text

exists

Whether an element is on screen right now. Never waits

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0

Returns: a value of type bool

Needs: Accessibility service

d.exists("text", "Close ad")

wait

Wait until an element appears

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
timeoutnumber10 sSeconds to wait for the target to appear
nthint0Index when several elements match, starting at 0

Returns: an object with ms

Errors: NOT_FOUND

Needs: Accessibility service

d.wait("text", "Done", timeout=30)

wait_gone

Wait until an element disappears

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
timeoutnumber10 sSeconds to wait for the target to appear

Returns: an object with ms

Errors: TIMEOUT

Needs: Accessibility service

d.wait_gone("text", "Loading")

wait_idle

Wait until the screen stops changing

Waits until the app in front has drawn nothing new for ms milliseconds. Use it after an action that loads content, instead of a fixed sleep. A screen that animates all the time ends in TIMEOUT.

NameTypeDefaultMeaning
msint500 msHow long the screen must stay unchanged
timeoutnumber10 sSeconds to wait before giving up

Returns: an object with ms

Errors: TIMEOUT

Needs: Accessibility service

d.wait_idle()

find

Wait for an element and return it

The SDKs return an element object with click, input, find and the node fields. The node comes without children.

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0
timeoutnumber10 sSeconds to wait for the target to appear

Returns: a value of type node

Errors: NOT_FOUND

Needs: Accessibility service

d.find("text", "Log in")

find_all

Every element that matches right now

Answers at once, with an empty list when nothing matches, unless timeout is set. Directional queries come back nearest first.

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
timeoutnumber0 sSeconds to wait for at least one match. 0 answers at once

Returns: a value of type list<node>

Needs: Accessibility service

d.find_all("id", "title")

get_text

Text of an element, or an empty string

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0

Returns: a value of type string

Needs: Accessibility service

d.get_text("id", "balance")

Conditions

checkedenabledselectedcountwhichin_appkeyboard_shownlast_toastcolor

checked

true if a switch or checkbox is on

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0

Returns: a value of type bool

Needs: Accessibility service

d.checked("id", "auto_login")

enabled

true if the element can be pressed

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0

Returns: a value of type bool

Needs: Accessibility service

d.enabled("text", "Next")

selected

true if a tab or item is selected

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object
nthint0Index when several elements match, starting at 0

Returns: a value of type bool

Needs: Accessibility service

d.selected("text", "Home")

count

Number of matching elements

NameTypeDefaultMeaning
byselectorrequiredWhich dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions
valuestringThe value to match. Leave it out when by is a query object

Returns: a value of type int

Needs: Accessibility service

d.count("class", "android.widget.CheckBox")

which

Index of the first candidate to appear, or -1

NameTypeDefaultMeaning
candidateslist<selector_pair>requiredList of [by, value] pairs or query objects
timeoutnumber10 sSeconds to wait for any candidate

Returns: a value of type int

Needs: Accessibility service

d.which([("text", "Log in"), ("id", "main_tab")], timeout=15)

in_app

true if that app is in the foreground

NameTypeDefaultMeaning
packagestringrequiredPackage name, for example com.android.chrome

Returns: a value of type bool

Needs: Accessibility service

d.in_app("com.android.chrome")

keyboard_shown

true if a soft keyboard is showing

Returns: a value of type bool

Needs: Accessibility service

d.keyboard_shown()

last_toast

Text of the most recent toast, or an empty string

NameTypeDefaultMeaning
max_agenumber30 sIgnore toasts older than this many seconds

Returns: a value of type string

Needs: Accessibility service

d.last_toast()

color

Pixel color at a coordinate as #RRGGBB

For screens without accessibility nodes, such as games.

NameTypeDefaultMeaning
xintrequiredX in screen pixels
yintrequiredY in screen pixels

Returns: a value of type string

Needs: Accessibility service

d.color(540, 1200)

Device

screen_onlockedwakelockbatteryorientationinfo

screen_on

true if the screen is on

Returns: a value of type bool

d.screen_on()

locked

true if the lock screen is showing

Returns: a value of type bool

d.locked()

wake

Turn the screen on and dismiss a lock screen that has no PIN

Gestures fail while the screen is off. A PIN, pattern or password lock cannot be dismissed without the user.

Returns: an object with screen_on, locked

d.wake()

lock

Turn the screen off and lock

Returns: nothing

Needs: Accessibility service

d.lock()

battery

Battery level and charging state

Returns: an object with level, charging, temperature

d.battery()

orientation

portrait or landscape

Returns: a value of type string

d.orientation()

info

Model, Android version, screen size and permission readiness

Returns: an object with model, manufacturer, sdk, release, agent, width, height, ready

d.info()

Network

networkproxyproxy_check

network

Connection type (wifi, mobile, none) and airplane mode

Returns: an object with type, airplane, metered

d.network()

proxy

Route chosen apps through an upstream proxy with a per-app VPN

Supports http:// (CONNECT) and socks5:// with user:pass. Pass null or "off" to stop. One upstream at a time. Apps that ignore the proxy setting lose network access instead of leaking.

NameTypeDefaultMeaning
urlstring|nullrequiredsocks5://user:pass@host:port, http://host:port, a saved profile like @kr1, or off
appstring|list<string>Package or packages to route

Returns: an object with active, apps

Errors: NO_PERMISSION, PROXY_FAILED, UNSUPPORTED

Needs: VPN permission · Android API 29+

d.proxy("@kr1", app="com.android.chrome")

proxy_check

Per-app proxy state and the IP the outside world sees

NameTypeDefaultMeaning
appstringPackage to check

Returns: an object with active, ip, upstream, error

d.proxy_check("com.android.chrome")

Apps

launchopen_urlintentclear_dataappsinstalled

launch

Start an app, optionally at a specific activity

NameTypeDefaultMeaning
packagestringrequiredPackage name, for example com.android.chrome
activitystringActivity name, either full or starting with a dot

Returns: an object with ms

Errors: APP_NOT_FOUND, ACTIVITY_BLOCKED

d.launch("com.android.settings")

open_url

Open a URL or deep link

NameTypeDefaultMeaning
urlstringrequiredhttp(s) URL or app deep link
packagestringOpen with this app only

Returns: nothing

d.open_url("https://droidline.dev")

intent

Open a screen by its intent action, such as a Settings page

Opens any screen other apps are allowed to open, for example android.settings.WIFI_SETTINGS, or android.settings.APPLICATION_DETAILS_SETTINGS with data package:com.example. The screen opens fresh, closing other screens of the same app. What to tap after that differs by phone maker and language, so Wi-Fi, airplane mode, force stop and clearing data are recipes in the docs rather than commands.

NameTypeDefaultMeaning
actionstringrequiredIntent action, such as android.settings.WIFI_SETTINGS
datastringData URI, such as package:com.example
packagestringOnly this app may handle it

Returns: nothing

Errors: APP_NOT_FOUND, BAD_ARGS

d.intent("android.settings.WIFI_SETTINGS")

clear_data

Clear an app's data in device owner mode

Optional, and only in device owner mode, where the phone wipes the app directly without opening Settings. Without it the answer is NO_PERMISSION; the docs have a recipe that goes through Settings instead.

NameTypeDefaultMeaning
packagestringrequiredPackage name, for example com.android.chrome

Returns: an object with ms

Errors: APP_NOT_FOUND, NO_PERMISSION

d.clear_data("com.android.chrome")

apps

Installed packages

NameTypeDefaultMeaning
systemboolfalseInclude system packages

Returns: a value of type list<app>

d.apps()

installed

Version name if installed, empty string if not

NameTypeDefaultMeaning
packagestringrequiredPackage name, for example com.android.chrome

Returns: a value of type string

d.installed("com.android.chrome")

System

backhomerecentsopen_notificationsquick_settingsclipboardbatch

back

Back

Returns: nothing

Needs: Accessibility service

d.back()

home

Home screen

Returns: nothing

Needs: Accessibility service

d.home()

recents

Recent apps

Returns: nothing

Needs: Accessibility service

d.recents()

open_notifications

Pull down the notification shade

Returns: nothing

Needs: Accessibility service

d.open_notifications()

quick_settings

Open quick settings

Returns: nothing

Needs: Accessibility service

d.quick_settings()

clipboard

Write the clipboard, or read it when called without text

Reading on Android 10+ needs the Droidline keyboard to be the current input method.

NameTypeDefaultMeaning
textstringText to copy. Omit to read

Returns: a value of type string

Errors: NO_IME

d.clipboard("Hello")

batch

Run several commands on the phone in one go, even while it is offline

Steps are [cmd, args...] lists or {cmd, ...} objects. The step sleep(ms) only exists inside batch. When the steps turn off the phone's network, for example Wi-Fi off and on again, pass cuts_network: the phone answers accepted first, runs the steps while offline, and the result arrives after it reconnects.

With cuts_network, pass wait to get the final result instead of accepted.

NameTypeDefaultMeaning
stepslist<step>requiredCommands to run in order
stop_on_errorbooltrueStop at the first failing step
cuts_networkboolfalseThe steps drop the phone's link. Answer accepted first and send the result after reconnecting

Returns: an object with results

d.batch([("home",), ("sleep", 500), ("recents",)])

Chrome

chrome.go

chrome.go

Open a URL in Chrome

NameTypeDefaultMeaning
urlstringrequiredAddress. https:// is added if missing
new_tabboolfalseOpen in a new tab

Returns: an object with ms

Errors: APP_NOT_FOUND

d.chrome.go("droidline.dev")

Notifications

notificationshas_notificationwait_notificationnotification_replynotification_clicknotification_dismissnotify_filteron_notification

notifications

Notifications currently showing

NameTypeDefaultMeaning
packagestringOnly this app

Returns: a value of type list<notification>

Needs: Notification access

d.notifications()

has_notification

true if a showing notification matches

NameTypeDefaultMeaning
bystring text | textContains | title | packagerequiredtext and textContains look at both title and text
valuestringThe value to match. Leave it out when by is a query object

Returns: a value of type bool

Needs: Notification access

d.has_notification("textContains", "shipped")

wait_notification

Wait for a matching notification and return it

Handled by the PC server, so it does not block other commands to the phone. It sees only apps you chose with notify_filter, and the default is none. On Android 15+ the OS hides one-time codes from apps: you get the notification but the code is masked.

NameTypeDefaultMeaning
bystring text | textContains | title | packagerequiredtext and textContains look at both title and text
valuestringThe value to match. Leave it out when by is a query object
timeoutnumber60 sSeconds to wait
packagestringOnly from this app

Returns: a value of type notification

Errors: TIMEOUT

Needs: Notification access

dl.wait_notification("textContains", "verification code", 60)

notification_reply

Reply inline to a notification that has a reply action

NameTypeDefaultMeaning
keystringrequiredNotification key from notifications() or a notification event
textstringrequiredReply text

Returns: nothing

Needs: Notification access

n = d.notifications()[0]
d.notification_reply(n["key"], "On my way")

notification_click

Open a notification

NameTypeDefaultMeaning
keystringrequiredNotification key from notifications() or a notification event

Returns: nothing

Needs: Notification access

n = d.notifications()[0]
d.notification_click(n["key"])

notification_dismiss

Dismiss a notification

NameTypeDefaultMeaning
keystringrequiredNotification key from notifications() or a notification event

Returns: nothing

Needs: Notification access

n = d.notifications()[0]
d.notification_dismiss(n["key"])

notify_filter

Choose which apps' notifications are sent to the PC. Default is none

NameTypeDefaultMeaning
packageslist<string>Allowed packages. Omit to read the current list

Returns: a value of type list<string>

Needs: Notification access

d.notify_filter(["com.android.chrome", "com.google.android.gm"])

on_notification

Call a function for every matching notification

SDK only. Built on subscribe. The CLI prints matching notifications as JSON lines instead.

Runs inside the SDK; the server sees a subscribe line.

NameTypeDefaultMeaning
packagestringOnly from this app
textContainsstringOnly if title or text contains this

Returns: nothing

Needs: Notification access

stop = d.on_notification(package="com.google.android.gm", callback=print)
# ... later
stop()

Messages, calls and contacts

smscallscontacts

sms

Text messages stored on the phone, newest first

Optional. Allow SMS on the app's Setup tab first; until then the answer is NO_PERMISSION. Covers SMS and the text of MMS. Chat messages (RCS) are kept by the messaging app itself and are not included. The MCP server lists this tool only when --tools names it.

NameTypeDefaultMeaning
boxstring inbox | sent | all"inbox"Received, sent, or both
addressstringOnly messages whose number or sender contains this. Spaces and dashes are ignored
containsstringOnly messages whose text contains this, ignoring case
withinnumber0 sOnly messages from the last this many seconds. 0 means any time
maxint20Most messages to return, up to 500

Returns: a value of type list<sms>

Needs: SMS

calls

Call history, newest first

Optional. Allow call history on the app's Setup tab first; until then the answer is NO_PERMISSION. Only calls made through the phone app are listed; calls inside apps such as messengers usually are not. The MCP server lists this tool only when --tools names it.

NameTypeDefaultMeaning
typestring all | incoming | outgoing | missed | rejected | blocked"all"Which calls
numberstringOnly calls whose number or saved name contains this. Spaces and dashes are ignored
withinnumber0 sOnly calls from the last this many seconds. 0 means any time
maxint20Most calls to return, up to 500

Returns: a value of type list<call>

Needs: Call history

contacts

Contacts saved on the phone, by name

Optional. Allow contacts on the app's Setup tab first; until then the answer is NO_PERMISSION. The MCP server lists this tool only when --tools names it.

NameTypeDefaultMeaning
querystringOnly contacts whose name, number or email contains this, ignoring case. Spaces and dashes in numbers are ignored
maxint50Most contacts to return, up to 500

Returns: a value of type list<contact>

Needs: Contacts

Server

devicesleasereleasepairpair_qrrenamerevokesubscribeserver_infoauth

devices

Paired devices with online state and route

Returns: a value of type list<device>

dl.devices()

lease

Borrow a free phone so no other script can use it

Optional. A phone nobody leased works as usual. While leased, requests to it must carry the lease, or they fail with DEVICE_LEASED. The lease ends with release, or after ttl seconds without a command.

NameTypeDefaultMeaning
devicestringThis phone, by ID or name. Omit to take any free one
waitnumber30 sSeconds to wait for a phone to become free
ttlnumber300 sThe lease ends after this many seconds without a command
min_sdkintOnly phones with at least this Android API level, such as 33
modelstringOnly phones whose model contains this text

Returns: an object with lease, device, name, ttl

Errors: NO_FREE_DEVICE, DEVICE_NOT_FOUND

dl.lease(wait=60)

release

Give a leased phone back

Pass the lease, or a device to free a phone whose script crashed while holding it.

NameTypeDefaultMeaning
leasestringThe lease that lease returned
devicestringFree this phone whatever lease holds it

Returns: nothing

dl.release("l-3f9a1c0d2e4b")

pair

Approve the phone that shows this 6-digit code

NameTypeDefaultMeaning
codestringrequiredCode shown on the phone
namestringName to give the device

Returns: a value of type device

Errors: PAIRING_FAILED

dl.pair("482913", name="shelf-01")

pair_qr

Create a one-time pairing QR code valid for 10 minutes

NameTypeDefaultMeaning
namestringName to give the device

Returns: an object with uri, expires

dl.pair_qr()

rename

Give a device a name

NameTypeDefaultMeaning
devicestringrequiredDevice ID or name
namestringrequiredNew name

Returns: a value of type device

dl.rename("k7d2q9xa", "shelf-01")

revoke

Unpair a device. It must pair again to connect

NameTypeDefaultMeaning
devicestringrequiredDevice ID or name

Returns: nothing

dl.revoke("shelf-01")

subscribe

Receive events on this connection

NameTypeDefaultMeaning
eventslist<string>requiredAny of notification, screen, toast, device, result, action
devicestringOnly from this device. Omit for all

Returns: nothing

dl.subscribe(["notification"])

server_info

Server version, ports and listening addresses

Returns: an object with version, server, name, proto, agent_port, client_port

dl.server_info()

auth

Authenticate this client connection with a token

NameTypeDefaultMeaning
tokenstringrequiredClient token from droidline token

Returns: nothing

dl.auth("your-client-token")