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.
| Key | Type | Meaning |
|---|---|---|
text | text | Exact text |
textContains | text | Part of the text |
textMatches | text | Regular expression on the whole text |
id | text | resource-id, or just its name after :id/ |
desc | text | Exact content-desc |
descContains | text | Part of the content-desc |
descMatches | text | Regular expression on the whole content-desc |
class | text | Exact class name |
package | text | Package the element belongs to |
clickable | true or false | The node's clickable flag is this value |
long_clickable | true or false | The node's long_clickable flag is this value |
checkable | true or false | The node's checkable flag is this value |
checked | true or false | The node's checked flag is this value |
enabled | true or false | The node's enabled flag is this value |
focused | true or false | The node's focused flag is this value |
selected | true or false | The node's selected flag is this value |
scrollable | true or false | The node's scrollable flag is this value |
editable | true or false | The node's editable flag is this value |
password | true or false | The node's password flag is this value |
visible | true or false | Whether 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 |
has | another query | One of its descendants matches this query |
inside | another query | One of its ancestors matches this query |
row | another query | Its 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 |
below | another query | Its center is below the first match of this query. Matches come back nearest first |
above | another query | Its center is above the first match of this query. Matches come back nearest first |
left_of | another query | Its center is left of the first match of this query. Matches come back nearest first |
right_of | another query | Its 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
| Name | Type | Default | Meaning |
|---|---|---|---|
path | string | Save the tree as JSON to this local file | |
all_windows | bool | false | Include system windows such as the status bar and keyboard |
Returns: an object with package, activity, width, height, tree
d.dump("screen.json") # saved on your PCawait d.dump("screen.json"); // saved on your PCawait d.DumpAsync("screen.json"); // saved on your PCdroidline dump screen.jsoncurl -s -X POST localhost:8780/devices/_/dump \
-H 'content-type: application/json' > screen.json{"id":1,"cmd":"dump"}screenshot
Capture the screen
Android 11+ uses the accessibility screenshot. Android 9-10 asks once for screen capture permission.
| Name | Type | Default | Meaning |
|---|---|---|---|
path | string | Save the image to this local file. The extension picks png or jpeg | |
format | string png | jpeg | "jpeg" | Image format |
quality | int | 80 | JPEG quality 1-100 |
scale | number | 1 | Resize factor 0.1-1.0, useful on mobile data |
Returns: an object with format, width, height, data
d.screenshot("shot.png") # saved on your PCawait d.screenshot("shot.png"); // saved on your PCawait d.ScreenshotAsync("shot.png"); // saved on your PCdroidline screenshot shot.pngcurl -s localhost:8780/devices/_/screenshot.png -o shot.png{"id":1,"cmd":"screenshot"}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.
| Name | Type | Default | Meaning |
|---|---|---|---|
on | bool | required | true to start, false to stop |
minutes | number | 30 | Turn off by itself after this long |
Returns: nothing
d.record(True)await d.record(true);await d.RecordAsync(true);droidline record truecurl -s -X POST localhost:8780/devices/_/record \
-H 'content-type: application/json' \
-d '{"on":true}'{"id":1,"cmd":"record","on":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.
| Name | Type | Default | Meaning |
|---|---|---|---|
image | image | required | PNG 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 |
threshold | number | 0.9 | How close the match must be, from 0 to 1 |
timeout | number | 10 s | Seconds to wait for the target to appear |
region | list<int> | Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match | |
scales | list<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 | |
color | bool | false | Also 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")await d.findImage("ok-button.png");await d.FindImageAsync("ok-button.png");droidline find_image ok-button.pngcurl -s -X POST localhost:8780/devices/_/find_image \
-H 'content-type: application/json' \
-d '{"image":"<base64 of the PNG>"}'{"id":1,"cmd":"find_image","image":"<base64 of the 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.
| Name | Type | Default | Meaning |
|---|---|---|---|
image | image | required | PNG 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 |
threshold | number | 0.9 | How close the match must be, from 0 to 1 |
timeout | number | 10 s | Seconds to wait for the target to appear |
region | list<int> | Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match | |
scales | list<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 | |
color | bool | false | Also 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)await d.tapImage("ok-button.png", { threshold: 0.85 });await d.TapImageAsync("ok-button.png", threshold: 0.85);droidline tap_image ok-button.png --threshold 0.85curl -s -X POST localhost:8780/devices/_/tap_image \
-H 'content-type: application/json' \
-d '{"image":"<base64 of the PNG>","threshold":0.85}'{"id":1,"cmd":"tap_image","image":"<base64 of the 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.
| Name | Type | Default | Meaning |
|---|---|---|---|
image | image | required | PNG 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 |
threshold | number | 0.9 | How close the match must be, from 0 to 1 |
region | list<int> | Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match | |
scales | list<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 | |
color | bool | false | Also 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.
| Name | Type | Default | Meaning |
|---|---|---|---|
image | image | required | PNG 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 |
threshold | number | 0.9 | How close the match must be, from 0 to 1 |
timeout | number | 0 s | Seconds to wait for at least one match. 0 answers at once |
region | list<int> | Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match | |
scales | list<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 | |
color | bool | false | Also require the average color to agree, so a red and a green button of the same shape differ |
max | int | 20 | Most 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.
| Name | Type | Default | Meaning |
|---|---|---|---|
image | image | required | PNG 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 |
threshold | number | 0.9 | How close the match must be, from 0 to 1 |
timeout | number | 10 s | Seconds to wait for the target to appear |
region | list<int> | Search only inside this box, given as left, top, right, bottom in screen pixels. Faster, and nothing outside it can match | |
scales | list<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 | |
color | bool | false | Also 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.
| Name | Type | Default | Meaning |
|---|---|---|---|
lang | string | "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")await d.ocr("eng");await d.OcrAsync("eng");droidline ocr engcurl -s -X POST localhost:8780/devices/_/ocr \
-H 'content-type: application/json' \
-d '{"lang":"eng"}'{"id":1,"cmd":"ocr","lang":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
text | string | required | Text to look for: a whole word, or part of a line |
lang | string | "eng" | Tesseract languages, such as kor+eng. Each needs its language data installed |
timeout | number | 10 s | Seconds 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")await d.ocrFind("Next", "eng");await d.OcrFindAsync("Next", "eng");droidline ocr_find Next engcurl -s -X POST localhost:8780/devices/_/ocr_find \
-H 'content-type: application/json' \
-d '{"text":"Next","lang":"eng"}'{"id":1,"cmd":"ocr_find","text":"Next","lang":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
text | string | required | Text to look for: a whole word, or part of a line |
lang | string | "eng" | Tesseract languages, such as kor+eng. Each needs its language data installed |
timeout | number | 10 s | Seconds 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")await d.ocrTap("Start", "eng");await d.OcrTapAsync("Start", "eng");droidline ocr_tap Start engcurl -s -X POST localhost:8780/devices/_/ocr_tap \
-H 'content-type: application/json' \
-d '{"text":"Start","lang":"eng"}'{"id":1,"cmd":"ocr_tap","text":"Start","lang":"eng"}current
Foreground package and activity
Returns: an object with package, activity
d.current()await d.current();await d.CurrentAsync();droidline currentcurl -s -X POST localhost:8780/devices/_/current \
-H 'content-type: application/json'{"id":1,"cmd":"current"}Coordinates
tap
Tap a screen coordinate
| Name | Type | Default | Meaning |
|---|---|---|---|
x | int | required | X in screen pixels |
y | int | required | Y in screen pixels |
Returns: an object with ms
d.tap(540, 1200)await d.tap(540, 1200);await d.TapAsync(540, 1200);droidline tap 540 1200curl -s -X POST localhost:8780/devices/_/tap \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200}'{"id":1,"cmd":"tap","x":540,"y":1200}long_tap
Press and hold a coordinate
| Name | Type | Default | Meaning |
|---|---|---|---|
x | int | required | X in screen pixels |
y | int | required | Y in screen pixels |
ms | int | 800 | Hold time in milliseconds |
Returns: an object with ms
d.long_tap(540, 1200, 800)await d.longTap(540, 1200, 800);await d.LongTapAsync(540, 1200, 800);droidline long_tap 540 1200 800curl -s -X POST localhost:8780/devices/_/long_tap \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200,"ms":800}'{"id":1,"cmd":"long_tap","x":540,"y":1200,"ms":800}swipe
Swipe between two points, or in a direction
| Name | Type | Default | Meaning |
|---|---|---|---|
x1 | int|string | required | Start X, or a direction: up, down, left, right |
y1 | int | Start Y | |
x2 | int | End X | |
y2 | int | End Y | |
ms | int | 300 | Duration in milliseconds |
Returns: an object with ms
d.swipe(540, 1600, 540, 400, 300)await d.swipe(540, 1600, 540, 400, 300);await d.SwipeAsync(540, 1600, 540, 400, 300);droidline swipe 540 1600 540 400 300curl -s -X POST localhost:8780/devices/_/swipe \
-H 'content-type: application/json' \
-d '{"x1":540,"y1":1600,"x2":540,"y2":400,"ms":300}'{"id":1,"cmd":"swipe","x1":540,"y1":1600,"x2":540,"y2":400,"ms":300}Elements
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.
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
timeout | number | 10 s | Seconds 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
d.touch("text", "Log in")await d.touch("text", "Log in");await d.TouchAsync("text", "Log in");droidline touch text "Log in"curl -s -X POST localhost:8780/devices/_/touch \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Log in"}'{"id":1,"cmd":"touch","by":"text","value":"Log in"}long_touch
Wait for an element and press and hold it
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
ms | int | 800 | Hold time in milliseconds |
nth | int | 0 | Index when several elements match, starting at 0 |
timeout | number | 10 s | Seconds to wait for the target to appear |
Returns: an object with via, ms
d.long_touch("text", "Message")await d.longTouch("text", "Message");await d.LongTouchAsync("text", "Message");droidline long_touch text Messagecurl -s -X POST localhost:8780/devices/_/long_touch \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Message"}'{"id":1,"cmd":"long_touch","by":"text","value":"Message"}scroll_to
Scroll until an element is visible
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
direction | string down | up | left | right | "down" | Direction the content moves toward |
max_swipes | int | 20 | Give up after this many swipes |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: an object with swipes
d.scroll_to("text", "Settings")await d.scrollTo("text", "Settings");await d.ScrollToAsync("text", "Settings");droidline scroll_to text Settingscurl -s -X POST localhost:8780/devices/_/scroll_to \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Settings"}'{"id":1,"cmd":"scroll_to","by":"text","value":"Settings"}Input
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.
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
text | string | required | Text to enter |
append | bool | false | Keep existing text and add to the end |
nth | int | 0 | Index when several elements match, starting at 0 |
timeout | number | 10 s | Seconds to wait for the target to appear |
Returns: an object with via, ms
d.input("id", "email", "me@example.com")await d.input("id", "email", "me@example.com");await d.InputAsync("id", "email", "me@example.com");droidline input id email me@example.comcurl -s -X POST localhost:8780/devices/_/input \
-H 'content-type: application/json' \
-d '{"by":"id","value":"email","text":"me@example.com"}'{"id":1,"cmd":"input","by":"id","value":"email","text":"me@example.com"}clear
Empty a text field
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
timeout | number | 10 s | Seconds to wait for the target to appear |
Returns: an object with ms
d.clear("id", "email")await d.clear("id", "email");await d.ClearAsync("id", "email");droidline clear id emailcurl -s -X POST localhost:8780/devices/_/clear \
-H 'content-type: application/json' \
-d '{"by":"id","value":"email"}'{"id":1,"cmd":"clear","by":"id","value":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
key | string|int | Key name (enter, tab, del, space, escape, up, down, left, right, back, home...), Android key code, or text to type | |
text | string | Type this text literally, even if it equals a key name |
Returns: an object with via
d.sendkey("enter")await d.sendkey("enter");await d.SendkeyAsync("enter");droidline sendkey entercurl -s -X POST localhost:8780/devices/_/sendkey \
-H 'content-type: application/json' \
-d '{"key":"enter"}'{"id":1,"cmd":"sendkey","key":"enter"}Checks
existswaitwait_gonewait_idlefindfind_allget_text
exists
Whether an element is on screen right now. Never waits
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: a value of type bool
d.exists("text", "Close ad")await d.exists("text", "Close ad");await d.ExistsAsync("text", "Close ad");droidline exists text "Close ad"curl -s -X POST localhost:8780/devices/_/exists \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Close ad"}'{"id":1,"cmd":"exists","by":"text","value":"Close ad"}wait
Wait until an element appears
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
timeout | number | 10 s | Seconds to wait for the target to appear |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: an object with ms
Errors: NOT_FOUND
d.wait("text", "Done", timeout=30)await d.wait("text", "Done", { timeout: 30 });await d.WaitAsync("text", "Done", timeout: 30);droidline wait text Done --timeout 30curl -s -X POST localhost:8780/devices/_/wait \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Done","timeout":30}'{"id":1,"cmd":"wait","by":"text","value":"Done","timeout":30}wait_gone
Wait until an element disappears
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
timeout | number | 10 s | Seconds to wait for the target to appear |
Returns: an object with ms
Errors: TIMEOUT
d.wait_gone("text", "Loading")await d.waitGone("text", "Loading");await d.WaitGoneAsync("text", "Loading");droidline wait_gone text Loadingcurl -s -X POST localhost:8780/devices/_/wait_gone \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Loading"}'{"id":1,"cmd":"wait_gone","by":"text","value":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
ms | int | 500 ms | How long the screen must stay unchanged |
timeout | number | 10 s | Seconds to wait before giving up |
Returns: an object with ms
Errors: TIMEOUT
d.wait_idle()await d.waitIdle();await d.WaitIdleAsync();droidline wait_idlecurl -s -X POST localhost:8780/devices/_/wait_idle \
-H 'content-type: application/json'{"id":1,"cmd":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
timeout | number | 10 s | Seconds to wait for the target to appear |
Returns: a value of type node
Errors: NOT_FOUND
d.find("text", "Log in")await d.find("text", "Log in");await d.FindAsync("text", "Log in");droidline find text "Log in"curl -s -X POST localhost:8780/devices/_/find \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Log in"}'{"id":1,"cmd":"find","by":"text","value":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
timeout | number | 0 s | Seconds to wait for at least one match. 0 answers at once |
Returns: a value of type list<node>
d.find_all("id", "title")await d.findAll("id", "title");await d.FindAllAsync("id", "title");droidline find_all id titlecurl -s -X POST localhost:8780/devices/_/find_all \
-H 'content-type: application/json' \
-d '{"by":"id","value":"title"}'{"id":1,"cmd":"find_all","by":"id","value":"title"}get_text
Text of an element, or an empty string
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: a value of type string
d.get_text("id", "balance")await d.getText("id", "balance");await d.GetTextAsync("id", "balance");droidline get_text id balancecurl -s -X POST localhost:8780/devices/_/get_text \
-H 'content-type: application/json' \
-d '{"by":"id","value":"balance"}'{"id":1,"cmd":"get_text","by":"id","value":"balance"}Conditions
checkedenabledselectedcountwhichin_appkeyboard_shownlast_toastcolor
checked
true if a switch or checkbox is on
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: a value of type bool
d.checked("id", "auto_login")await d.checked("id", "auto_login");await d.CheckedAsync("id", "auto_login");droidline checked id auto_logincurl -s -X POST localhost:8780/devices/_/checked \
-H 'content-type: application/json' \
-d '{"by":"id","value":"auto_login"}'{"id":1,"cmd":"checked","by":"id","value":"auto_login"}enabled
true if the element can be pressed
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: a value of type bool
d.enabled("text", "Next")await d.enabled("text", "Next");await d.EnabledAsync("text", "Next");droidline enabled text Nextcurl -s -X POST localhost:8780/devices/_/enabled \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Next"}'{"id":1,"cmd":"enabled","by":"text","value":"Next"}selected
true if a tab or item is selected
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object | |
nth | int | 0 | Index when several elements match, starting at 0 |
Returns: a value of type bool
d.selected("text", "Home")await d.selected("text", "Home");await d.SelectedAsync("text", "Home");droidline selected text Homecurl -s -X POST localhost:8780/devices/_/selected \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Home"}'{"id":1,"cmd":"selected","by":"text","value":"Home"}count
Number of matching elements
| Name | Type | Default | Meaning |
|---|---|---|---|
by | selector | required | Which dump field to match (text, textContains, textMatches, id, desc, descContains, descMatches, class), or a query object with several conditions |
value | string | The value to match. Leave it out when by is a query object |
Returns: a value of type int
d.count("class", "android.widget.CheckBox")await d.count("class", "android.widget.CheckBox");await d.CountAsync("class", "android.widget.CheckBox");droidline count class android.widget.CheckBoxcurl -s -X POST localhost:8780/devices/_/count \
-H 'content-type: application/json' \
-d '{"by":"class","value":"android.widget.CheckBox"}'{"id":1,"cmd":"count","by":"class","value":"android.widget.CheckBox"}which
Index of the first candidate to appear, or -1
| Name | Type | Default | Meaning |
|---|---|---|---|
candidates | list<selector_pair> | required | List of [by, value] pairs or query objects |
timeout | number | 10 s | Seconds to wait for any candidate |
Returns: a value of type int
d.which([("text", "Log in"), ("id", "main_tab")], timeout=15)await d.which([["text", "Log in"], ["id", "main_tab"]], { timeout: 15 });await d.WhichAsync(new object[] { ("text", "Log in"), ("id", "main_tab") }, timeout: 15);droidline which text="Log in" id=main_tab --timeout 15curl -s -X POST localhost:8780/devices/_/which \
-H 'content-type: application/json' \
-d '{"candidates":[["text","Log in"],["id","main_tab"]],"timeout":15}'{"id":1,"cmd":"which","candidates":[["text","Log in"],["id","main_tab"]],"timeout":15}in_app
true if that app is in the foreground
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | required | Package name, for example com.android.chrome |
Returns: a value of type bool
d.in_app("com.android.chrome")await d.inApp("com.android.chrome");await d.InAppAsync("com.android.chrome");droidline in_app com.android.chromecurl -s -X POST localhost:8780/devices/_/in_app \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"in_app","package":"com.android.chrome"}keyboard_shown
true if a soft keyboard is showing
Returns: a value of type bool
d.keyboard_shown()await d.keyboardShown();await d.KeyboardShownAsync();droidline keyboard_showncurl -s -X POST localhost:8780/devices/_/keyboard_shown \
-H 'content-type: application/json'{"id":1,"cmd":"keyboard_shown"}last_toast
Text of the most recent toast, or an empty string
| Name | Type | Default | Meaning |
|---|---|---|---|
max_age | number | 30 s | Ignore toasts older than this many seconds |
Returns: a value of type string
d.last_toast()await d.lastToast();await d.LastToastAsync();droidline last_toastcurl -s -X POST localhost:8780/devices/_/last_toast \
-H 'content-type: application/json'{"id":1,"cmd":"last_toast"}color
Pixel color at a coordinate as #RRGGBB
For screens without accessibility nodes, such as games.
| Name | Type | Default | Meaning |
|---|---|---|---|
x | int | required | X in screen pixels |
y | int | required | Y in screen pixels |
Returns: a value of type string
d.color(540, 1200)await d.color(540, 1200);await d.ColorAsync(540, 1200);droidline color 540 1200curl -s -X POST localhost:8780/devices/_/color \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200}'{"id":1,"cmd":"color","x":540,"y":1200}Device
screen_onlockedwakelockbatteryorientationinfo
screen_on
true if the screen is on
Returns: a value of type bool
d.screen_on()await d.screenOn();await d.ScreenOnAsync();droidline screen_oncurl -s -X POST localhost:8780/devices/_/screen_on \
-H 'content-type: application/json'{"id":1,"cmd":"screen_on"}locked
true if the lock screen is showing
Returns: a value of type bool
d.locked()await d.locked();await d.LockedAsync();droidline lockedcurl -s -X POST localhost:8780/devices/_/locked \
-H 'content-type: application/json'{"id":1,"cmd":"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()await d.wake();await d.WakeAsync();droidline wakecurl -s -X POST localhost:8780/devices/_/wake \
-H 'content-type: application/json'{"id":1,"cmd":"wake"}lock
Turn the screen off and lock
Returns: nothing
d.lock()await d.lock();await d.LockAsync();droidline lockcurl -s -X POST localhost:8780/devices/_/lock \
-H 'content-type: application/json'{"id":1,"cmd":"lock"}battery
Battery level and charging state
Returns: an object with level, charging, temperature
d.battery()await d.battery();await d.BatteryAsync();droidline batterycurl -s -X POST localhost:8780/devices/_/battery \
-H 'content-type: application/json'{"id":1,"cmd":"battery"}orientation
portrait or landscape
Returns: a value of type string
d.orientation()await d.orientation();await d.OrientationAsync();droidline orientationcurl -s -X POST localhost:8780/devices/_/orientation \
-H 'content-type: application/json'{"id":1,"cmd":"orientation"}info
Model, Android version, screen size and permission readiness
Returns: an object with model, manufacturer, sdk, release, agent, width, height, ready
d.info()await d.info();await d.InfoAsync();droidline infocurl -s -X POST localhost:8780/devices/_/info \
-H 'content-type: application/json'{"id":1,"cmd":"info"}Network
network
Connection type (wifi, mobile, none) and airplane mode
Returns: an object with type, airplane, metered
d.network()await d.network();await d.NetworkAsync();droidline networkcurl -s -X POST localhost:8780/devices/_/network \
-H 'content-type: application/json'{"id":1,"cmd":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
url | string|null | required | socks5://user:pass@host:port, http://host:port, a saved profile like @kr1, or off |
app | string|list<string> | Package or packages to route |
Returns: an object with active, apps
Errors: NO_PERMISSION, PROXY_FAILED, UNSUPPORTED
d.proxy("@kr1", app="com.android.chrome")await d.proxy("@kr1", { app: "com.android.chrome" });await d.ProxyAsync("@kr1", app: "com.android.chrome");droidline proxy @kr1 --app com.android.chromecurl -s -X POST localhost:8780/devices/_/proxy \
-H 'content-type: application/json' \
-d '{"url":"@kr1","app":"com.android.chrome"}'{"id":1,"cmd":"proxy","url":"@kr1","app":"com.android.chrome"}proxy_check
Per-app proxy state and the IP the outside world sees
| Name | Type | Default | Meaning |
|---|---|---|---|
app | string | Package to check |
Returns: an object with active, ip, upstream, error
d.proxy_check("com.android.chrome")await d.proxyCheck("com.android.chrome");await d.ProxyCheckAsync("com.android.chrome");droidline proxy_check com.android.chromecurl -s -X POST localhost:8780/devices/_/proxy_check \
-H 'content-type: application/json' \
-d '{"app":"com.android.chrome"}'{"id":1,"cmd":"proxy_check","app":"com.android.chrome"}Apps
launchopen_urlintentclear_dataappsinstalled
launch
Start an app, optionally at a specific activity
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | required | Package name, for example com.android.chrome |
activity | string | Activity name, either full or starting with a dot |
Returns: an object with ms
Errors: APP_NOT_FOUND, ACTIVITY_BLOCKED
d.launch("com.android.settings")await d.launch("com.android.settings");await d.LaunchAsync("com.android.settings");droidline launch com.android.settingscurl -s -X POST localhost:8780/devices/_/launch \
-H 'content-type: application/json' \
-d '{"package":"com.android.settings"}'{"id":1,"cmd":"launch","package":"com.android.settings"}open_url
Open a URL or deep link
| Name | Type | Default | Meaning |
|---|---|---|---|
url | string | required | http(s) URL or app deep link |
package | string | Open with this app only |
Returns: nothing
d.open_url("https://droidline.dev")await d.openUrl("https://droidline.dev");await d.OpenUrlAsync("https://droidline.dev");droidline open_url https://droidline.devcurl -s -X POST localhost:8780/devices/_/open_url \
-H 'content-type: application/json' \
-d '{"url":"https://droidline.dev"}'{"id":1,"cmd":"open_url","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.
| Name | Type | Default | Meaning |
|---|---|---|---|
action | string | required | Intent action, such as android.settings.WIFI_SETTINGS |
data | string | Data URI, such as package:com.example | |
package | string | Only this app may handle it |
Returns: nothing
Errors: APP_NOT_FOUND, BAD_ARGS
d.intent("android.settings.WIFI_SETTINGS")await d.intent("android.settings.WIFI_SETTINGS");await d.IntentAsync("android.settings.WIFI_SETTINGS");droidline intent android.settings.WIFI_SETTINGScurl -s -X POST localhost:8780/devices/_/intent \
-H 'content-type: application/json' \
-d '{"action":"android.settings.WIFI_SETTINGS"}'{"id":1,"cmd":"intent","action":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | required | Package name, for example com.android.chrome |
Returns: an object with ms
Errors: APP_NOT_FOUND, NO_PERMISSION
d.clear_data("com.android.chrome")await d.clearData("com.android.chrome");await d.ClearDataAsync("com.android.chrome");droidline clear_data com.android.chromecurl -s -X POST localhost:8780/devices/_/clear_data \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"clear_data","package":"com.android.chrome"}apps
Installed packages
| Name | Type | Default | Meaning |
|---|---|---|---|
system | bool | false | Include system packages |
Returns: a value of type list<app>
d.apps()await d.apps();await d.AppsAsync();droidline appscurl -s -X POST localhost:8780/devices/_/apps \
-H 'content-type: application/json'{"id":1,"cmd":"apps"}installed
Version name if installed, empty string if not
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | required | Package name, for example com.android.chrome |
Returns: a value of type string
d.installed("com.android.chrome")await d.installed("com.android.chrome");await d.InstalledAsync("com.android.chrome");droidline installed com.android.chromecurl -s -X POST localhost:8780/devices/_/installed \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"installed","package":"com.android.chrome"}System
backhomerecentsopen_notificationsquick_settingsclipboardbatch
back
Back
Returns: nothing
d.back()await d.back();await d.BackAsync();droidline backcurl -s -X POST localhost:8780/devices/_/back \
-H 'content-type: application/json'{"id":1,"cmd":"back"}home
Home screen
Returns: nothing
d.home()await d.home();await d.HomeAsync();droidline homecurl -s -X POST localhost:8780/devices/_/home \
-H 'content-type: application/json'{"id":1,"cmd":"home"}recents
Recent apps
Returns: nothing
d.recents()await d.recents();await d.RecentsAsync();droidline recentscurl -s -X POST localhost:8780/devices/_/recents \
-H 'content-type: application/json'{"id":1,"cmd":"recents"}open_notifications
Pull down the notification shade
Returns: nothing
d.open_notifications()await d.openNotifications();await d.OpenNotificationsAsync();droidline open_notificationscurl -s -X POST localhost:8780/devices/_/open_notifications \
-H 'content-type: application/json'{"id":1,"cmd":"open_notifications"}quick_settings
Open quick settings
Returns: nothing
d.quick_settings()await d.quickSettings();await d.QuickSettingsAsync();droidline quick_settingscurl -s -X POST localhost:8780/devices/_/quick_settings \
-H 'content-type: application/json'{"id":1,"cmd":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
text | string | Text to copy. Omit to read |
Returns: a value of type string
Errors: NO_IME
d.clipboard("Hello")await d.clipboard("Hello");await d.ClipboardAsync("Hello");droidline clipboard Hellocurl -s -X POST localhost:8780/devices/_/clipboard \
-H 'content-type: application/json' \
-d '{"text":"Hello"}'{"id":1,"cmd":"clipboard","text":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
steps | list<step> | required | Commands to run in order |
stop_on_error | bool | true | Stop at the first failing step |
cuts_network | bool | false | The 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",)])await d.batch([["home"], ["sleep", 500], ["recents"]]);await d.BatchAsync(new object[] { new object[] { "home" }, ("sleep", 500), new object[] { "recents" } });droidline batch '[["home"],["sleep",500],["recents"]]'curl -s -X POST localhost:8780/devices/_/batch \
-H 'content-type: application/json' \
-d '{"steps":[["home"],["sleep",500],["recents"]]}'{"id":1,"cmd":"batch","steps":[["home"],["sleep",500],["recents"]]}Chrome
chrome.go
Open a URL in Chrome
| Name | Type | Default | Meaning |
|---|---|---|---|
url | string | required | Address. https:// is added if missing |
new_tab | bool | false | Open in a new tab |
Returns: an object with ms
Errors: APP_NOT_FOUND
d.chrome.go("droidline.dev")await d.chrome.go("droidline.dev");await d.Chrome.GoAsync("droidline.dev");droidline chrome.go droidline.devcurl -s -X POST localhost:8780/devices/_/chrome.go \
-H 'content-type: application/json' \
-d '{"url":"droidline.dev"}'{"id":1,"cmd":"chrome.go","url":"droidline.dev"}Notifications
notificationshas_notificationwait_notificationnotification_replynotification_clicknotification_dismissnotify_filteron_notification
notifications
Notifications currently showing
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | Only this app |
Returns: a value of type list<notification>
d.notifications()await d.notifications();await d.NotificationsAsync();droidline notificationscurl -s -X POST localhost:8780/devices/_/notifications \
-H 'content-type: application/json'{"id":1,"cmd":"notifications"}has_notification
true if a showing notification matches
| Name | Type | Default | Meaning |
|---|---|---|---|
by | string text | textContains | title | package | required | text and textContains look at both title and text |
value | string | The value to match. Leave it out when by is a query object |
Returns: a value of type bool
d.has_notification("textContains", "shipped")await d.hasNotification("textContains", "shipped");await d.HasNotificationAsync("textContains", "shipped");droidline has_notification textContains shippedcurl -s -X POST localhost:8780/devices/_/has_notification \
-H 'content-type: application/json' \
-d '{"by":"textContains","value":"shipped"}'{"id":1,"cmd":"has_notification","by":"textContains","value":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
by | string text | textContains | title | package | required | text and textContains look at both title and text |
value | string | The value to match. Leave it out when by is a query object | |
timeout | number | 60 s | Seconds to wait |
package | string | Only from this app |
Returns: a value of type notification
Errors: TIMEOUT
dl.wait_notification("textContains", "verification code", 60)await dl.waitNotification("textContains", "verification code", 60);await client.WaitNotificationAsync("textContains", "verification code", 60);droidline wait_notification textContains "verification code" 60curl -s -X POST localhost:8780/server/wait_notification \
-H 'content-type: application/json' \
-d '{"by":"textContains","value":"verification code","timeout":60}'{"id":1,"cmd":"wait_notification","by":"textContains","value":"verification code","timeout":60}notification_reply
Reply inline to a notification that has a reply action
| Name | Type | Default | Meaning |
|---|---|---|---|
key | string | required | Notification key from notifications() or a notification event |
text | string | required | Reply text |
Returns: nothing
n = d.notifications()[0]
d.notification_reply(n["key"], "On my way")const [n] = await d.notifications();
await d.notificationReply(n.key, "On my way");var n = (await d.NotificationsAsync())[0];
await d.NotificationReplyAsync((string)n.Key!, "On my way");KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_reply "$KEY" "On my way"curl -s -X POST localhost:8780/devices/_/notification_reply \
-H 'content-type: application/json' \
-d '{"key":"KEY","text":"On my way"}'{"id":1,"cmd":"notification_reply","key":"KEY","text":"On my way"}notification_click
Open a notification
| Name | Type | Default | Meaning |
|---|---|---|---|
key | string | required | Notification key from notifications() or a notification event |
Returns: nothing
n = d.notifications()[0]
d.notification_click(n["key"])const [n] = await d.notifications();
await d.notificationClick(n.key);var n = (await d.NotificationsAsync())[0];
await d.NotificationClickAsync((string)n.Key!);KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_click "$KEY"curl -s -X POST localhost:8780/devices/_/notification_click \
-H 'content-type: application/json' \
-d '{"key":"KEY"}'{"id":1,"cmd":"notification_click","key":"KEY"}notification_dismiss
Dismiss a notification
| Name | Type | Default | Meaning |
|---|---|---|---|
key | string | required | Notification key from notifications() or a notification event |
Returns: nothing
n = d.notifications()[0]
d.notification_dismiss(n["key"])const [n] = await d.notifications();
await d.notificationDismiss(n.key);var n = (await d.NotificationsAsync())[0];
await d.NotificationDismissAsync((string)n.Key!);KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_dismiss "$KEY"curl -s -X POST localhost:8780/devices/_/notification_dismiss \
-H 'content-type: application/json' \
-d '{"key":"KEY"}'{"id":1,"cmd":"notification_dismiss","key":"KEY"}notify_filter
Choose which apps' notifications are sent to the PC. Default is none
| Name | Type | Default | Meaning |
|---|---|---|---|
packages | list<string> | Allowed packages. Omit to read the current list |
Returns: a value of type list<string>
d.notify_filter(["com.android.chrome", "com.google.android.gm"])await d.notifyFilter(["com.android.chrome", "com.google.android.gm"]);await d.NotifyFilterAsync(new[] { "com.android.chrome", "com.google.android.gm" });droidline notify_filter com.android.chrome,com.google.android.gmcurl -s -X POST localhost:8780/devices/_/notify_filter \
-H 'content-type: application/json' \
-d '{"packages":["com.android.chrome","com.google.android.gm"]}'{"id":1,"cmd":"notify_filter","packages":["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.
| Name | Type | Default | Meaning |
|---|---|---|---|
package | string | Only from this app | |
textContains | string | Only if title or text contains this |
Returns: nothing
stop = d.on_notification(package="com.google.android.gm", callback=print)
# ... later
stop()const stop = await d.onNotification({ package: "com.google.android.gm" }, (n) => console.log(n.title, n.text));
// ... later
stop();var stop = await d.OnNotificationAsync(n => Console.WriteLine($"{n.Title} {n.Text}"), package: "com.google.android.gm");
// ... later
stop.Dispose();droidline on_notification --package com.google.android.gm{"id":1,"cmd":"subscribe","events":["notification"]}Messages, calls and contacts
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.
| Name | Type | Default | Meaning |
|---|---|---|---|
box | string inbox | sent | all | "inbox" | Received, sent, or both |
address | string | Only messages whose number or sender contains this. Spaces and dashes are ignored | |
contains | string | Only messages whose text contains this, ignoring case | |
within | number | 0 s | Only messages from the last this many seconds. 0 means any time |
max | int | 20 | Most messages to return, up to 500 |
Returns: a value of type list<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.
| Name | Type | Default | Meaning |
|---|---|---|---|
type | string all | incoming | outgoing | missed | rejected | blocked | "all" | Which calls |
number | string | Only calls whose number or saved name contains this. Spaces and dashes are ignored | |
within | number | 0 s | Only calls from the last this many seconds. 0 means any time |
max | int | 20 | Most calls to return, up to 500 |
Returns: a value of type list<call>
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.
| Name | Type | Default | Meaning |
|---|---|---|---|
query | string | Only contacts whose name, number or email contains this, ignoring case. Spaces and dashes in numbers are ignored | |
max | int | 50 | Most contacts to return, up to 500 |
Returns: a value of type list<contact>
Server
devicesleasereleasepairpair_qrrenamerevokesubscribeserver_infoauth
devices
Paired devices with online state and route
Returns: a value of type list<device>
dl.devices()await dl.devices();await client.DevicesAsync();droidline devicescurl -s localhost:8780/devices{"id":1,"cmd":"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.
| Name | Type | Default | Meaning |
|---|---|---|---|
device | string | This phone, by ID or name. Omit to take any free one | |
wait | number | 30 s | Seconds to wait for a phone to become free |
ttl | number | 300 s | The lease ends after this many seconds without a command |
min_sdk | int | Only phones with at least this Android API level, such as 33 | |
model | string | Only 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)await dl.lease({ wait: 60 });await client.LeaseAsync(wait: 60);droidline lease --waitcurl -s -X POST localhost:8780/server/lease \
-H 'content-type: application/json'{"id":1,"cmd":"lease"}release
Give a leased phone back
Pass the lease, or a device to free a phone whose script crashed while holding it.
| Name | Type | Default | Meaning |
|---|---|---|---|
lease | string | The lease that lease returned | |
device | string | Free this phone whatever lease holds it |
Returns: nothing
dl.release("l-3f9a1c0d2e4b")await dl.release("l-3f9a1c0d2e4b");await client.ReleaseAsync("l-3f9a1c0d2e4b");droidline release l-3f9a1c0d2e4bcurl -s -X POST localhost:8780/server/release \
-H 'content-type: application/json' \
-d '{"lease":"l-3f9a1c0d2e4b"}'{"id":1,"cmd":"release","lease":"l-3f9a1c0d2e4b"}pair
Approve the phone that shows this 6-digit code
| Name | Type | Default | Meaning |
|---|---|---|---|
code | string | required | Code shown on the phone |
name | string | Name to give the device |
Returns: a value of type device
Errors: PAIRING_FAILED
dl.pair("482913", name="shelf-01")await dl.pair("482913", { name: "shelf-01" });await client.PairAsync("482913", name: "shelf-01");droidline pair 482913 --name shelf-01curl -s -X POST localhost:8780/server/pair \
-H 'content-type: application/json' \
-d '{"code":"482913","name":"shelf-01"}'{"id":1,"cmd":"pair","code":"482913","name":"shelf-01"}pair_qr
Create a one-time pairing QR code valid for 10 minutes
| Name | Type | Default | Meaning |
|---|---|---|---|
name | string | Name to give the device |
Returns: an object with uri, expires
dl.pair_qr()await dl.pairQr();await client.PairQrAsync();droidline pair # shows the QR code in the terminalcurl -s -X POST localhost:8780/server/pair_qr \
-H 'content-type: application/json'{"id":1,"cmd":"pair_qr"}rename
Give a device a name
| Name | Type | Default | Meaning |
|---|---|---|---|
device | string | required | Device ID or name |
name | string | required | New name |
Returns: a value of type device
dl.rename("k7d2q9xa", "shelf-01")await dl.rename("k7d2q9xa", "shelf-01");await client.RenameAsync("k7d2q9xa", "shelf-01");droidline rename k7d2q9xa shelf-01curl -s -X POST localhost:8780/server/rename \
-H 'content-type: application/json' \
-d '{"device":"k7d2q9xa","name":"shelf-01"}'{"id":1,"cmd":"rename","device":"k7d2q9xa","name":"shelf-01"}revoke
Unpair a device. It must pair again to connect
| Name | Type | Default | Meaning |
|---|---|---|---|
device | string | required | Device ID or name |
Returns: nothing
dl.revoke("shelf-01")await dl.revoke("shelf-01");await client.RevokeAsync("shelf-01");droidline revoke shelf-01curl -s -X POST localhost:8780/server/revoke \
-H 'content-type: application/json' \
-d '{"device":"shelf-01"}'{"id":1,"cmd":"revoke","device":"shelf-01"}subscribe
Receive events on this connection
| Name | Type | Default | Meaning |
|---|---|---|---|
events | list<string> | required | Any of notification, screen, toast, device, result, action |
device | string | Only from this device. Omit for all |
Returns: nothing
dl.subscribe(["notification"])await dl.subscribe(["notification"]);await client.SubscribeAsync(new[] { "notification" });{"id":1,"cmd":"subscribe","events":["notification"]}server_info
Server version, ports and listening addresses
Returns: an object with version, server, name, proto, agent_port, client_port
dl.server_info()await dl.serverInfo();await client.ServerInfoAsync();droidline server_infocurl -s -X POST localhost:8780/server/server_info \
-H 'content-type: application/json'{"id":1,"cmd":"server_info"}auth
Authenticate this client connection with a token
| Name | Type | Default | Meaning |
|---|---|---|---|
token | string | required | Client token from droidline token |
Returns: nothing
dl.auth("your-client-token")await dl.auth("your-client-token");await client.AuthAsync("your-client-token");{"id":1,"cmd":"auth","token":"your-client-token"}