rdp-cli

Connect to VNC and verify input from the command line

Applies to: 0.1.2 · Windows / macOS / Linux · VNC

Complete a small remote editing task

Connect to an existing VNC desktop, enter text in an application and check the result in a fresh screenshot. The steps below cover authentication, input and optional viewing or takeover.

Prepare the server and client

Install the appropriate download and follow the platform setup in the quick start. The remote computer must already run a reachable VNC server, with permission to view and control it. Prepare a blank document in a remote text editor. rdp-cli does not install the server or supply an AI model.

VNC normally uses port 5900. Choose the authentication offered by the server: classic vnc-auth uses a separate VNC password and only its first eight UTF-8 bytes; Mac account login uses --user MAC_USER --vnc-security ard with the Mac login password. With --user and no explicit security mode, rdp-cli selects ARD. Classic VNC and ARD do not encrypt the desktop stream; use a trusted LAN or VPN. Existing VeNCrypt/X509Plain servers instead require explicit --vnc-security x509-plain and a verified --vnc-tls-pin. RDP --domain and display-layout options do not apply to VNC. The commands below show classic password authentication; for a Mac account use the Mac authentication guide.

Connect with the correct protocol

Replace the documentation address and port. On macOS or Linux, run this block in Bash; macOS users can start bash first. On Linux replace rdp-cli with the installed command or your architecture's executable path.

IFS= read -r -s -p 'Password: ' vnc_password
printf '\n'
printf '%s' "$vnc_password" | rdp-cli connect --protocol vnc --host 192.0.2.20 --port 5900 --password-stdin
unset vnc_password

On Windows, use PowerShell in the EXE directory:

$secret = Read-Host 'Password' -AsSecureString
$savedEncoding = $OutputEncoding
try {
  $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
  [System.Net.NetworkCredential]::new('', $secret).Password |
    .\rdp-cli.exe connect --protocol vnc --host 192.0.2.20 --port 5900 --password-stdin
} finally {
  $OutputEncoding = $savedEncoding
  $secret.Dispose()
}

Read the JSON and save data.session as SESSION. Check ok and any error.code; a failed connection is not a reason to silently switch authentication. --vnc-security none is only for a server deliberately configured without authentication; it must be explicit and used without a password source. A saved --credential-ref is an alternative to --password-stdin, not an additional password source.

Observe, act and inspect again

For subsequent Windows commands replace rdp-cli with .\rdp-cli.exe; on Linux retain the correct executable path.

rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION --out vnc-before.png

Read vnc-before.png, confirm the intended desktop and editor, and save the screenshot's data.observation as OBSERVATION. Inspect the status response for the protocol, connection and control state. Choose the document's actual remote coordinates for X and Y:

rdp-cli click --session SESSION --desktop --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out vnc-focused.png

Read vnc-focused.png and verify focus. Use that response's data.observation as NEW_OBSERVATION:

rdp-cli type --session SESSION --text "VNC command check" --observation NEW_OBSERVATION
rdp-cli screenshot --session SESSION --out vnc-after.png

Open vnc-after.png and check that “VNC command check” appears exactly in the intended document. Input dispatch does not prove that the application accepted it. Do not reuse coordinates from this guide or a stale observation after a resize, reconnect or control change.

Watch or recover when necessary

A local viewer is optional. If a person wants to watch the same session:

rdp-cli watch --session SESSION --viewer window

It starts read-only. Pause, takeover and handoff remain explicit; the Agent must stop while input is paused or a person controls the session. Reconnection and server resize invalidate observations and leave control paused. Review a fresh screenshot before any authorized resume.

If connection fails, verify address, port, server authentication and network reachability; inspect the returned error rather than repeatedly trying passwords. If typed text differs, check focus, target keyboard layout and input method, then inspect again. VNC Unicode events do not guarantee every server/application combination accepts every character. For uncertain input outcomes, inspect the screen and query the original operation before repeating it.

Know the VNC limits

VNC supports the shared screenshot, input and viewing workflow, but no exchange-drive files, sound, microphone or client-requested display layouts. Those unavailable operations return CAPABILITY_UNAVAILABLE. UTF-8 clipboard text requires negotiated clipboard_utf8; otherwise the supported clipboard encoding is Latin-1. A viewer cannot add missing protocol capabilities.

Use the command reference for exact options, the protocol comparison to choose between RDP and VNC, and the quick start for platform-specific setup.