rdp-cli · 0.3.1

RDP commands: screenshots, input, files and sessions

109 rdp-cli commands for remote desktops, Linux applications and Android: connect, observe, send input, transfer files, manage tasks and hand over control.

Browse commands by task

New to rdp-cli? Start with installation and your first connection. →

connect
Connect a persistent RDP, VNC or Android ADB session.
screenshot
Capture a coherent PNG observation
click
Click at a remote coordinate
type
Type without changing the clipboard; Android supports printable ASCII, LF and TAB. Use android text for Unicode paste.
files upload
Upload to the session file root and verify the completed transfer.
files download
Download from the RDP exchange drive or a stable Android file snapshot.
watch
Open or activate a viewer for human observation; not required for Agent commands
list
List sessions visible to the caller

Verified command catalog for build 2026110701 on Windows, macOS and Linux. Check --version and --help-json on your installed executable.

Observe, act, verify

The values USER, SESSION, OBSERVATION, X and Y are placeholders. Supply a password to stdin and close the stream; --password-stdin is not an interactive prompt. Save data.session, read before.png, choose coordinates from that image, then read after.png to verify the effect. Input dispatch alone is not task completion.

rdp-cli connect --host desktop.example.net --user USER --password-stdin
rdp-cli screenshot --session SESSION --out before.png
rdp-cli click --session SESSION --desktop --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out after.png

Run --version to identify your build capabilities. --help-json returns the machine-readable catalog; COMMAND --help shows its full option descriptions without starting a session.

rdp-cli --version
rdp-cli --help-json
rdp-cli connect --help

JSON and shared options

Ordinary commands return one UTF-8 JSON object on stdout: ok: true with data, or ok: false with error. stderr contains diagnostics. Exit codes are 0 for success, 1 for an operational failure and 2 for invalid arguments.

Help is plain text. events --follow streams NDJSON; ordinary events returns one JSON result containing data.events and data.ndjson. In Windows PowerShell 5.1, set both [Console]::OutputEncoding and $OutputEncoding to UTF-8 when sending or reading non-ASCII text.

data.session
Keep the session ID returned by connect for later commands.
data.observation
Use the screenshot token for input; capture again after reconnection, control changes or layout changes.
data.capabilities
Inspect negotiated support before choosing files, audio, clipboard or display operations.
data.state / data.remote_outcome
queued, sent, partial, unknown, cancelled and failed describe input progress. remote_outcome: not_confirmed still requires visual verification.
data.transfer_id
Use the transfer ID with files status or files cancel; wait for a terminal transfer state and inspect completed file hashes.
error.code / error.message / error.retryable
Use the stable error code for decisions, the message for context and retryable as a hint, not permission to repeat an action blindly.
data.activity
Current or recent activity, its Agent/human source, age and transfer progress. No typed or clipboard content; activity is not proof of remote task completion.

All commands accept --request-id and --timeout-ms. Reuse a request ID only with the identical command and arguments within the retention window. A local timeout does not prove that input was never sent; query operations status before retrying.

--request-id ID · --timeout-ms MILLISECONDS

Sessions

For RDP/VNC, connect requires --host; RDP also requires --user. Default ports are RDP 3389 and VNC 5900. Choose one password source when authentication is required; --vnc-security none uses none. ADB requires --device and --transport instead; Wi-Fi can use an explicit host and connection port. --domain, --size and --layout are RDP options. reconnect keeps control paused; disconnect does not log off the remote user.

rdp-cli connect#

Connect a persistent RDP, VNC or Android ADB session.

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--profile

Saved connection profile

TextOptional
--host

RDP/VNC host, or explicit Android Wi-Fi endpoint.

TextOptional
--protocol

Protocol: RDP, VNC, ADB or X11; each uses its own explicit target and authentication rules.

Choice
rdp | vnc | adb | x11
Default: rdp
Optional
--mode

X11 mode: existing desktop or forwarded application.

Choice
desktop | application
Optional
--display

Existing authorized X11 display; desktop mode only.

TextOptional
--xauthority

Existing absolute remote Xauthority path; desktop mode only.

TextOptional
--ssh-known-hosts

Local OpenSSH known-hosts file; no external SSH executable.

PathOptional
--ssh-key

Local private SSH key; password input supplies its passphrase.

PathOptional
--ssh-host-key

Independently verified SSH SHA256 fingerprint.

TextOptional
--linux-file-root

Authorized absolute SFTP directory; default is a private session directory in the SSH home.

TextOptional
--application

Absolute path to an already installed remote X11 application.

TextOptional
--app-args

Literal argument array in JSON; no shell interpretation.

TextOptional
--device

Explicit device ID returned by android devices; required for ADB.

TextOptional
--transport

Explicit USB or Wi-Fi transport; required for ADB.

Choice
usb | wifi
Optional
--device-auth-ref

Reuse an identity explicitly saved in the operating system credential store.

TextOptional
--save-device-auth

Explicitly save the authorized identity under this local reference.

TextOptional
--device-file-root

Authorized Android directory; defaults to /sdcard/Download/rdp-cli/<session-id>.

PathOptional
--android-display

Main or session-owned virtual phone display

Choice
main | virtual
Optional
--android-virtual-size

Virtual display size, WIDTHxHEIGHT

TextOptional
--android-virtual-dpi

Virtual display DPI

Positive integerOptional
--android-start-app

Installed app to launch on the new virtual display

TextOptional
--vnc-security

VNC authentication; none requires explicit selection

Choice
vnc-auth | none | x509-plain | ard
Optional
--vnc-tls-pin

Verified SHA256 leaf-certificate fingerprint for VNC X509Plain.

TextOptional
--port

TCP port: RDP 3389 or VNC 5900. android pair uses the phone pairing port; ADB connect uses its separate connection port.

Positive integer
Default: RDP 3389 · VNC 5900
Optional
--user

Local or domain account; required for RDP

TextOptional
--domain

Windows domain

TextOptional
--password

Password; classic VNC uses the first 8 UTF-8 bytes

TextOptional
--password-stdin

Read password from standard input until EOF

FlagOptional
--cert-policy

RDP server certificate policy; independent of Web HTTPS

Choice
ignore | strict
Default: ignore
Optional
--tls-profile

modern requires TLS 1.2 and modern cryptography; legacy permits older signatures/ciphers, including SHA-1 on TLS 1.2, and TLS 1.0 for this session without forcing a downgrade

Choice
modern | legacy
Default: modern
Optional
--credential-ref

Existing platform credential-store reference

TextOptional
--audio-mode

RDP playback destination: viewer (client), controlled computer (host), or off

Choice
client | host | off
Default: client
Optional
--microphone-mode

RDP microphone source: authorized viewer (client), matching controlled-computer helper (host), or off

Choice
client | host | off
Default: client
Optional
--save-credential

Save a successful password with this reference

TextOptional
--name

Readable session name

TextOptional
--size

Desktop WIDTHxHEIGHT

TextOptional
--layout

Monitor layout JSON or @file

TextOptional
--connect-timeout-ms

Connection deadline in milliseconds

Positive integerOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli connect --help

rdp-cli list#

List sessions visible to the caller

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli list --help

rdp-cli status#

Get a coherent session status snapshot

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli status --help

rdp-cli reconnect#

Reconnect a non-closed session and remain paused

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli reconnect --help

rdp-cli disconnect#

Close the remote session; RDP does not log off the Windows user.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli disconnect --help

Viewers and desktop status

watch opens a read-only human viewer; Agent commands do not need it. Select --viewer window or web. presence show/hide controls local desktop status; --floating adds controls and --panel opens the session panel on macOS or Linux. Closing a read-only viewer keeps the connection alive.

rdp-cli watch#

Open or activate a viewer for human observation; not required for Agent commands

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--viewer

Viewer implementation

Choice
window | web
Default: window
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli watch --help

rdp-cli presence show#

Show desktop session presence

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--floating

Also show optional floating session controls

FlagOptional
--panel

Also open the session panel on macOS or Linux

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli presence show --help

rdp-cli presence hide#

Hide desktop presence without closing sessions

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli presence hide --help

Control and handoff

pause accepts one --session or --all and revokes human control. resume returns a paused session to its Agent. control take requires the connected viewer ID; release can identify that viewer or a target Agent. Respect a human pause and obtain a fresh screenshot after control is returned.

rdp-cli pause#

Stop normal input and revoke human control

Choose exactly one: --session SESSION or --all.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli pause --help

rdp-cli resume#

Return a paused session to its Agent

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli resume --help

rdp-cli control take#

Give a connected viewer the human lease

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--viewer-id

Connected viewer ID, including control-lease owner where applicable

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control take --help

rdp-cli control release#

Return the human lease to an Agent

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--viewer-id

Connected viewer ID, including control-lease owner where applicable

TextOptional
--agent-id

Agent receiving control

TextOptional
--to-agent

Target Agent identity

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control release --help

Screenshots, input and clipboard

screenshot writes a PNG with --out and can select --monitor. Coordinate input requires an observation and either monitor-relative coordinates or --desktop coordinates; do not mix both. drag uses from/to coordinates and optional monitor IDs. type accepts exactly one of --text or --text-stdin; --sensitive changes the visible hint, not the screenshot. key accepts --keys or --key with --state. Clipboard writes explicitly replace remote text.

rdp-cli screenshot#

Capture a coherent PNG observation

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--monitor

Monitor ID; screenshot also accepts all

Text
Default: all
Optional
--region

Region x,y,width,height in remote pixels

TextOptional
--max-width

Maximum image width; original input coordinates remain valid

Positive integerOptional
--since

Previous screenshot comparison reference

TextOptional
--out

Destination PNG file

PathOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli screenshot --help

rdp-cli move#

Move the remote pointer

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--x

Remote x coordinate

IntegerRequired
--y

Remote y coordinate

IntegerRequired
--monitor

Monitor ID; screenshot also accepts all

TextOptional
--desktop

Use desktop coordinates instead of monitor-local coordinates

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli move --help

rdp-cli click#

Click at a remote coordinate

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--x

Remote x coordinate

IntegerRequired
--y

Remote y coordinate

IntegerRequired
--button

Mouse button

Choice
left | right | middle
Default: left
Optional
--count

Number of clicks

Positive integerOptional
--monitor

Monitor ID; screenshot also accepts all

TextOptional
--desktop

Use desktop coordinates instead of monitor-local coordinates

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli click --help

rdp-cli scroll#

Scroll at a remote coordinate

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--x

Remote x coordinate

IntegerRequired
--y

Remote y coordinate

IntegerRequired
--delta-x

Signed horizontal wheel units

IntegerOptional
--delta-y

Signed vertical wheel units

IntegerOptional
--monitor

Monitor ID; screenshot also accepts all

TextOptional
--desktop

Use desktop coordinates instead of monitor-local coordinates

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli scroll --help

rdp-cli drag#

Drag between remote coordinates

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--from-x

Start x coordinate

IntegerRequired
--from-y

Start y coordinate

IntegerRequired
--to-x

End x coordinate

IntegerRequired
--to-y

End y coordinate

IntegerRequired
--from-monitor

Starting monitor ID

TextOptional
--to-monitor

Ending monitor ID

TextOptional
--desktop

Use desktop coordinates instead of monitor-local coordinates

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli drag --help

rdp-cli type#

Type without changing the clipboard; Android supports printable ASCII, LF and TAB. Use android text for Unicode paste.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--text

Unicode input or clipboard text

TextOptional
--text-stdin

Read input or clipboard text from standard input until EOF

FlagOptional
--sensitive

Redact text in observable events; screenshots still show the desktop

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli type --help

rdp-cli key#

Send a key combination or key state

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--keys

Key combination such as CTRL+S

TextOptional
--key

Key name; android key uses its listed system keys.

TextOptional
--state

Key state or audio mute state, as listed

Choice
down | up
Optional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli key --help

rdp-cli clipboard get#

Read remote text clipboard

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli clipboard get --help

rdp-cli clipboard set#

Write remote text clipboard

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--text

Unicode input or clipboard text

TextOptional
--text-stdin

Read input or clipboard text from standard input until EOF

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli clipboard set --help

Files

--path is relative to the authorized RDP exchange drive, Android directory or X11 SFTP root. --local names a local file or folder. Replacement requires --overwrite. Check transfer status and completed hashes; do not repeat an operation whose result is unknown.

rdp-cli files list#

List files in the RDP exchange drive or authorized Android directory.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--path

Path relative to the RDP exchange drive or authorized Android directory.

PathOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files list --help

rdp-cli files upload#

Upload to the session file root and verify the completed transfer.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--local

Local file/directory for upload or download destination

PathRequired
--path

Path relative to the RDP exchange drive or authorized Android directory.

PathRequired
--overwrite

Allow replacing an existing target

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files upload --help

rdp-cli files download#

Download from the RDP exchange drive or a stable Android file snapshot.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--path

Path relative to the RDP exchange drive or authorized Android directory.

PathRequired
--local

Local file/directory for upload or download destination

PathRequired
--overwrite

Allow replacing an existing target

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files download --help

rdp-cli files status#

Get transfer status

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--transfer-id

Transfer ID; files status without this lists session transfers

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files status --help

rdp-cli files cancel#

Cancel a transfer

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--transfer-id

Transfer ID; files status without this lists session transfers

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files cancel --help

rdp-cli files cleanup#

Remove selected exchange content

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--path

Path relative to the RDP exchange drive or authorized Android directory.

PathRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli files cleanup --help

Sound and microphone

RDP: --audio-mode client|host|off and --microphone-mode client|host|off independently select playback and microphone source for a new connection. They do not start recording. The host route requires the matching service on the controlled Windows computer; it is unavailable on Linux. X11/VNC have no product audio channel.

rdp-cli host-microphone install#

Install and start the controlled-computer microphone helper on this Windows PC

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli host-microphone install --help

rdp-cli host-microphone status#

Check whether the controlled-computer microphone helper is installed on this Windows PC

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli host-microphone status --help

rdp-cli host-microphone uninstall#

Stop and remove the controlled-computer microphone helper from this Windows PC

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli host-microphone uninstall --help

rdp-cli audio status#

Get session audio capabilities and sources

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio status --help

rdp-cli audio mute#

Mute or unmute one viewer

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--viewer-id

Connected viewer ID, including control-lease owner where applicable

TextRequired
--state

Key state or audio mute state, as listed

Choice
on | off
Required
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio mute --help

rdp-cli audio volume#

Set one viewer's playback gain

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--viewer-id

Connected viewer ID, including control-lease owner where applicable

TextRequired
--percent

Playback gain percentage

Positive integerRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio volume --help

rdp-cli audio microphone#

Query or stop an active microphone source

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--action

Microphone status or stop; start requires a human viewer

Choice
status | stop
Default: status
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio microphone --help

rdp-cli audio android#

Select phone playback, phone microphone or off explicitly.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--source

Phone audio: off, output (system sharing consent), or microphone (control and a fresh --observation required).

Choice
off | output | microphone
Required
--observation

Token from a fresh screenshot

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio android --help

rdp-cli audio poll#

Read a bounded batch of recent PCM audio samples.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--after

Return events or PCM samples after this sequence.

Positive integerOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli audio poll --help

Displays

monitors returns negotiated topology. monitors set accepts layout JSON or @file; --allow-reconnect permits reconnect when a live layout change is unavailable. Read the resulting topology and take a new screenshot before input. VNC can report its framebuffer but rejects requested layout changes.

rdp-cli monitors#

Get negotiated monitor topology

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli monitors --help

rdp-cli monitors set#

Change monitor topology

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--layout

Monitor layout JSON or @file

TextRequired
--allow-reconnect

Permit reconnect if dynamic monitor layout is unavailable

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli monitors set --help

Browser access

web start configures the listener and TLS certificate/key or trusted proxy; --ice-server can repeat. Use LAN/VPN access with HTTPS and authorization outside loopback. access grant requires repeated --permission values and --expires-in seconds. Permissions include session.observe, session.control, clipboard.read/write, files.read/write and audio.listen/send. Revocation stops that grant’s live streams.

rdp-cli web start#

Start the embedded authenticated Web service

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--listen

Listen address

TextOptional
--tls-cert

HTTPS certificate file

PathOptional
--tls-key

HTTPS private-key file

PathOptional
--trust-proxy

Trust the configured proxy

FlagOptional
--ice-server

STUN/TURN URL for WebRTC peers

TextOptional · Repeatable
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli web start --help

rdp-cli web status#

Get Web service status

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli web status --help

rdp-cli web stop#

Stop browser access while keeping remote sessions connected.

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli web stop --help

rdp-cli access grant#

Create a scoped Web grant

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--permission

Permission granted to this access token

TextRequired · Repeatable
--expires-in

Grant lifetime in seconds

Positive integerRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli access grant --help

rdp-cli access list#

List scoped Web grants

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli access list --help

rdp-cli access revoke#

Revoke a Web grant and its live streams

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--grant-id

Grant identifier

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli access revoke --help

Android phones

Use an explicit device ID and usb or wifi transport. Discovery does not authorize a phone. Pair through the phone’s pairing port; connection uses its separate connection port. Send the pairing code through stdin and close the stream. Save an identity only explicitly. Input and app changes require control and a fresh observation; query application jobs before repeating an uncertain operation.

rdp-cli android devices#

Discover USB and Wi-Fi candidates without authorizing them.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android devices --help

rdp-cli android pair#

Pair wireless debugging using the pairing port and a code supplied through stdin.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--host

RDP/VNC host, or explicit Android Wi-Fi endpoint.

TextRequired
--port

TCP port: RDP 3389 or VNC 5900. android pair uses the phone pairing port; ADB connect uses its separate connection port.

Positive integerRequired
--code-stdin

Read the six-digit pairing code from stdin.

FlagOptional
--device-auth-ref

Reuse an identity explicitly saved in the operating system credential store.

TextOptional
--save-device-auth

Explicitly save the authorized identity under this local reference.

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android pair --help

rdp-cli android forget#

Forget one saved local Android identity; phone-side revocation is separate.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--device-auth-ref

Reuse an identity explicitly saved in the operating system credential store.

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android forget --help

rdp-cli android apps list#

List installed Android packages.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps list --help

rdp-cli android apps info#

Read the actual installed paths for a package.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--package

Android package name.

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps info --help

rdp-cli android apps install#

Submit one APK from the authorized device directory; track its job.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--path

Path relative to the RDP exchange drive or authorized Android directory.

PathRequired
--replace

Explicitly replace an installed application.

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps install --help

rdp-cli android apps launch#

Launch a package and verify its screen.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--package

Android package name.

TextRequired
--activity

Activity class; otherwise resolve the launcher.

TextOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps launch --help

rdp-cli android apps stop#

Force-stop the explicitly selected Android package.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--package

Android package name.

TextRequired
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps stop --help

rdp-cli android apps status#

Query an app job without repeating its operation.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--job

Job ID returned by install, launch or stop.

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android apps status --help

rdp-cli android touch#

Send a complete timed touch gesture using a fresh screenshot.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--kind

Touch gesture type.

Choice
tap | double-tap | long-press | swipe | drag | pinch | gesture
Required
--x

Remote x coordinate

IntegerOptional
--y

Remote y coordinate

IntegerOptional
--to-x

End x coordinate

IntegerOptional
--to-y

End y coordinate

IntegerOptional
--second-x

Second finger starting X coordinate.

IntegerOptional
--second-y

Second finger starting Y coordinate.

IntegerOptional
--second-to-x

Second finger ending X coordinate.

IntegerOptional
--second-to-y

Second finger ending Y coordinate.

IntegerOptional
--duration-ms

Gesture duration, 1–10000 ms; drag adds a 400 ms hold.

Positive integerOptional
--events-stdin

Read a JSON array [{at_ms,contact,phase,x,y}, …] from stdin; only for --kind gesture.

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android touch --help

rdp-cli android key#

Press an Android system key with control and a fresh observation.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--key

Key name; android key uses its listed system keys.

Choice
back | home | recent | enter | backspace
Required
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android key --help

rdp-cli android text#

Explicitly paste Unicode through the phone clipboard.

Requires a current Android-enabled download for Windows (x64 / x86 / ARM64), macOS (Apple silicon / Intel) or Linux (x86_64 / ARM64).

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--method

Explicit text method: clipboard paste.

Choice
clipboard
Required
--text

Unicode input or clipboard text

TextOptional
--text-stdin

Read input or clipboard text from standard input until EOF

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli android text --help

Linux desktops and applications

Use --protocol x11 with an explicit desktop or application mode and verified SSH identity. The SSH client and application display are built in. An existing Wayland desktop uses its configured RDP/VNC endpoint. X11 has no audio or microphone channel. SFTP files stay within the authorized root; nothing installs a remote server.

rdp-cli linux targets#

Discover existing Linux displays and compatible endpoints without starting services.

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--host

RDP/VNC host, or explicit Android Wi-Fi endpoint.

TextRequired
--user

Local or domain account; required for RDP

TextRequired
--port

TCP port: RDP 3389 or VNC 5900. android pair uses the phone pairing port; ADB connect uses its separate connection port.

Positive integer
Default: 22
Optional
--ssh-known-hosts

Local OpenSSH known-hosts file; no external SSH executable.

PathOptional
--ssh-host-key

Independently verified SSH SHA256 fingerprint.

TextOptional
--ssh-key

Local private SSH key; password input supplies its passphrase.

PathOptional
--password

Password; classic VNC uses the first 8 UTF-8 bytes

TextOptional
--password-stdin

Read password from standard input until EOF

FlagOptional
--credential-ref

Existing platform credential-store reference

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli linux targets --help

rdp-cli linux text#

Type text or explicitly paste through the remote clipboard.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--method

Explicit text method: clipboard paste.

Choice
clipboard
Required
--keys

Key combination such as CTRL+S

Choice
CTRL+V | CTRL+SHIFT+V | SHIFT+INSERT
Default: CTRL+V
Optional
--text

Unicode input or clipboard text

TextOptional
--text-stdin

Read input or clipboard text from standard input until EOF

FlagOptional
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli linux text --help

rdp-cli linux apps list#

List this session’s forwarded X11 application instances.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli linux apps list --help

rdp-cli linux apps stop#

Stop one explicitly selected application instance.

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--instance

Exact application instance ID from linux apps list.

TextRequired
--observation

Token from a fresh screenshot

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli linux apps stop --help

Operations and events

operations status queries an operation ID or the original request ID when a result is uncertain. It does not repeat input. events reads the stream; --follow keeps it open and --after resumes from a cursor. Verify the remote application separately after a sent result.

rdp-cli operations status#

Query a retained operation result

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--operation-id

Operation identifier

TextOptional
--request-id

Request correlation/idempotency ID; operations status queries the original ID

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli operations status --help

rdp-cli events#

Read or follow the session event stream

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--follow

Keep following new events

FlagOptional
--after

Return events or PCM samples after this sequence.

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli events --help

Trust, credentials and installation

trust records apply to an exact RDP target and fingerprint in strict certificate mode. credentials remove deletes only the named product credential reference. On macOS and Linux, install-cli/uninstall-cli manage the CLI entry and --prefix chooses the installation location; Windows runs the downloaded executable directly. presence show --panel opens the session panel on macOS and Linux. licenses prints the bundled third-party versions and notices.

rdp-cli trust list#

List scoped RDP certificate trust records

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli trust list --help

rdp-cli trust add#

Trust one target certificate fingerprint

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--target

RDP trust target

TextRequired
--fingerprint

Certificate fingerprint

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli trust add --help

rdp-cli trust remove#

Remove one target trust record

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--target

RDP trust target

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli trust remove --help

rdp-cli credentials remove#

Remove one product credential-store item

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--reference

Credential-store reference to remove

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli credentials remove --help

rdp-cli install-cli#

Install the CLI entry on macOS or Linux

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--prefix

User-controlled installation prefix

PathOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli install-cli --help

rdp-cli uninstall-cli#

Remove the CLI entry point created by rdp-cli

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli uninstall-cli --help

rdp-cli licenses#

Show third-party versions and license notices

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli licenses --help

Agent tasks and automation

Added screen regions and image comparison, conditional waits, action batches, persistent task reports, named Agent collaboration, MCP with connection profiles and diagnostics, and Android virtual displays.

rdp-cli tasks create#

Create a persistent task

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--title

Task title

TextRequired
--session

Explicit session ID

TextOptional
--record-frames

Explicitly retain screenshot key frames

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks create --help

rdp-cli tasks list#

List authorized tasks

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks list --help

rdp-cli tasks status#

Read task progress and history

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks status --help

rdp-cli tasks attach#

Attach an authorized session to a task

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks attach --help

rdp-cli tasks checkpoint#

Save a checkpoint without replaying input

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--note

Progress note without secrets

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks checkpoint --help

rdp-cli tasks new-run#

Start a new run from a checkpoint

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--from-checkpoint

Existing checkpoint ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks new-run --help

rdp-cli tasks grants list#

List task permissions

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks grants list --help

rdp-cli tasks grants grant#

Grant task permissions

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--to-agent

Target Agent identity

TextRequired
--permission

Permission granted to this access token

TextRequired · Repeatable
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks grants grant --help

rdp-cli tasks grants revoke#

Revoke future task access

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--to-agent

Target Agent identity

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks grants revoke --help

rdp-cli tasks evidence#

Save selected local evidence

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--file

Local evidence file, up to 4 MiB

PathRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks evidence --help

rdp-cli tasks export#

Export an offline JSON or HTML report

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--out

Destination PNG file

PathRequired
--format

Output format; see this command’s allowed values

Choice
json | html
Default: json
Optional
--include-evidence

Include explicitly saved evidence

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks export --help

rdp-cli tasks purge#

Purge selected local task history

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--task

Persistent task ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--run

Task run ID

TextOptional

rdp-cli tasks purge --help

rdp-cli agents register#

Register an Agent identity

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--name

Readable session name

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents register --help

rdp-cli agents list#

List Agent identities without secrets

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents list --help

rdp-cli agents show#

Read an Agent identity and permissions

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--id

Target identity

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents show --help

rdp-cli agents revoke#

Revoke an Agent identity and its claims

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--id

Target identity

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents revoke --help

rdp-cli agents grant#

Grant an Agent session access

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--id

Target identity

TextRequired
--permission

Permission granted to this access token

TextRequired · Repeatable
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents grant --help

rdp-cli agents revoke-access#

Revoke an Agent session access

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--id

Target identity

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli agents revoke-access --help

rdp-cli control claim#

Claim a paused session as a named Agent

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--lease-seconds

Control lease duration in seconds

Positive integer
Default: 60
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control claim --help

rdp-cli control renew#

Renew a valid control claim

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--lease-seconds

Control lease duration in seconds

Positive integer
Default: 60
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control renew --help

rdp-cli control unclaim#

Release the claim and pause the session

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control unclaim --help

rdp-cli control claim-status#

Inspect the current control claim

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control claim-status --help

rdp-cli control handoff#

Hand control to an authorized Agent

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--to-agent

Target Agent identity

TextRequired
--lease-seconds

Control lease duration in seconds

Positive integer
Default: 60
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli control handoff --help

rdp-cli profiles list#

List saved connection profiles

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles list --help

rdp-cli profiles show#

Read a profile and parameter sources

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--name

Readable session name

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles show --help

rdp-cli profiles save#

Save a profile with credential references

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--json

Versioned JSON input for this command

TextRequired
--replace

Explicitly replace an installed application.

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles save --help

rdp-cli profiles remove#

Remove a profile without deleting credentials

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--name

Readable session name

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles remove --help

rdp-cli profiles export#

Export a profile without secrets

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--name

Readable session name

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles export --help

rdp-cli profiles import#

Import a profile without connecting

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--json

Versioned JSON input for this command

TextRequired
--replace

Explicitly replace an installed application.

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli profiles import --help

rdp-cli doctor#

Diagnose capabilities; explicitly opt into a connection probe

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--session

Explicit session ID

TextOptional
--profile

Saved connection profile

TextOptional
--probe

Explicitly connect a temporary profile session

FlagOptional
--redact

Omit target names, addresses and session IDs

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli doctor --help

rdp-cli doctor status#

Read a diagnostic result

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--diagnostic-id

Original diagnostic request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli doctor status --help

rdp-cli doctor cancel#

Cancel further diagnostic work

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--diagnostic-id

Original diagnostic request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli doctor cancel --help

rdp-cli wait#

Wait for a pixel or state condition

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--condition

Condition to wait for

Choice
changed | stable | connection | transfer | operation
Required
--region

Region x,y,width,height in remote pixels

TextOptional
--state

Key state or audio mute state, as listed

TextOptional
--transfer-id

Transfer ID; files status without this lists session transfers

TextOptional
--operation-id

Operation identifier

TextOptional
--sample-ms

Sampling interval in milliseconds

Positive integer
Default: 100
Optional
--stable-ms

Required stable duration in milliseconds

Positive integer
Default: 1000
Optional
--threshold-permille

Changed-pixel fraction in thousandths

Integer
Default: 10
Optional
--pixel-delta

RGB channel difference to ignore

Integer
Default: 8
Optional
--max-frame-age-ms

Maximum accepted frame age in milliseconds

Positive integer
Default: 5000
Optional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli wait --help

rdp-cli wait status#

Read a wait result

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--wait-id

Original wait request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli wait status --help

rdp-cli wait cancel#

Cancel a wait without cancelling its target

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--wait-id

Original wait request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli wait cancel --help

rdp-cli batch#

Run a prevalidated sequence of up to 64 steps

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--json

Versioned JSON input for this command

TextOptional
--steps-stdin

Read batch JSON from stdin

FlagOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli batch --help

rdp-cli batch status#

Read a batch result without replay

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--batch-id

Original batch request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli batch status --help

rdp-cli batch cancel#

Cancel pending batch steps

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--batch-id

Original batch request ID

TextRequired
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli batch cancel --help

rdp-cli operations cancel#

Cancel remaining input; sent input is not undone

Requires --session SESSION.

Command options
OptionFormat and valuesRequirement
--operation-id

Operation identifier

TextOptional
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli operations cancel --help

rdp-cli mcp stdio#

Serve MCP over standard input and output

A session is not required; optional session selection is listed below where supported.

Command options
OptionFormat and valuesRequirement
--agent-id

Agent receiving control

TextOptional
--agent-ref

Caller Agent credential reference

TextOptional
--claim-ref

Current control claim reference

TextOptional
--task

Persistent task ID

TextOptional
--run

Task run ID

TextOptional

rdp-cli mcp stdio --help

Protocol and platform conditions

  • RDP defaults to --cert-policy ignore and --tls-profile modern. TLS 1.2 servers may still need older signatures or ciphers. For a known legacy target, explicitly retry once with --tls-profile legacy, preserving credentials and certificate policy and using a new request ID. Reconnect retains the selected profile; there is no automatic downgrade. strict verifies certificate trust/name. Web HTTPS is unaffected.
  • VNC security depends on the selected mode. Classic VNC is unencrypted; use a trusted network or VPN. VeNCrypt X509Plain uses TLS and requires certificate verification. Encrypted VNC: --vnc-security x509-plain requires --user, a password source and an independently verified --vnc-tls-pin. Classic VNC does not accept --user. RDP options --domain, --size and --layout do not apply.
  • VNC does not provide files, audio, microphone or requested display layout changes. Clipboard UTF-8 depends on negotiation; otherwise only Latin-1 is accepted.
  • RDP files require drive redirection; audio, clipboard, microphone and multiple displays also depend on server policy and negotiated capabilities.
  • Windows and macOS offer native viewing and desktop status. Linux native viewing needs a desktop/display service, audio needs the host audio service and saved credentials need Secret Service. A headless host can still use supported CLI operations.
  • Long Unicode input is paced for remote applications. Choose an appropriate timeout and verify the result; changing input method or opening a viewer cannot guarantee that every server accepts every character.
  • Android 12+ is required; Pixel 3 with Android 12 is the tested phone. Android text paste explicitly changes the phone clipboard. Phone output requires system sharing consent and respects app capture restrictions; microphone is a separate source. Neither starts on connect or resumes automatically after reconnection.
  • For macOS Screen Sharing, supply the Mac account name with --user and its password: ARD authentication is selected automatically, or explicitly with --vnc-security ard. A separately configured VNC password uses --vnc-security vnc-auth without --user. ARD does not encrypt the desktop stream; use a trusted network or VPN.

Recover from an error

OBSERVATION_REQUIRED / INVALID_COORDINATES
Capture again, inspect monitor topology and choose valid remote coordinates.
SESSION_PAUSED / CONTROL_HELD_BY_HUMAN
Stop input and respect human control; continue only when the session is deliberately returned to the Agent.
AUTH_FAILED / VNC_AUTH_FAILED
Check the account/password source and remote authentication policy.
RDP_TLS_HANDSHAKE_FAILED / CERTIFICATE_UNTRUSTED
RDP_TLS_HANDSHAKE_FAILED: inspect the selected profile and server cryptography; this does not prove an old TLS version or a wrong password. For a known legacy target, retry connect once with --tls-profile legacy and a new request ID. CERTIFICATE_UNTRUSTED: verify certificate trust/name and the actual fingerprint; changing TLS profile does not resolve certificate trust.
CAPABILITY_UNAVAILABLE / CLIPBOARD_ENCODING_UNSUPPORTED
Inspect protocol/capabilities or text encoding and use a supported operation.
REQUEST_TIMEOUT / REQUEST_ID_CONFLICT / REQUEST_WINDOW_EXPIRED
Query the original operation and current screen before retrying. Never reuse an ID for different arguments or assume expired retention still deduplicates.