rdp-cli 명령어 참조

관찰·실행·검증

USER, SESSION, OBSERVATION, X, Y는 실제 값으로 바꿔야 합니다. stdin으로 암호를 전달한 뒤 스트림을 닫으세요. --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는 data.events와 data.ndjson을 담은 단일 JSON 결과를 반환합니다. 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

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를 명시적으로 허용합니다. 웹 HTTPS 검증에는 영향을 주지 않습니다.
• VNC는 --user, --domain, --size, --layout, --cert-policy, --tls-profile을 거부합니다. 고전 인증은 암호의 첫 8 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의 중복 방지를 기대하지 마세요.