Before you connect
You need a Windows computer with an enabled RDP service, an account allowed to sign in remotely, and a network route from the Mac to that server. Enabling a Windows remote desktop service is separate from installing this client. Use your LAN or VPN when the server is not publicly reachable.
Choose the package for your Mac on the download page: Apple silicon requires macOS 13 or later; Intel requires macOS 12 or later. Check that page for download availability. Download the matching DMG, open it, and drag rdp-cli to Applications. Run this command to make the CLI available:
/Applications/rdp-cli.app/Contents/MacOS/rdp-cli install-cli
rdp-cli --help
If the terminal cannot find rdp-cli, open a new terminal or run the executable directly from the app path above. The DMG also includes a standalone executable.
Create a session
Replace the example address and USER with your authorized server and account. In macOS Terminal (zsh), paste the following block, enter your password at the prompt and press Return. The password is not displayed; the command passes it to rdp-cli and finishes the input automatically.
read -r -s "rdp_password?Password: "
printf '\n'
printf '%s' "$rdp_password" | rdp-cli connect --host 192.0.2.20 --user USER --password-stdin
unset rdp_password
For a domain account, add --domain DOMAIN. An existing saved credential can instead be referenced with --credential-ref CREDENTIAL; do not combine password sources. Inspect rdp-cli connect --help for certificate options. The current RDP default is ignore, so configure certificate verification according to your environment.
Read the returned JSON. Continue only after examining its state, and save data.session. Do not copy an old session ID from a tutorial. A connected session can still show a login or Welcome screen: look at the image before deciding what to do next.
Capture the actual desktop
Use your returned session value in place of SESSION:
rdp-cli screenshot --session SESSION --out first-screen.png
Open first-screen.png. The screenshot response also contains data.observation. Keep that value for input based on this image. It is not a permanent password or reusable session ID; reconnects, control changes and display changes can invalidate it.
Watch only when you want to
The remote connection does not require a local window. If you want to follow what the agent is doing, open the existing session:
rdp-cli watch --session SESSION --viewer window
The window starts read-only. Use its control buttons to pause or take over. Closing a read-only viewer leaves the session connected; closing a viewer that owns control leaves input paused.
If a connection fails
Check the server address, network route, RDP availability and account permission. Read the structured error instead of repeatedly sending a password. Older servers may need an explicitly selected compatibility setting; do not apply it to unrelated sessions. For an existing session, inspect rdp-cli status --session SESSION before retrying an action.
Next, follow the command workflow or learn how to watch and take over.