rdp-cli
Control an Android phone with an AI agent over USB or Wi-Fi
Connect Android 12+, capture the real screen, enter text, transfer a file and take over the same rdp-cli session.
Android 12 or later is the support baseline. The verified device is Google Pixel 3 running Android 12; this does not claim testing of every manufacturer or later Android release.
Prepare your phone
- Enable Developer options and USB debugging, connect a data cable and confirm the debugging prompt on the unlocked phone.
- For Wi-Fi, enable Wireless debugging and use the pairing code and pairing port shown on the phone. The connection port is separate; a USB cable is not required.
- Windows USB requires a WinUSB driver appropriate for the phone and host architecture, including ARM64. rdp-cli does not install drivers or close other debugging tools. On Linux (x86_64 / ARM64), allow your normal user to access the phone’s USB device through the appropriate udev rule or device group, then use Bash for the commands below. Run rdp-cli without sudo. macOS uses the system USB interface.
Replace DEVICE_SERIAL, SESSION, OBSERVATION, PHONE_IP and both ports with actual values. Save data.session from connect and data.observation from each screenshot. Use the returned wifi: device ID in place of wifi:PHONE_GUID. Choose a name for PHONE_REF to save the pairing on this computer. Enter the current six-digit code when prompted; the command sends it through standard input.
Windows PowerShell: rdp-cli → .\rdp-cli.exe.
Find and connect
Choose the explicit device ID returned by discovery. Connection does not open a viewer or start audio.
rdp-cli android devices
rdp-cli connect --protocol adb --device usb:DEVICE_SERIAL --transport usb
rdp-cli screenshot --session SESSION --out before.png
Complete a small task
Open a notes application on the authorized phone and create an empty note. Inspect before.png, replace X and Y with coordinates of its text field, and tap. Inspect focused.png and save that response’s data.observation as NEW_OBSERVATION before pasting. Verify the text in result.png. These commands act on the phone without opening a computer viewer.
rdp-cli android touch --session SESSION --kind tap --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out focused.png
Use the explicit clipboard method for Unicode or multiline text. It replaces the phone clipboard; it does not synchronize the computer clipboard. Replace the example text with your own note. If the phone rotates or an observation expires, capture and inspect again.
rdp-cli android text --session SESSION --method clipboard --text "Remote task completed." --observation NEW_OBSERVATION
rdp-cli screenshot --session SESSION --out result.png
Files & folders
For a file round trip, create a local plain-text note.txt containing your own sample. Upload it as note.txt, save data.transfer_id as UPLOAD_TRANSFER and wait for completed. Download it to a different local file, save the new transfer ID as DOWNLOAD_TRANSFER, and wait for completed again. Compare the two files. Paths refer to the session folder on the phone, not its private application directories. Existing names are not overwritten by default.
rdp-cli files upload --session SESSION --local ./note.txt --path note.txt
rdp-cli files status --session SESSION --transfer-id UPLOAD_TRANSFER
rdp-cli files download --session SESSION --path note.txt --local ./note-returned.txt
rdp-cli files status --session SESSION --transfer-id DOWNLOAD_TRANSFER
Connect wirelessly
Wi-Fi is an alternative to USB. If this phone already has a USB session, run disconnect --session SESSION first. Pair, then connect with the returned device ID and current connection port. Save the new data.session and observe again before input.
For Wi-Fi, enable Wireless debugging and use the pairing code and pairing port shown on the phone. The connection port is separate; a USB cable is not required.
macOS / Linux · Bash
printf '%s' 'Pairing code: '
IFS= read -r -s rdp_pair_code
printf '\n'
printf '%s' "$rdp_pair_code" | rdp-cli android pair --host PHONE_IP --port PAIR_PORT --code-stdin --save-device-auth PHONE_REF
unset rdp_pair_code
rdp-cli connect --protocol adb --device wifi:PHONE_GUID --transport wifi --host PHONE_IP --port CONNECT_PORT --device-auth-ref PHONE_REF
Windows · PowerShell
$pairingCode = Read-Host 'Pairing code' -AsSecureString
try {
[System.Net.NetworkCredential]::new('', $pairingCode).Password |
.\rdp-cli.exe android pair --host PHONE_IP --port PAIR_PORT --code-stdin --save-device-auth PHONE_REF
} finally {
$pairingCode.Dispose()
}
.\rdp-cli.exe connect --protocol adb --device wifi:PHONE_GUID --transport wifi --host PHONE_IP --port CONNECT_PORT --device-auth-ref PHONE_REF
Observe and take over
Share one persistent session with an agent, a native viewer and authorized browsers. Pause or take control when needed.
rdp-cli watch --session SESSION --viewer window
rdp-cli watch --session SESSION --viewer web
What to expect
If USB discovery is empty, check the data cable and device permissions. ADB_DEVICE_BUSY means another debugging tool owns the phone; close that connection explicitly. For Wi-Fi, confirm the current connection port and saved device identity. Do not substitute the pairing port. A successful input response confirms dispatch; the next screenshot or completed file is what verifies the task.
- The session controls the phone’s existing screen. Physical touches and other debugging tools can still affect it.
- Unicode paste changes the phone clipboard explicitly. It does not read or synchronize your computer clipboard.
- Phone playback audio requires confirmation of the phone’s system sharing prompt and respects application capture restrictions. Phone microphone audio is a separate source; computer microphone injection is not provided.
- Audio starts off. Reconnection does not resume recording. Android components are deployed temporarily to the authorized phone; no root or replacement keyboard is required.
Stop
Turn off phone audio and disconnect. Completed files and user applications remain on the phone.
rdp-cli audio android --session SESSION --source off
rdp-cli disconnect --session SESSION