Start with the actual response

This guide covers the rdp-cli 0.1.0 RDP interface on Windows, macOS and Linux. It uses existing connection and Agent acceptance records from September 2026, not new server tests. Use an authorized Windows RDP server and the current release for your client. Run rdp-cli from PATH; on Windows use .\rdp-cli.exe from its folder, and on Linux use the installed command or your downloaded executable.

rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION

Replace SESSION with your own returned session ID. Read error.code, error.message and error.retryable on failure. In a successful status response, inspect data.connection_state, data.control_state, data.last_error when present, and data.capabilities. A retryable flag does not authorize replaying input.

Check the connection layer

Error What to check and do
CONNECT_TIMEOUT / RDP_CONNECT_FAILED Verify the host, configured port (normally 3389), LAN/VPN route and a running RDP service. Have the administrator check the listener and permitted firewall rule. A reachable port alone does not prove a successful RDP login. Retry once after correcting the cause.
RDP_TLS_HANDSHAKE_FAILED Check the server TLS configuration. The default modern profile requires TLS 1.2. Use --tls-profile legacy only for an identified legacy target on a trusted network; it permits older cryptography. Do not apply it to every connection or disable server security to make a test pass.
CERTIFICATE_UNTRUSTED Under --cert-policy strict, verify the server name and certificate chain, or verify the reported SHA-256 fingerprint with the administrator before adding an exact trust record. The current default is ignore; that does not verify server identity. Do not switch to ignore just to silence a strict-mode failure.
AUTH_FAILED Check the username, local/domain account choice, --domain and remote-logon permission. Use the password prompt or an existing credential reference from quick start. Do not cycle passwords: TLS failure and an unreachable host are not evidence of a bad password.

A connected session has no usable picture

Run the following read-only query and open the PNG at data.path. connected means activation and a coherent frame were received; the frame may still be a login, Welcome or black screen. It does not prove that the desktop is ready.

rdp-cli screenshot --session SESSION

For FRAME_UNAVAILABLE, inspect status and error.retryable; allow the reconnect or display change to settle, then request another screenshot. If a coherent image stays black, inspect server state and whether the client slept or lost its VPN. Historical black screens had different or unconfirmed causes. Do not type credentials into an unseen target or assume every unchanged image is a frozen protocol.

Resolve input and permission errors

  • OBSERVATION_REQUIRED: capture and read a fresh image; use its data.observation for the next action. Refresh after reconnect, takeover or display changes.
  • SESSION_PAUSED, CONTROL_HELD_BY_HUMAN or CONTROL_NOT_OWNED: stop input and respect the current controller. Resume only after an authorized handoff, then capture again; do not bypass the pause with another viewer.
  • PERMISSION_DENIED / CAPABILITY_UNAVAILABLE: inspect the relevant capability and access grant. A viewer cannot enable an unsupported server feature. UNICODE_INPUT_UNAVAILABLE requires a supported input method, not blind retries.

Recover an uncertain action

Before input that may need recovery, specify and save a unique --request-id for each distinct action; replace the example request IDs with your own values. If error JSON arrives, retain its top-level request_id; if the response is completely lost and no original ID was saved, do not invent a new ID to query the old action or blindly resend it.

After REQUEST_TIMEOUT or SERVICE_UNAVAILABLE during an action, retain its original request ID. Check the local service with list and query the original operation before deciding to retry. The call may have sent input even when its response was lost.

rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION

Replace REQUEST_ID with the original value, not the ID of the status query. Inspect data.state, retained data.result and a fresh screenshot. OPERATION_NOT_FOUND can mean the record expired or the service changed; it does not prove the action never ran. After correcting a connection problem, an explicit reconnect of a non-closed session remains paused. SESSION_CLOSED needs a new authorized connection; do not attempt to revive it by repeatedly reconnecting.

Continue with the right evidence

If unresolved, report the client version, server version, protocol, time, error code and redacted status/screenshot. Remove passwords, access tokens and private screen content. This guide does not establish compatibility or long-term reliability for every server.

Download · Quick start · Command reference