명령어 레퍼런스

Droidline 전체 명령의 파라미터, 반환값, 에러와 Python, Node.js, CLI, HTTP에서의 같은 호출.

번역된 페이지입니다. 영어 문서와 내용이 다르면 영어 문서가 기준입니다. English

명령마다 하는 일, 파라미터, 반환값, 날 수 있는 에러를 보여 주고, 이어서 같은 호출을 인터페이스별로 보여 줍니다. 아무 예제에서나 언어를 고르면 페이지 전체가 그 언어로 바뀝니다. Python 예제는 d = connect()(서버 명령은 dl = Droidline())를, Node.js 예제는 const d = await connect()(const dl = new Droidline())를 이미 실행했다고 가정합니다.

화면

dumpscreenshotcurrent

dump

현재 화면 노드 트리를 반환

이름타입기본값의미
pathstring이 로컬 파일에 JSON으로 저장
all_windowsboolfalse상태 표시줄, 키보드 같은 시스템 창도 포함

반환: 다음 필드를 가진 객체: package, activity, width, height, tree

필요 권한: 접근성 서비스

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

screenshot

화면 캡처

Android 11 이상은 접근성 스크린샷, 9~10은 처음 한 번 화면 캡처 허용 팝업

이름타입기본값의미
pathstring이 로컬 파일에 저장. 확장자로 png/jpeg 결정
formatstring png | jpeg"jpeg"이미지 형식
qualityint80JPEG 품질 1~100
scalenumber1축소 비율 0.1~1.0, 모바일 데이터에서 유용

반환: 다음 필드를 가진 객체: format, width, height, data

필요 권한: 접근성 서비스

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

current

지금 떠 있는 패키지명과 액티비티명

반환: 다음 필드를 가진 객체: package, activity

필요 권한: 접근성 서비스

d.current()

좌표

taplong_tapswipe

tap

좌표 탭

이름타입기본값의미
xint필수화면 픽셀 X
yint필수화면 픽셀 Y

반환: 다음 필드를 가진 객체: ms

필요 권한: 접근성 서비스

d.tap(540, 1200)

long_tap

좌표 길게 누르기

이름타입기본값의미
xint필수화면 픽셀 X
yint필수화면 픽셀 Y
msint800누르는 시간(ms)

반환: 다음 필드를 가진 객체: ms

필요 권한: 접근성 서비스

d.long_tap(540, 1200, 800)

swipe

두 좌표 사이 또는 방향으로 스와이프

이름타입기본값의미
x1int|string필수시작 X 또는 방향: up, down, left, right
y1int시작 Y
x2int끝 X
y2int끝 Y
msint300시간(ms)

반환: 다음 필드를 가진 객체: ms

필요 권한: 접근성 서비스

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

요소

touchlong_touchscroll_to

touch

대상이 뜰 때까지 기다렸다가 누르기

노드 클릭이 거부되면 bounds 중심을 좌표 탭. via에 node, parent, gesture 중 성공한 경로 표시

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터
timeoutnumber10 s대상이 뜰 때까지 기다리는 초

반환: 다음 필드를 가진 객체: via, ms

줄임 이름: touchById(value), touchByText(value), touchByDesc(value)

에러: NOT_FOUND, NOT_CLICKABLE, NO_ACCESSIBILITY

필요 권한: 접근성 서비스

d.touch("text", "로그인")

long_touch

대상을 기다렸다가 길게 누르기

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
msint800누르는 시간(ms)
nthint0같은 대상이 여럿일 때 순번, 0부터
timeoutnumber10 s대상이 뜰 때까지 기다리는 초

반환: 다음 필드를 가진 객체: via, ms

필요 권한: 접근성 서비스

d.long_touch("text", "메시지")

scroll_to

대상이 보일 때까지 스크롤

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
directionstring down | up | left | right"down"스크롤 방향
max_swipesint20이만큼 스와이프해도 없으면 포기
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 필드를 가진 객체: swipes

필요 권한: 접근성 서비스

d.scroll_to("text", "설정")

입력

inputclearsendkey

input

입력칸을 기다렸다가 글자 넣기

접근성 글자 설정 동작을 쓰고, 이를 무시하는 칸은 자체 키보드가 선택돼 있으면 키보드로 입력

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
textstring필수넣을 글자
appendboolfalse기존 글자 뒤에 이어 붙이기
nthint0같은 대상이 여럿일 때 순번, 0부터
timeoutnumber10 s대상이 뜰 때까지 기다리는 초

반환: 다음 필드를 가진 객체: via, ms

필요 권한: 접근성 서비스

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

clear

입력칸 비우기

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터
timeoutnumber10 s대상이 뜰 때까지 기다리는 초

반환: 다음 필드를 가진 객체: ms

필요 권한: 접근성 서비스

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

sendkey

키 이름, 키코드, 또는 글자 보내기

back, home, recents, notifications, quick_settings, lock은 접근성 전역 동작. 그 외 키와 글자는 자체 키보드로 포커스된 칸에 전송

이름타입기본값의미
keystring|int키 이름(enter, tab, del, space, escape, up, down, left, right, back, home 등), 안드로이드 키코드, 또는 입력할 글자
textstring키 이름과 같아도 글자 그대로 입력

반환: 다음 필드를 가진 객체: via

에러: NO_IME, BAD_ARGS

필요 권한: 접근성 서비스

d.sendkey("enter")

확인

existswaitwait_goneget_text

exists

지금 화면에 대상이 있는지. 기다리지 않음

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

d.exists("text", "광고 닫기")

wait

대상이 뜰 때까지 대기

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
timeoutnumber10 s대상이 뜰 때까지 기다리는 초
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 필드를 가진 객체: ms

에러: NOT_FOUND

필요 권한: 접근성 서비스

d.wait("text", "완료", timeout=30)

wait_gone

대상이 사라질 때까지 대기

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
timeoutnumber10 s대상이 뜰 때까지 기다리는 초

반환: 다음 필드를 가진 객체: ms

에러: TIMEOUT

필요 권한: 접근성 서비스

d.wait_gone("text", "불러오는 중")

get_text

대상의 글자, 없으면 빈 문자열

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 타입의 값: string

필요 권한: 접근성 서비스

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

조건

checkedenabledselectedcountwhichin_appkeyboard_shownlast_toastcolor

checked

스위치·체크박스가 켜져 있으면 true

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

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

enabled

버튼이 눌릴 수 있는 상태면 true

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

d.enabled("text", "다음")

selected

탭이 선택된 상태면 true

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값
nthint0같은 대상이 여럿일 때 순번, 0부터

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

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

count

조건에 맞는 요소 개수

이름타입기본값의미
byselector필수어느 dump 속성으로 찾을지: text, textContains, id, desc, descContains, class
valuestring필수찾을 값

반환: 다음 타입의 값: int

필요 권한: 접근성 서비스

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

which

여러 후보 중 먼저 나타난 것의 순번, 없으면 -1

이름타입기본값의미
candidateslist<selector_pair>필수[속성, 값] 쌍의 목록
timeoutnumber10 s후보가 뜰 때까지 기다리는 초

반환: 다음 타입의 값: int

필요 권한: 접근성 서비스

d.which([("text", "로그인"), ("id", "main_tab")], timeout=15)

in_app

지금 그 앱이 앞에 떠 있으면 true

이름타입기본값의미
packagestring필수패키지명, 예: com.android.chrome

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

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

keyboard_shown

키보드가 올라와 있으면 true

반환: 다음 타입의 값: bool

필요 권한: 접근성 서비스

d.keyboard_shown()

last_toast

최근 토스트 메시지 글자, 없으면 빈 문자열

이름타입기본값의미
max_agenumber30 s이 초보다 오래된 토스트는 무시

반환: 다음 타입의 값: string

필요 권한: 접근성 서비스

d.last_toast()

color

해당 좌표의 색(#RRGGBB)

노드가 없는 화면(게임 등) 분기용

이름타입기본값의미
xint필수화면 픽셀 X
yint필수화면 픽셀 Y

반환: 다음 타입의 값: string

필요 권한: 접근성 서비스

d.color(540, 1200)

기기

screen_onlockedwakelockbatteryorientationinfo

screen_on

화면이 켜져 있으면 true

반환: 다음 타입의 값: bool

d.screen_on()

locked

잠금 화면이면 true

반환: 다음 타입의 값: bool

d.locked()

wake

화면을 켜고, PIN이 없는 잠금 화면은 해제

화면이 꺼져 있으면 제스처가 실패합니다. PIN·패턴·비밀번호 잠금은 사람이 풀어야 합니다

반환: 다음 필드를 가진 객체: screen_on, locked

d.wake()

lock

화면 끄고 잠그기

반환: 없음

필요 권한: 접근성 서비스

d.lock()

battery

배터리 잔량, 충전 중 여부

반환: 다음 필드를 가진 객체: level, charging, temperature

d.battery()

orientation

화면 방향: portrait 또는 landscape

반환: 다음 타입의 값: string

d.orientation()

info

모델, 안드로이드 버전, 화면 크기, 권한 준비 상태

반환: 다음 필드를 가진 객체: model, manufacturer, sdk, release, agent, width, height, ready

d.info()

네트워크

networkproxyproxy_check

network

연결 종류(wifi, mobile, none)와 비행기 모드 여부

반환: 다음 필드를 가진 객체: type, airplane, metered

d.network()

proxy

앱별 VPN으로 고른 앱만 업스트림 프록시로 보내기

http://(CONNECT)와 socks5://, user:pass 인증 지원. null이나 "off"로 끔. 업스트림은 한 번에 하나. 프록시 설정을 무시하는 앱은 새지 않고 연결이 막힘

이름타입기본값의미
urlstring|null필수socks5://user:pass@host:port, http://host:port, @kr1 같은 저장된 프로필, 또는 off
appstring|list<string>프록시로 보낼 패키지(여러 개 가능)

반환: 다음 필드를 가진 객체: active, apps

에러: NO_PERMISSION, PROXY_FAILED, UNSUPPORTED

필요 권한: VPN 권한 · Android API 29+

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

proxy_check

앱별 프록시 연결 상태와 바깥에서 보이는 IP

이름타입기본값의미
appstring확인할 패키지

반환: 다음 필드를 가진 객체: active, ip, upstream, error

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

앱

launchopen_urlkillclear_dataappsinstalled

launch

앱 실행, 선택적으로 특정 액티비티

이름타입기본값의미
packagestring필수패키지명, 예: com.android.chrome
activitystring액티비티명, 전체 이름 또는 점으로 시작

반환: 다음 필드를 가진 객체: ms

에러: APP_NOT_FOUND, ACTIVITY_BLOCKED

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

open_url

URL이나 딥링크 열기

이름타입기본값의미
urlstring필수http(s) 주소 또는 앱 딥링크
packagestring이 앱으로만 열기

반환: 없음

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

kill

앱 강제 종료

설정 매크로: 앱 정보 → 강제 중지 → 확인. 몇 초 소요

이름타입기본값의미
packagestring필수패키지명, 예: com.android.chrome

반환: 다음 필드를 가진 객체: via, ms

에러: APP_NOT_FOUND, MACRO_FAILED

필요 권한: 접근성 서비스

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

clear_data

앱 데이터 삭제

설정 매크로: 앱 정보 → 저장공간 → 데이터 삭제 → 확인

이름타입기본값의미
packagestring필수패키지명, 예: com.android.chrome

반환: 다음 필드를 가진 객체: via, ms

에러: APP_NOT_FOUND, MACRO_FAILED

필요 권한: 접근성 서비스

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

apps

설치된 패키지 목록

이름타입기본값의미
systemboolfalse시스템 패키지 포함

반환: 다음 타입의 값: list<app>

d.apps()

installed

설치돼 있으면 버전명, 아니면 빈 문자열

이름타입기본값의미
packagestring필수패키지명, 예: com.android.chrome

반환: 다음 타입의 값: string

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

시스템

backhomerecentsopen_notificationsquick_settingsdatawifiairplaneclipboardbatch

back

뒤로

반환: 없음

필요 권한: 접근성 서비스

d.back()

home

홈 화면

반환: 없음

필요 권한: 접근성 서비스

d.home()

recents

최근 앱

반환: 없음

필요 권한: 접근성 서비스

d.recents()

open_notifications

알림창 내리기

반환: 없음

필요 권한: 접근성 서비스

d.open_notifications()

quick_settings

빠른 설정 열기

반환: 없음

필요 권한: 접근성 서비스

d.quick_settings()

data

모바일 데이터 끄기·켜기

폰 자신의 연결을 끊는 명령입니다. 먼저 accepted로 답하며, wait를 주면 최종 결과를 받습니다.

이름타입기본값의미
onbool필수true면 켜기, false면 끄기

반환: 다음 필드를 가진 객체: via, ms

에러: MACRO_FAILED

필요 권한: 접근성 서비스

d.data(False, wait=True)

wifi

와이파이 끄기·켜기

폰 자신의 연결을 끊는 명령입니다. 먼저 accepted로 답하며, wait를 주면 최종 결과를 받습니다.

이름타입기본값의미
onbool필수true면 켜기, false면 끄기

반환: 다음 필드를 가진 객체: via, ms

에러: MACRO_FAILED

필요 권한: 접근성 서비스

d.wifi(False, wait=True)

airplane

비행기 모드 켜기·끄기

IP 갱신은 켜기·끄기를 batch 하나로 묶어야 폰이 끊긴 동안에도 둘 다 실행합니다

폰 자신의 연결을 끊는 명령입니다. 먼저 accepted로 답하며, wait를 주면 최종 결과를 받습니다.

이름타입기본값의미
onbool필수true면 켜기, false면 끄기

반환: 다음 필드를 가진 객체: via, ms

에러: MACRO_FAILED

필요 권한: 접근성 서비스

d.airplane(True, wait=True)

clipboard

클립보드 쓰기, 글자 없이 부르면 읽기

Android 10 이상에서 읽기는 자체 키보드가 현재 입력기여야 가능

이름타입기본값의미
textstring복사할 글. 생략하면 읽기

반환: 다음 타입의 값: string

에러: NO_IME

d.clipboard("안녕하세요")

batch

여러 명령을 폰에서 한 번에 실행, 끊긴 동안에도 계속

단계는 [명령, 인자...] 목록이나 {cmd, ...} 객체. sleep(ms)는 batch 안에서만 씀. 망을 끊는 단계가 있으면 accepted로 먼저 답하고 재접속 후 결과가 옴

이름타입기본값의미
stepslist<step>필수순서대로 실행할 명령
stop_on_errorbooltrue실패한 단계에서 멈춤

반환: 다음 필드를 가진 객체: results

d.batch([("airplane", True), ("sleep", 3000), ("airplane", False)], wait=True)

크롬

chrome.go

chrome.go

크롬에서 주소 열기

이름타입기본값의미
urlstring필수주소. https://가 없으면 붙임
new_tabboolfalse새 탭에서 열기

반환: 다음 필드를 가진 객체: ms

에러: APP_NOT_FOUND

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

알림

notificationshas_notificationwait_notificationnotification_replynotification_clicknotification_dismissnotify_filteron_notification

notifications

지금 떠 있는 알림 목록

이름타입기본값의미
packagestring이 앱만

반환: 다음 타입의 값: list<notification>

필요 권한: 알림 접근

d.notifications()

has_notification

지금 떠 있는 알림 중 조건에 맞는 게 있으면 true

이름타입기본값의미
bystring text | textContains | title | package필수text, textContains는 제목과 본문 모두에서 찾음
valuestring필수찾을 값

반환: 다음 타입의 값: bool

필요 권한: 알림 접근

d.has_notification("textContains", "배송")

wait_notification

조건에 맞는 알림이 오면 내용 반환

PC 서버가 처리하므로 폰의 다른 명령을 막지 않습니다. Android 15 이상은 인증번호를 가려서 넘기므로 알림 도착만 알 수 있습니다

이름타입기본값의미
bystring text | textContains | title | package필수text, textContains는 제목과 본문 모두에서 찾음
valuestring필수찾을 값
timeoutnumber60 s기다리는 초
packagestring이 앱에서 온 것만

반환: 다음 타입의 값: notification

에러: TIMEOUT

필요 권한: 알림 접근

dl.wait_notification("textContains", "인증번호", 60)

notification_reply

답장 버튼이 있는 알림에 바로 답장

이름타입기본값의미
keystring필수notifications() 또는 알림 이벤트의 key
textstring필수답장 글

반환: 없음

필요 권한: 알림 접근

n = d.notifications()[0]
d.notification_reply(n["key"], "가는 중이에요")

notification_click

알림을 눌러 해당 화면 열기

이름타입기본값의미
keystring필수notifications() 또는 알림 이벤트의 key

반환: 없음

필요 권한: 알림 접근

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

notification_dismiss

알림 지우기

이름타입기본값의미
keystring필수notifications() 또는 알림 이벤트의 key

반환: 없음

필요 권한: 알림 접근

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

notify_filter

PC로 보낼 알림 앱 고르기. 기본값은 아무 앱도 보내지 않음

이름타입기본값의미
packageslist<string>허용할 패키지. 생략하면 현재 목록 조회

반환: 다음 타입의 값: list<string>

필요 권한: 알림 접근

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

on_notification

조건에 맞는 알림마다 함수 호출

SDK 전용, subscribe 위에 구현. CLI는 맞는 알림을 JSON 줄로 출력

SDK 안에서 동작합니다. 서버에는 subscribe 줄이 갑니다.

이름타입기본값의미
packagestring이 앱에서 온 것만
textContainsstring제목이나 본문에 이 글이 있을 때만

반환: 없음

필요 권한: 알림 접근

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

서버

devicespairpair_qrrenamerevokesubscribeserver_infoauth

devices

등록된 기기와 온라인 상태, 접속 경로

반환: 다음 타입의 값: list<device>

dl.devices()

pair

이 6자리 코드를 띄운 폰을 등록

이름타입기본값의미
codestring필수폰에 표시된 코드
namestring기기에 붙일 이름

반환: 다음 타입의 값: device

에러: PAIRING_FAILED

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

pair_qr

10분 동안 유효한 일회용 페어링 QR 만들기

이름타입기본값의미
namestring기기에 붙일 이름

반환: 다음 필드를 가진 객체: uri, expires

dl.pair_qr()

rename

기기 이름 바꾸기

이름타입기본값의미
devicestring필수기기 ID 또는 이름
namestring필수새 이름

반환: 다음 타입의 값: device

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

revoke

기기 등록 폐기. 다시 페어링해야 접속 가능

이름타입기본값의미
devicestring필수기기 ID 또는 이름

반환: 없음

dl.revoke("shelf-01")

subscribe

이 연결로 이벤트 받기

이름타입기본값의미
eventslist<string>필수notification, screen, toast, device, result 중에서
devicestring이 기기 것만. 생략하면 전체

반환: 없음

dl.subscribe(["notification"])

server_info

서버 버전, 포트, 대기 주소

반환: 다음 필드를 가진 객체: version, server, name, proto, agent_port, client_port

dl.server_info()

auth

이 클라이언트 연결을 토큰으로 인증

이름타입기본값의미
tokenstring필수droidline token으로 만든 클라이언트 토큰

반환: 없음

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