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，保留窗口過期後也不能假定仍可去重。