rdp-cli 在线命令参考

观察、操作、验证

USER、SESSION、OBSERVATION、X 和 Y 均为占位符。通过标准输入提供密码后关闭输入流；--password-stdin 不会显示交互式密码提示。保存 data.session，读取 before.png，从图中选取坐标，再检查 after.png。输入已发送不等于任务已完成。

rdp-cli connect --host desktop.example.net --user USER --password-stdin
rdp-cli screenshot --session SESSION --out before.png
rdp-cli click --session SESSION --desktop --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out after.png

--version 显示版本与构建能力；--help-json 返回机器可读目录；COMMAND --help 可离线查看该命令的完整参数说明，不会启动会话。

rdp-cli --version
rdp-cli --help-json
rdp-cli connect --help

JSON 与通用参数

普通命令在 stdout 输出一个 UTF-8 JSON 对象：成功为 ok: true 与 data，失败为 ok: false 与 error。stderr 仅供诊断；退出码 0 表示成功，1 表示运行失败，2 表示命令或参数错误。

帮助输出纯文本。events --follow 流式输出 NDJSON；普通 events 返回一个 JSON 结果，其中含 data.events 与 data.ndjson。 Windows PowerShell 5.1 处理非 ASCII 文本时，应将 [Console]::OutputEncoding 与 $OutputEncoding 都设为 UTF-8。

data.session

保存 connect 返回的会话 ID，后续命令使用同一值。

data.observation

输入须使用截图返回的观察令牌；重连、控制权或布局变化后重新截图。

data.capabilities

先检查协商能力，再决定是否使用文件、音频、剪贴板或显示器操作。

data.state / data.remote_outcome

queued、sent、partial、unknown、cancelled、failed 表示输入进度。remote_outcome: not_confirmed 仍需查看远端结果。

data.transfer_id

把传输 ID 交给 files status 或 files cancel；等待终态并检查已完成文件的摘要。

error.code / error.message / error.retryable

使用稳定错误码决策，消息提供上下文；retryable 只是提示，不能据此盲目重复操作。

所有命令支持 --request-id 与 --timeout-ms。只有在保留窗口内，以完全相同的命令和参数重试时才复用请求 ID。本地超时不能证明输入未发送，应先查询 operations status。

协议与平台条件

• RDP 默认 --cert-policy ignore 与 --tls-profile modern。strict 核验证书信任及名称；legacy 显式允许较旧 TLS。两者均不改变 Web HTTPS 校验。
• VNC 不接受 --user、--domain、--size、--layout、--cert-policy、--tls-profile。经典认证只使用密码前八个 UTF-8 字节；无认证须明确 --vnc-security none 且不传密码。当前支持的 VNC 传输不加密。
• VNC 不提供文件、声音、麦克风与主动显示布局调整。剪贴板 UTF-8 取决于协商，否则仅接受 Latin-1。
• RDP 文件需要驱动器重定向；音频、剪贴板、麦克风、多屏也受服务端策略与协商能力影响。
• Windows/macOS 提供原生查看器及状态入口。Linux 原生窗口依赖桌面显示服务，音频依赖主机音频服务，保存凭据依赖 Secret Service；无桌面主机仍可使用支持的 CLI 操作。
• Unicode 输入会按远端应用兼容性节奏发送。为长文本设置合适超时并核对结果；切换输入法或打开查看器不能保证任意服务端接受所有字符。

错误恢复

OBSERVATION_REQUIRED / INVALID_COORDINATES

重新截图，检查屏幕布局并选择有效远端坐标。

SESSION_PAUSED / CONTROL_HELD_BY_HUMAN

停止输入，尊重人类控制；仅在明确交还 Agent 后继续。

AUTH_FAILED / VNC_AUTH_FAILED

检查账号、密码来源及远端认证策略。

RDP_TLS_HANDSHAKE_FAILED / CERTIFICATE_UNTRUSTED

核对服务器 TLS、证书策略与实际指纹，不要将 TLS 错误当作密码错误。

CAPABILITY_UNAVAILABLE / CLIPBOARD_ENCODING_UNSUPPORTED

检查协议能力或文本编码，选择支持的操作。

REQUEST_TIMEOUT / REQUEST_ID_CONFLICT / REQUEST_WINDOW_EXPIRED

重试前查询原操作和当前画面；不同参数不能复用 ID，保留窗口过期后也不能假定仍可去重。