Complete a small remote editing task

Connect to an existing VNC desktop, enter a short line in a blank document and confirm it on a new screenshot. This guide uses rdp-cli 0.1.0 and existing September 2026 acceptance evidence; it does not claim a new test run. The 20 September Mac workflow used a real Ubuntu 24.04 / TigerVNC 1.13.1 desktop with xterm. Later Linux acceptance also exercised authenticated TigerVNC. The example text below is a teaching example, not a replay of either session.

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 defaults to port 5900 and password authentication. Its supported security modes do not encrypt the desktop transport: use a trusted network or VPN. Classic VNC authentication uses only the first eight UTF-8 password bytes. Do not add RDP-only --user, --domain, layout or certificate options.

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.