Empieza por la respuesta real

Guía para la interfaz RDP de rdp-cli 0.1.0 en Windows, macOS y Linux. Se basa en verificaciones de conexión y Agent de septiembre de 2026, no en nuevas pruebas de servidores. Usa un servidor Windows RDP autorizado y la versión actual para tu equipo. Los ejemplos usan rdp-cli en PATH; en Windows usa .\rdp-cli.exe desde su carpeta y en Linux el comando instalado o el ejecutable descargado.

rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION

Sustituye SESSION por tu ID de sesión. Ante un fallo, lee error.code, error.message y error.retryable. En un estado correcto revisa data.connection_state, data.control_state, data.last_error si existe y data.capabilities. Una marca de reintento no autoriza repetir entradas.

Comprueba la conexión por etapas

Error Comprobación y acción
CONNECT_TIMEOUT / RDP_CONNECT_FAILED Comprueba host, puerto configurado (normalmente 3389), ruta LAN/VPN y servicio RDP. Pide al administrador que revise la escucha y la regla de firewall permitida. Un puerto accesible no demuestra un inicio RDP correcto. Reintenta una vez tras corregir la causa.
RDP_TLS_HANDSHAKE_FAILED Revisa TLS en el servidor. El perfil predeterminado modern exige TLS 1.2. Usa --tls-profile legacy solo para un servidor antiguo identificado en una red de confianza: permite criptografía anterior. No lo apliques a todas las conexiones ni desactives la seguridad del servidor para pasar una prueba.
CERTIFICATE_UNTRUSTED Con --cert-policy strict, verifica el nombre y la cadena del certificado, o contrasta la huella SHA-256 con el administrador antes de guardar una confianza específica. El valor actual por defecto, ignore, no verifica la identidad. No cambies a ignore solo para ocultar el fallo.
AUTH_FAILED Revisa usuario, cuenta local o de dominio, --domain y permiso de inicio remoto. Usa el diálogo de contraseña o una referencia guardada del inicio rápido. No pruebes contraseñas repetidamente: un fallo TLS o un host inaccesible no demuestran una clave incorrecta.

Conectado, pero sin imagen útil

Ejecuta esta consulta de lectura y abre el PNG de data.path. connected significa que RDP se activó y recibió una imagen coherente; puede ser el inicio de sesión, la bienvenida o una pantalla negra. No confirma que el escritorio esté listo.

rdp-cli screenshot --session SESSION

Ante FRAME_UNAVAILABLE, revisa el estado y error.retryable, deja que termine la reconexión o el cambio de pantalla y captura otra vez. Si la imagen sigue negra, revisa el servidor, la suspensión del cliente o la VPN. Los casos históricos tuvieron causas distintas o no confirmadas. No escribas credenciales en un destino invisible ni consideres toda imagen estática un bloqueo del protocolo.

Resuelve errores de entrada y permisos

  • OBSERVATION_REQUIRED: captura y lee una imagen nueva; usa su data.observation en la próxima acción. Renuévala tras reconectar, ceder el control o cambiar las pantallas.
  • SESSION_PAUSED, CONTROL_HELD_BY_HUMAN o CONTROL_NOT_OWNED: detén la entrada y respeta al controlador actual. Reanuda solo tras una devolución autorizada y vuelve a capturar; no eludas la pausa con otro visor.
  • PERMISSION_DENIED / CAPABILITY_UNAVAILABLE: revisa la capacidad y la autorización. Abrir un visor no habilita funciones ausentes del servidor. UNICODE_INPUT_UNAVAILABLE requiere un método compatible, no reintentos ciegos.

Recupera una acción de resultado incierto

Antes de una entrada cuyo resultado pueda necesitar recuperación, asigna y guarda un --request-id único por acción distinta; sustituye los ID de ejemplo por valores propios. Si recibes un JSON de error, conserva su request_id de nivel superior; si se pierde toda la respuesta y no guardaste el ID original, no inventes otro para consultar la acción anterior ni la repitas a ciegas.

Tras REQUEST_TIMEOUT o SERVICE_UNAVAILABLE durante una acción, conserva el ID original. Comprueba el servicio local con list y consulta la operación antes de reintentar: la entrada puede haberse enviado aunque se perdiera la respuesta.

rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION

Sustituye REQUEST_ID por el valor original, no por el ID de la consulta. Comprueba data.state, data.result retenido y una captura nueva. OPERATION_NOT_FOUND puede indicar caducidad o cambio de servicio; no demuestra que no se ejecutara. Tras corregir la conexión, un reconnect explícito de una sesión no cerrada la deja en pausa. SESSION_CLOSED necesita una conexión nueva autorizada, no reconexiones repetidas.

Continúa con la evidencia necesaria

Si persiste, aporta versiones del cliente y servidor, protocolo, hora, código y estado/captura sin información sensible. Elimina contraseñas, tokens y contenido privado. La guía no acredita compatibilidad ni estabilidad prolongada de todos los servidores.

Descargar · Inicio rápido · Referencia de comandos