From a Linux executable to a remote screenshot

This guide takes you from downloading rdp-cli to inspecting a Windows desktop over RDP. It describes version 0.1.0 using existing release evidence: Linux x86_64 build 2026092203 passed software acceptance on ten systems, and ARM64 build 2026092301 on twelve environments including Raspberry Pi 4 and DGX Spark. This article is not a new test run or a claim that every Linux distribution has been tested.

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

Expect JSON version information from --version. The product is a single static ELF and can run as an ordinary user; no root installation is needed. A native viewer still uses your running desktop's display services. The release's tested scope does not imply every desktop, kernel or audio device has been accepted.

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.