rdp-cli command reference

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.

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.

Protocol and platform conditions

• RDP defaults to --cert-policy ignore and --tls-profile modern. strict verifies certificate trust/name; legacy is an explicit compatibility choice that permits older TLS. Neither setting changes Web HTTPS verification.
• VNC rejects --user, --domain, --size, --layout, --cert-policy and --tls-profile. Classic authentication uses the first eight UTF-8 password bytes; unauthenticated access requires explicit --vnc-security none and no password option. Supported VNC transports are not encrypted.
• 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.

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

Check server TLS support, certificate policy and the actual fingerprint; do not treat a TLS error as a password error.

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.