> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/freerdp/freerdp/llms.txt > Use this file to discover all available pages before exploring further. # xfreerdp > The xfreerdp X11 command-line client for Linux. Full option reference with connection, display, security, device-redirection, and performance flags. `xfreerdp` is the X11 RDP client and the reference frontend for FreeRDP. It exposes every FreeRDP setting through a rich command-line interface and is the best client to use when scripting connections or working on a traditional Linux desktop. ## Synopsis ```bash theme={null} xfreerdp [file.rdp] [options] [/v:[:port]] ``` Options can use either Windows-style (`/option:value`) or POSIX-style (`--option value`) syntax. FreeRDP auto-detects which style is in use. ## Quick examples ```bash Basic connection theme={null} xfreerdp /v:rdp.example.com /u:alice /p:secret ``` ```bash Domain user, fullscreen theme={null} xfreerdp /v:192.168.1.100 /u:CORP\\alice /p:secret /f ``` ```bash Custom resolution with NLA security theme={null} xfreerdp /v:rdp.example.com /u:alice /p:secret /w:1920 /h:1080 /sec:nla ``` ```bash RDP file with password override theme={null} xfreerdp connection.rdp /p:Pwd123! ``` ```bash RemoteApp theme={null} xfreerdp /v:rdp.example.com /u:alice /app:program:||notepad ``` ```bash Drive and clipboard redirection theme={null} xfreerdp /v:rdp.example.com /u:alice /drive:home,/home/alice /clipboard ``` ## Keyboard shortcuts (X11 client) | Shortcut | Action | | ----------------- | -------------------------------------------------- | | `Right Ctrl` | Release keyboard and mouse grab | | `Ctrl+Alt+Return` | Toggle fullscreen | | `Ctrl+Alt+M` | Minimise window | | `Ctrl+Alt+D` | Disconnect and exit | | `Ctrl+Alt+C` | Toggle remote control in remote-assistance session | ## Global config file The X11 client reads a JSON config at `@SYSCONF_DIR@/xfreerdp.json`. | Key | Type | Default | Description | | ----------------------- | ------- | ------- | ----------------------------- | | `isActionScriptAllowed` | boolean | `true` | Allow or block action scripts | An action script can be placed at `~/.config/freerdp/action.sh` or specified with `/action-script:`. It receives the current key combination as an argument; output containing `key-local` signals the script consumed the shortcut. *** ## Full option reference ### Connection options | Option | Format | Default | Description | | ------------------------------ | ----------------------------------------- | ------- | --------------------------------------------------- | | `/v:` | `[:port]` | — | Server hostname, IP, IPv6, vsock URI, or pipe path | | `/port:` | `` | `3389` | Server port | | `/u:` | `[[\\]\|[@]]` | — | Username | | `/d:` | `` | — | Domain | | `/p:` | `` | — | Password (omit value to silence interactive prompt) | | `/pth:` | `` | — | Pass-the-hash (restricted admin mode) | | `/admin` | flag | — | Admin / console session | | `/vmconnect:` | `` | — | Hyper-V console (port 2179, disables negotiation) | | `/shell:` | `` | — | Alternate shell on the server | | `/shell-dir:` | `` | — | Shell working directory | | `/from-stdin` | `[force]` | — | Read credentials from stdin | | `/args-from:` | `\|stdin\|fd:\|env:` | — | Read command-line arguments from a source | | `/timeout:` | `` | `9000` | Connection timeout in milliseconds | | `/auto-reconnect` | toggle | off | Automatic reconnection on disconnect | | `/auto-reconnect-max-retries:` | `` | — | Maximum reconnect attempts (0 = unlimited) | | `/reconnect-cookie:` | `` | — | Resume session with reconnect cookie | | `/load-balance-info:` | `` | — | Load-balancer routing token | | `/pcb:` | `` | — | Preconnection Blob (Hyper-V) | | `/pcid:` | `` | — | Preconnection Id | | `/ipv4` | `[:force]` | — | Prefer IPv4 A record | | `/ipv6` | `[:force]` | — | Prefer IPv6 AAAA record | ### Authentication | Option | Format | Default | Description | | ------------------------- | ---------------------------------------------------------------------- | ------- | -------------------------------- | | `/sec:` | `rdp\|tls\|nla\|ext\|aad[:[on\|off]]` | auto | Force specific security protocol | | `/cert:` | `deny\|ignore\|name:\|tofu\|fingerprint::` | — | Certificate handling policy | | `/tls:` | `ciphers:\|seclevel:<0-5>\|secrets-file:\|enforce[:]` | — | TLS tuning | | `/nego` | toggle | on | Protocol security negotiation | | `/smartcard-logon` | `[cert:

,key:,pin:

,csp:,reader:,card:]` | — | Smartcard logon authentication | | `/restricted-admin` | flag | — | Restricted admin mode | | `/auth-only` | toggle | off | Authenticate then disconnect | | `/credentials-delegation` | toggle | off | Delegate credentials (CredSSP) | | `/auth-pkg-list:` | `[[none],][!ntlm,kerberos,!u2u]` | all | Authentication package filter | | `/kerberos:` | `kdc-url:,cache:,armor:,...` | — | Kerberos options | | `/assistance:` | `` | — | Remote assistance password | | `/spn-class:` | `` | — | SPN authentication service class | | `/sspi-module:` | `` | — | External SSPI shared library | ### Display and window | Option | Format | Default | Description | | --------------------- | -------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------- | | `/w:` | `` | `1024` | Window/session width in pixels | | `/h:` | `` | `768` | Window/session height in pixels | | `/size:` | `x` or `%[wh]` | `1024x768` | Screen size (alternative to `/w:` + `/h:`) | | `/f` | flag | — | Fullscreen mode (Ctrl+Alt+Enter to toggle) | | `/multimon` | `[force]` | — | Span across all monitors | | `/monitors:` | `[,...]` | — | Select specific monitor IDs (use with `/f` or `/multimon`) | | `/span` | flag | — | Span screen over multiple monitors | | `/dynamic-resolution` | toggle | off | Send resize events when the window is resized | | `/smart-sizing` | `[x]` | — | Scale remote desktop to fit the window | | `/orientation:` | `0\|90\|180\|270` | `0` | Display rotation | | `/scale:` | `100\|140\|180` | `100` | Global display scaling factor | | `/scale-desktop:` | `` | `100` | Scaling for desktop apps (100–500) | | `/scale-device:` | `100\|140\|180` | `100` | Scaling for Store/app-store apps | | `/workarea` | flag | — | Use the available work area (excludes taskbar) | | `/decorations` | toggle | on | Window decorations | | `/floatbar` | `[sticky:[on\|off],default:[visible\|hidden],show:[always\|fullscreen\|window]]` | off | Floating toolbar | | `/t:` | `` | — | Window title | | `/wm-class:` | `<class>` | — | X11 WM\_CLASS hint | | `/window-position:` | `<x>x<y>` | — | Initial window position | | `/parent-window:` | `<id>` | — | Embed into an existing X11 window | | `/pwidth:` | `<mm>` | — | Physical display width (millimetres) | | `/pheight:` | `<mm>` | — | Physical display height (millimetres) | ### Performance and codecs | Option | Format | Default | Description | | ---------------------- | ------------------------------------------------------------------------------- | ------- | -------------------------------------------- | | `/gfx` | `[progressive\|RFX\|AVC420\|AVC444,mask:<v>,small-cache,thin-client,frame-ack]` | auto | RDP8 Graphics Pipeline (GFX) | | `/rfx` | flag | — | RemoteFX codec | | `/rfx-mode:` | `image\|video` | — | RemoteFX mode | | `/nsc` | flag | — | NSCodec (NS Codec) support | | `/bpp:` | `<depth>` | `16` | Colour depth (8, 15, 16, 24, 32) | | `/network:` | `modem\|broadband\|broadband-low\|broadband-high\|wan\|lan\|auto` | auto | Network type preset | | `/compression` | toggle | on | Bulk data compression | | `/compression-level:` | `0\|1\|2` | — | Compression level | | `/gdi:` | `sw\|hw` | `sw` | GDI rendering backend (software or hardware) | | `/video` | flag | — | Video-optimised remoting channel | | `/max-fast-path-size:` | `<bytes>` | — | Maximum fast-path PDU size | | `/frame-ack:` | `<n>` | — | Number of frame-acknowledgement PDUs | | `/wallpaper` | toggle | on | Show remote wallpaper | | `/themes` | toggle | on | Enable remote themes | | `/aero` | toggle | off | Desktop composition (Aero) | | `/window-drag` | toggle | off | Full-window drag | | `/menu-anims` | toggle | off | Menu animations | | `/fonts` | toggle | on | ClearType / font smoothing | ### Audio | Option | Format | Description | | -------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- | | `/sound` | `[sys:<sys>,dev:<dev>,format:<fmt>,rate:<r>,channel:<ch>,latency:<ms>,quality:<q>]` | Audio output (RDPSND + dynamic channel) | | `/microphone` | `[sys:<sys>,dev:<dev>,format:<fmt>,rate:<r>,channel:<ch>]` | Audio input (audin dynamic channel) | | `/audio-mode:` | `<mode>` | Audio output mode (0=local, 1=remote, 2=none) | **Examples:** ```bash theme={null} # ALSA audio output xfreerdp /v:host /sound:sys:alsa # OSS audio with specific device xfreerdp /v:host /sound:sys:oss,dev:1,format:1 # Microphone with ALSA xfreerdp /v:host /microphone:sys:alsa ``` ### Device redirection | Option | Format | Description | | ------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- | | `/drive:` | `<name>,<path>` | Redirect a local directory as a named share | | `/drives` | toggle | Redirect all mount points | | `/home-drive` | toggle | Redirect the user's home directory | | `/clipboard` | `[[use-selection:<atom>],[direction-to:[all\|local\|remote\|off]],[files-to:[...]]]` | Clipboard redirection | | `/printer` | `[<name>[,<driver>[,default]]]` | Redirect a printer | | `/smartcard` | `[<str>[,<str>...]]` | Redirect smartcard(s) matching name fragment | | `/serial` | `[<name>[,<path>[,<driver>[,permissive]]]]` | Redirect a serial port | | `/parallel` | `[<name>[,<path>]]` | Redirect a parallel port | | `/usb:` | `[id:<vid>:<pid>#...,addr:<bus>:<addr>#...,auto]` | Redirect USB device (requires URBDRC) | | `/multitouch` | toggle | Redirect multitouch input | | `/rdp2tcp:` | `<executable[:arg...]>` | TCP tunnel via external process | **Drive redirection examples:** ```bash theme={null} # Named share from a specific path xfreerdp /v:host /drive:home,/home/alice # Hotplug all removable drives xfreerdp /v:host /drive:hotplug,* # Redirect the home directory shortcut xfreerdp /v:host /home-drive ``` ### RemoteApp | Option | Format | Description | | ------- | ------------------------------------------------------------------------------------------------------- | ------------------ | | `/app:` | `program:[<path>\|\|<alias>],cmd:<cmd>,file:<f>,guid:<g>,icon:<f>,name:<n>,workdir:<d>,hidef:[on\|off]` | Launch a RemoteApp | ```bash theme={null} # Launch Notepad as RemoteApp xfreerdp /v:rdp.example.com /u:alice /app:program:||notepad # Launch with explicit path and working directory xfreerdp /v:host /app:program:"C:\\Windows\\system32\\notepad.exe",workdir:"C:\\\" ``` ### Gateway and proxy | Option | Format | Description | | ----------- | ------------------------------------------------------------------------------------------------- | ----------------- | | `/gateway:` | `g:<host>[:<port>],u:<user>,d:<domain>,p:<pass>,type:[rpc\|http\|auto\|arm],access-token:<token>` | RD Gateway | | `/proxy:` | `[<proto>://][<user>:<pass>@]<host>[:<port>]` | HTTP/SOCKS5 proxy | ```bash theme={null} # Connect through an RD Gateway xfreerdp /v:internal.host /gateway:g:gateway.example.com,u:alice,d:CORP,p:secret # Use HTTPS_PROXY for gateway connections export https_proxy=http://proxy.example.com:3128/ xfreerdp /gateway:g:rdp.example.com ... ``` ### Virtual channels | Option | Format | Description | | ----------------- | ----------------------- | -------------------------------- | | `/vc:` | `<channel>[,<options>]` | Add a static virtual channel | | `/dvc:` | `<channel>[,<options>]` | Add a dynamic virtual channel | | `/disp` | flag | Display control channel (`disp`) | | `/geometry` | flag | Geometry tracking channel | | `/echo` | flag | Echo channel | | `/ssh-agent` | flag | SSH agent forwarding channel | | `/multitouch` | toggle | Multitouch input channel | | `/heartbeat` | toggle | Heartbeat PDU support | | `/multitransport` | toggle | Multitransport (UDP) support | ### Keyboard | Option | Format | Description | | ---------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `/kbd:` | `layout:<id\|name>,lang:<id>,fn-key:<v>,type:<v>,subtype:<v>,unicode[:on\|off],remap:<k>=<v>,pipe:<path>` | Keyboard settings | | `/grab-keyboard` | toggle | Grab keyboard and forward all keys to remote | | `/grab-mouse` | toggle | Grab mouse inside the window | ```bash theme={null} # Set keyboard layout by name xfreerdp /v:host /kbd:layout:en-US # Remap scancode: swap 'a' and 's' on a US keyboard xfreerdp /v:host /kbd:remap:0x1e=0x1f,remap:0x1f=0x1e # Enable Unicode keyboard input xfreerdp /v:host /kbd:unicode:on ``` ### Listing / discovery | Option | Value | Description | | -------------- | --------------------- | --------------------------------- | | `/list:` | `monitor` | List detected monitors | | `/list:` | `kbd` | List available keyboard layouts | | `/list:` | `kbd-lang[:<filter>]` | List keyboard language IDs | | `/list:` | `kbd-scancode` | List RDP scancodes | | `/list:` | `smartcard` | List smartcard readers | | `/list:` | `timezones` | List supported Windows time zones | | `/list:` | `tune` | List all internal settings | | `/version` | flag | Print FreeRDP version | | `/buildconfig` | flag | Print build configuration | ### Miscellaneous | Option | Format | Default | Description | | ----------------------- | --------------------------------------------- | ----------------------------- | --------------------------------------------------- | | `/timezone:` | `<windows tz name>` | — | Override time zone sent to server | | `/client-hostname:` | `<name>` | — | Client hostname sent to the server | | `/client-build-number:` | `<n>` | — | Client build number (affects smartcard behaviour) | | `/server-name:` | `<name>` | — | Alternate server name for TLS/Kerberos validation | | `/redirect-prefer:` | `FQDN\|IP\|NETBIOS` | — | Override redirection preference order | | `/tune:` | `<key:value>[,...]` | — | Directly set internal FreeRDP settings (expert use) | | `/log-level:` | `OFF\|FATAL\|ERROR\|WARN\|INFO\|DEBUG\|TRACE` | — | Default log level | | `/log-filters:` | `<tag>:<level>[,...]` | — | Per-tag log filters (see `wLog(7)`) | | `/dump:` | `record\|replay,file:<path>[,nodelay]` | — | Record or replay an RDP session | | `/disable-output` | flag | — | Disable all graphics decoding (for load testing) | | `/prevent-session-lock` | `[<secs>]` | `180s` | Inject idle mouse events to keep session alive | | `/action-script:` | `<path>` | `~/.config/freerdp/action.sh` | Key-combination action script | ## Environment variables | Variable | Description | | ----------------------------- | --------------------------------------------------------------------- | | `WLOG_LEVEL` | Default log level (e.g. `DEBUG`, `TRACE`) | | `WLOG_FILTER` | Log filter string (e.g. `com.freerdp.core:TRACE`) | | `https_proxy` / `HTTPS_PROXY` | Proxy used for RD Gateway connections | | `FREERDP_WLROOTS_HACK` | (SDL3 only) Multimonitor detection workaround for wlroots compositors | ## Exit codes | Code | Meaning | | -------- | ----------------------------------------------- | | `0` | Successful disconnect | | `1` | Logoff | | `2` | Idle timeout | | `3` | Logon timeout | | `4` | Connection replaced by another session | | Non-zero | Error (connection failure, bad arguments, etc.) |