TurboADB

Command line

Everything TurboADB does, as one-line commands you can script. Every device command takes -s SERIAL (or -s @saved-name); add --adb-host HOST to drive a device plugged into another PC.

Getting startedGlobal options SetupDevices Shell & logsFiles AppsScreen Keys & inputConnectivity Open appsStatus PhoneRoot ForwardingSharing

Getting started

adb and scrcpy download themselves on first use (adb on Windows, macOS and x86-64 Linux, scrcpy on Windows; elsewhere the ones on PATH are used), and neither is ever taken from the current folder. turboadb -h lists the commands and turboadb <command> -h shows one command's options.

pip install turboadb
turboadb doctor                                   # are adb and scrcpy available?
turboadb devices                                  # what's attached
turboadb -s 10BE330KG9000AF info                  # one device by serial
turboadb -s 192.168.1.50:5555 screenshot shot.png # a network device
turboadb --adb-host lab-pc-01 -s DEVICE info      # a device on another PC
turboadb targets add bench network 192.168.1.50   # save a target once…
turboadb -s @bench info                           # …and use it by name

Global options, output and exit codes

Device options work before or after the command name, so turboadb -s SERIAL info and turboadb info -s SERIAL are the same — but before the words of shell, adb, text, search and send-sms, which take everything after their first word as it is (text, search and send-sms refuse an option among their words; -- before the words sends them exactly as written). The setup commands (doctor, fetch-tools, upgrade-tools, self-update, shortcut, gui, deploy-serve) drive no device, so of these they take only --json.

OptionMeaning
-s, --serial SERIALThe device: a USB serial or host:port, or @NAME for a saved target. Omit it when only one device is attached.
--adb-host HOSTUse another PC's adb server (that PC runs turboadb serve).
--adb-port PORTadb server port (default 5037).
--adb-path PATHUse this adb executable (or its folder). A path with no adb is an error — never a silent switch to another adb.
--scrcpy-path PATHUse this scrcpy executable.
--timeout SECONDSTimeout for each command (default 60 s) and for bugreport (default 15 minutes); a push or pull fails only after this long without progress (default 600 s); install, cp and rm have longer limits of their own, which a longer value extends and a shorter one never cuts; 0 for no limit. shell -- COMMAND and adb -- ARGS stream as long as they run unless it is given.
--jsonOne JSON document on stdout (progress and warnings go to stderr): data as JSON, actions as {"ok": …, "message": …} (the targets actions, and forward/reverse after Ctrl+C, too), returned values as {"ok": …, "result": …}, saved files as {"ok": …, "path": …}, a --full report as {"ok": …, "report": …}, serve as {"ok": …, "port": …, "messages": […]}. The setup commands take it too; logcat streams plain lines.
-V, --versionPrint the TurboADB version.
Exit codeMeaning
0Success.
1The action failed or the device refused it (one ERROR: line explains why).
2Wrong command-line usage.
3adb not found — run turboadb fetch-tools — or --adb-path / TURBOADB_ADB names no adb.
130Stopped with Ctrl+C.

shell and adb exit with the device command's own code.

EnvironmentEffect
TURBOADB_ADBPath to the adb executable (one that names no adb is an error).
TURBOADB_SCRCPYPath to the scrcpy executable (the same rule).
TURBOADB_AUTO_FETCH=0Never download adb / scrcpy automatically.
VISUAL, EDITORThe editor turboadb edit opens.

Setup and tools

CommandWhat it doesOptions
doctorReport whether adb and scrcpy were found, and where; the running adb server (release, protocol, executable — and a warning when another adb's server would keep being restarted); and which TurboADB runs, with a warning when this Python has a different copy installed.--json
fetch-toolsDownload adb (and scrcpy) into ~/.turboadb/tools: adb where Google builds it for the machine (Windows, macOS, x86-64 Linux), scrcpy on Windows. --adb-only and --scrcpy-only are mutually exclusive.--adb-only | --scrcpy-only --force --json
upgrade-toolsUpdate adb and scrcpy only when a newer version exists.--check --json
self-updateUpgrade TurboADB from PyPI (exactly the version it offers — a lagging package mirror is reported, not called an update), then adb and scrcpy. A source checkout updates with git pull.--check --json
shortcutCreate Desktop and Start-menu shortcuts (Windows). They start the TurboADB installed in this Python, so a different running copy (a source checkout) changes nothing and says why. Without PyQt5 they start turboadb-gui; where nothing could start the app, none is written and the command exits 1.--json
guiLaunch the desktop app.
 
turboadb fetch-tools --scrcpy-only --force
turboadb self-update --check

Devices and connection

CommandWhat it doesArguments & options
devicesList devices on the local adb server, or the one --adb-host (or -s @NAME) selects. A missing adb exits 3, and a server that cannot be started or reached exits 1 with the reason, never "No devices found".--json
infoIdentity and build: model, Android, CPU, device type (phone, tablet, tv, watch, automotive, head unit), telephony, display size.--json
connectadb connect to a network device.HOST:PORT
disconnectDisconnect one network device, or all.[HOST:PORT] --json
pairPair with an Android 11+ device (Wireless debugging).HOST:PORT CODE --json
tcpipRestart adbd on a USB device in TCP mode.[PORT=5555]
wirelessUSB → Wi-Fi in one step: read the IP, tcpip, connect.[PORT=5555]
discoverFind Wireless-debugging devices on the network (mDNS) — with --adb-host, on that PC's network, through its adb server.--connect --json
stop-serverStop the adb server, leaving no adb daemon running.--json
restart-serverKill and start the adb server (devices not showing up).--json
waitWait until the device is online.[SECONDS]
stateThe adb state: device, offline, unauthorized, recovery, bootloader… (works while rebooting).
serialnoThe device's serial number.
ipThe device's Wi-Fi / Ethernet IP address.
targetsSaved targets (the GUI sidebar's list); use one with -s @NAME.list add NAME usb [SERIAL] add NAME network HOST[:PORT] add NAME remote ADBHOST[:PORT] [SERIAL] remove NAME export FILE import FILE --json
 
turboadb connect 192.168.1.50:5555
turboadb pair 192.168.1.50:37123 482913
turboadb -s SERIAL wireless
turboadb discover --connect
turboadb targets add lab remote lab-pc-01 10BE330KG9000AF
turboadb -s @lab screenshot lab.png

Shell, logs and reports

CommandWhat it doesArguments & options
shellRun a command on the device (put -- before it), on every device of the selected adb server, or a batch file; no command opens an interactive shell. Output streams as the device writes it (ping, top, logcat), with no time limit unless --timeout is given; --json collects it. A batch file is read as UTF-8 (with or without a byte order mark) or, by its mark, as UTF-16 or UTF-32.COMMAND… --su --all --batch FILE --keep-going --json
adbAny adb command for the selected device (-s, --adb-host added for you), attached to your console as adb itself runs: streaming output, byte-exact exec-out, prompts. --timeout limits it; --json collects it.-- ARGS…
logcatStream logcat live, filtered, and save it.--tag TAG --priority V|D|I|W|E|F --filter TAG:LEVEL (repeat) --buffer NAME (repeat) --crashes --pid PID --package NAME --grep REGEX --match REGEX --stop-on-match --format threadtime --save FILE --clear --dump --tail N
logcat-clearClear the logcat buffers.
bugreportCapture a full bug report zip (a few minutes; --timeout sets the limit, 0 for none). PATH is a file (.zip is added when it lacks it) or an existing folder; the file that was saved is printed.[PATH]
 
turboadb -s SERIAL shell
turboadb -s SERIAL shell -- getprop ro.build.version.release
turboadb shell --all -- getprop ro.product.model
turboadb -s SERIAL shell --batch setup.txt --keep-going
turboadb -s SERIAL logcat --crashes --dump
turboadb -s SERIAL logcat --filter ActivityManager:I --grep "ANR|FATAL" --save crash.log

Files

Paths are checked first: a missing path, or a folder without -r, is an error and nothing changes.

CommandWhat it doesArguments & options
pushUpload a file or folder to the device, with progress.LOCAL REMOTE --json
pullDownload a file or folder from the device, with progress. The result counts what this pull copied; on Windows a name with a character Windows forbids is saved under a valid one.REMOTE LOCAL --json
lsList a device folder: permissions, owner, size, date, name.[PATH=/sdcard] --json
mkdirCreate folders, with any missing parents.PATH…
touchCreate empty files.PATH…
rmDelete files, and folders with -r (/ is always refused).PATH… -r
mvMove or rename; into a folder when the destination is one (a folder given its own name in other letters is renamed).SRC DST -f
cpCopy a file or folder; into an existing folder it merges. A link is copied as a link, an item of another kind is never overwritten, and a folder is never copied into itself.SRC DST
statPath, real path, type, size and octal mode.PATH --json
editEdit a device text file in a local editor; saved back only when changed, keeping its permissions. The editor is found on PATH (code is code.cmd on Windows), never in the current folder.PATH --editor "code --wait"
 
turboadb -s SERIAL push app.apk /data/local/tmp/
turboadb -s SERIAL ls /sdcard/Download
turboadb -s SERIAL mv /sdcard/clip.mp4 /sdcard/Movies
turboadb -s SERIAL rm -r /sdcard/logs
turboadb -s SERIAL edit /data/local/tmp/config.ini

Apps

CommandWhat it doesArguments & options
packagesList installed packages.[FILTER] --third-party --system --enabled --disabled --path --json
installInstall one APK, or several as a split install.APK… --grant --downgrade --no-replace --test
uninstallUninstall a package; --keep-data keeps its data and cache (through the device's package manager, as adb refuses the option).PACKAGE --keep-data
clearClear an app's data (the foreground user's copy on a device with several users, such as Android Automotive).PACKAGE
startLaunch an app by package (works on head units too).PACKAGE
start-activityStart an activity with an optional action, data and extras.PKG/.Activity --action --data --es K V --ei K V --ez K V
activityThe activity in the foreground.
stopForce-stop an app.PACKAGE
grantGrant a runtime permission (to the foreground user's copy of the app).PACKAGE PERMISSION
revokeRevoke a runtime permission (for the foreground user's copy of the app).PACKAGE PERMISSION
close-appsClose background apps.
 
turboadb -s SERIAL packages --disabled
turboadb -s SERIAL install app-debug.apk --grant --test
turboadb -s SERIAL start-activity com.example/.MainActivity --es mode demo
turboadb -s SERIAL grant com.example.app android.permission.ACCESS_FINE_LOCATION

Screen, capture and mirroring

--display N picks one display of a multi-display head unit (cluster, centre stack, passenger); displays lists the ids.

CommandWhat it doesArguments & options
displaysList the device's displays: id, size, name.--method auto|adb|scrcpy --json
screenshotSave a PNG screenshot.PATH --display N
recordRecord on the device and pull the MP4 (works over RDP; Ctrl+C stops and saves). --continuous records past the 3-minute cap in parts. PATH may be a folder: the recording is saved there as recording-DATE-TIME.mp4.PATH --time-limit 30 --size WxH --bit-rate 8M --display N --continuous --json
scrcpyMirror and control the screen, or the device camera. --compat is the profile for head units that won't mirror with the defaults.--display-id N --compat --max-size PX --bit-rate --max-fps --video-codec h264|h265|av1 --crop W:H:X:Y --render-driver --keyboard sdk|uhid|aoa --force-adb-forward --no-audio --audio-source --audio-codec --audio-bit-rate --audio-buffer --audio-output-buffer --audio-dup --record FILE --record-format mp4|mkv --no-playback --turn-screen-off --no-stay-awake --show-touches --no-control --fullscreen --always-on-top --window-borderless --window-title --video-source display|camera --camera-facing --camera-size --log FILE --wait --json
screenTurn the device screen on or off.on|off
 
turboadb -s SERIAL displays
turboadb -s SERIAL screenshot cluster.png --display 2
turboadb -s SERIAL record drive.mp4 --continuous
turboadb -s SERIAL scrcpy --compat --display-id 2 --log scrcpy.log
turboadb -s SERIAL scrcpy --no-playback --record drive.mkv --record-format mkv

Keys and input

CommandWhat it doesArguments & options
keySend keys in order, by name or keycode: home, back, recents, menu, search, power, sleep, wake, notifications, call, enter, del, tab, space, esc, up, down, left, right, center, vol_up, vol_down, vol_mute, play_pause, media_play, media_pause, stop, next, prev, rewind, fast_forward, brightness_up, brightness_down.KEY… --longpress --display N
textType text into the focused field. Options go before the text (-- types it exactly as written).TEXT… --display N
tapTap a point, or the centre of the screen.[X Y] --display N
tap-burstTap one point many times from a single device-side loop (soak and stress testing).X Y --count 100 --rate --duration --display --method auto|input|events --json
touch-deviceThe touchscreen a tap burst can write to, and whether the shell may. Exits 1 when none is found, with --json too.--json
swipeSwipe from one point to another.X1 Y1 X2 Y2 --ms 200 --display N
scrollScroll with a swipe.up|down|left|right --display N
mediaMedia control through the active session.play-pause|play|pause|next|previous|stop|fast-forward|rewind|mute
brightnessSet brightness live, or read / set / step the 0–255 setting.[0.0–1.0] --get --level N --step N
notificationsOpen or close the notification shade.expand|collapse
 
turboadb -s SERIAL key down down enter
turboadb -s SERIAL key power --longpress
turboadb -s SERIAL tap 540 1200 --display 2
turboadb -s SERIAL swipe 500 1500 500 400 --ms 300
turboadb -s SERIAL brightness --step -20

Connectivity

CommandWhat it doesArguments
wifiTurn Wi-Fi on or off.on|off
bluetoothTurn Bluetooth on or off.on|off
airplaneTurn airplane mode on or off.on|off
hotspotTurn the hotspot on or off (best effort; opens tethering settings otherwise).on|off
mobile-dataTurn mobile data on or off.on|off
 
turboadb -s SERIAL wifi on
turboadb -s SERIAL mobile-data off

Open apps and the web

CommandWhat it doesArguments
settingsOpen the Settings app.
openOpen a URL with the app that handles it, or a shortcut.URL or browser|youtube|maps|spotify|play-store
searchSearch the web in the browser.QUERY…
cameraOpen the camera app.
galleryOpen the gallery / photos app.
calculatorOpen the calculator app.
 
turboadb -s SERIAL open https://maps.google.com
turboadb -s SERIAL open youtube
turboadb -s SERIAL search "nearest charger"

Device status

CommandWhat it doesArguments & options
batteryBattery details (dumpsys battery).--json
healthBattery, temperature, memory, CPU and uptime in one snapshot, or the full report (-o saves it).--full -o FILE --json
build-infoBuild and version properties, or the full report (-o saves it).--full -o FILE --json
getpropOne Android property, or all of them.[NAME] --json
 
turboadb -s SERIAL health --full -o health.txt
turboadb -s SERIAL getprop ro.build.fingerprint

Phone and messages

CommandWhat it doesArguments & options
dialOpen the dialler with a number filled in (doesn't call).NUMBER
callPlace a call.NUMBER
answerAnswer a ringing call.
end-callHang up or reject the current call.
call-stateIdle, ringing or in call (every SIM counts), or unknown on a device without a call state; a device that could not be asked is an error.
call-logRecent calls.--limit 20 --json
smsRecent SMS messages.--limit 20 --json
send-smsOpen Messages with a draft; you press Send on the device.NUMBER TEXT…
phone-supportWhat the device has: telephony, the dialler / call / SMS apps, and phone-like apps (a head unit's own Bluetooth phone).--json
 
turboadb -s SERIAL phone-support
turboadb -s SERIAL call-state
turboadb -s SERIAL send-sms 1800123456 "on my way"

Root and system

For rooted and engineering builds.

CommandWhat it doesArguments & options
rootRestart adbd as root.
unrootRestart adbd without root.
remountadb remount read-write.
accessRoot, build type, verity and bootloader state.--json
make-writableadb root, optional disable-verity and remount, with the reboots they need.--no-root --disable-verity --no-remount --no-reboot --boot-timeout 180
mount-rwRemount a partition read-write.[PATH=/]
disable-verityadb disable-verity (reboot to apply).--reboot --json
enable-verityadb enable-verity (reboot to apply).--reboot
rebootReboot, optionally into another mode, and wait for the boot (head units often have no recovery UI).[recovery|bootloader|fastboot|sideload] --wait --wait-timeout 180
 
turboadb -s SERIAL root
turboadb -s SERIAL disable-verity --reboot
turboadb -s SERIAL reboot --wait

Port forwarding

CommandWhat it doesArguments & options
forwardadb forward; active until Ctrl+C (or left in place with --no-wait). Also lists and removes rules.LOCAL REMOTE --no-wait --list --remove SPEC --remove-all --json
reverseadb reverse; active until Ctrl+C (or left in place with --no-wait). Also lists and removes rules.REMOTE LOCAL --no-wait --list --remove SPEC --remove-all --json
 
turboadb -s SERIAL forward tcp:9222 localabstract:chrome_devtools_remote --no-wait
turboadb -s SERIAL forward --list
turboadb -s SERIAL reverse --remove tcp:3000

Sharing devices with other PCs

serve never downloads adb by itself: its startup task runs as SYSTEM, where that would put a second adb in another profile and bind port 5037 with it. Run turboadb fetch-tools there first if adb is missing.

CommandWhat it doesArguments & options
serveShare this PC's adb server so others can use --adb-host (opens the firewall on Domain and Private networks only, as the server has no password; needs Administrator), check it, or stop sharing. The auto-starts run the adb the server was started with (the SYSTEM startup task a copy of it under Program Files that only administrators can change, where the adb found is not protected); --uninstall-startup exits 1 and says so when the startup task could not be removed (that needs Administrator); --port defaults to --adb-port.--port 5037 --startup-task --install-startup --uninstall-startup --status --stop --json
deploy-serveSet up serve on remote Windows PCs over WinRM (needs turboadb[winrm]). A target without adb gets it downloaded first.HOST… -u USER -p PASSWORD --port 5037 --ssl --winrm-port --no-update --test --json
 
# on the PC with the device:
turboadb serve --startup-task
turboadb serve --status

# or from your machine:
turboadb deploy-serve lab-pc-01 lab-pc-02 -u "DOMAIN\user" --ssl

No command matches that search.

More

turboadb-gui starts the desktop app (without PyQt5 on Windows, the executable bundled in the wheel, from a copy in ~/.turboadb/gui), turboadb-docs opens this site, and turboadb-shortcut creates shortcuts. For shell tab completion install turboadb[completion] and run eval "$(register-python-argcomplete turboadb)". The same reference, with every option explained, is in CLI.md on GitHub.

Prefer clicking?

⤓ Download for Windows Usage guide