rdp-cli

Connect from Linux to Windows RDP with one executable

Applies to: 0.1.2 · Linux x86_64 / ARM64 · Windows RDP

From a Linux executable to a remote screenshot

Choose the Linux executable for your CPU, connect to Windows over RDP and capture your first remote screenshot. Use the download page for current system requirements and supported architectures.

Choose the architecture and verify the file

On the Linux computer that will run rdp-cli:

uname -m

Choose Linux x86_64 for x86_64, or Linux ARM64 for aarch64, on the download page. An ARM CPU running a 32-bit OS is outside this ARM64 release. A Mac running macOS needs the macOS package. Download the executable, not the separate source/license materials; the materials are not required to run it.

Compare the SHA-256 output with the matching architecture's file details on the download page before executing. For x86_64:

sha256sum ./rdp-cli-linux-x86_64

Only after the digest matches, set the execute bit and inspect the version:

chmod u+x ./rdp-cli-linux-x86_64
./rdp-cli-linux-x86_64 --version

For ARM64:

sha256sum ./rdp-cli-linux-arm64

Only after the digest matches, set the execute bit and inspect the version:

chmod u+x ./rdp-cli-linux-arm64
./rdp-cli-linux-arm64 --version

--version returns the installed version as JSON. The Linux download is a single static ELF executable that runs as a normal user. Opening a native viewer additionally requires a graphical desktop session.

Connect from Bash

The Windows server must already have RDP enabled, allow your account to sign in remotely, and be reachable from this Linux computer over the intended network or VPN. Client installation does not enable the Windows service.

Run the following in Bash from the executable directory. On ARM64, change the first line to rdp_cli=./rdp-cli-linux-arm64. Replace 192.0.2.20 and USER with your authorized target and account; the password prompt does not display typed characters.

rdp_cli=./rdp-cli-linux-x86_64
IFS= read -r -s -p 'Password: ' rdp_password
printf '\n'
printf '%s' "$rdp_password" | "$rdp_cli" connect --host 192.0.2.20 --user USER --password-stdin
unset rdp_password

Keep using this shell so rdp_cli remains defined. The pipe sends the password then closes standard input. For a domain account add --domain DOMAIN; do not combine multiple password sources. RDP currently defaults to --cert-policy ignore; inspect connect --help and configure certificate verification for your environment. A certificate policy does not repair an unreachable server or invalid credentials.

Read the JSON: on failure inspect error.code and error.message; on success save the returned data.session as SESSION.

Inspect status and your first PNG

"$rdp_cli" status --session SESSION
"$rdp_cli" screenshot --session SESSION --out first-screen.png

Check the connection and control state. Open first-screen.png with an image tool and identify the actual screen before deciding what to do. A connected session can still show login, Welcome or an application that is busy. Save the screenshot response's data.observation for a later input based on that image; it is not a permanent session identifier.

A local window is optional for screenshot and input commands. To let a person watch the same session on a Linux desktop:

"$rdp_cli" watch --session SESSION --viewer window

The window starts read-only. Human takeover is explicit. Closing a read-only viewer leaves the connection active; losing the viewer that owns control leaves input paused. After reconnect or handoff, inspect a fresh screenshot and respect the control state.

Resolve the specific failure

  • Wrong executable format: compare uname -m with the downloaded architecture; x86_64 and ARM64 files are not interchangeable.
  • Permission denied: check the execute bit and whether the chosen filesystem permits execution. Do not use elevated privileges as a substitute for choosing a suitable user directory.
  • Connection or authentication error: check route, port, Windows RDP service, account permission and the returned error. Do not repeatedly submit passwords or enable legacy TLS for unrelated failures.
  • SDL_INIT_FAILED without a desktop: native viewing needs a display session; headless CLI screenshots remain usable. Do not treat a viewer error alone as proof that RDP failed.
  • CREDENTIAL_STORE_FAILED: stored credentials use the host's Secret Service. If that service is unavailable, use an appropriate supported password source such as --password-stdin; do not claim a credential was saved.

Continue with the quick start, the command reference, or RDP file upload and download. File exchange additionally requires server drive redirection and file permission.