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

xfreerdp [file.rdp] [options] [/v:<server>[: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

Basic connection

xfreerdp /v:rdp.example.com /u:alice /p:secret

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:<path>. 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:	<server>[:port]	—	Server hostname, IP, IPv6, vsock URI, or pipe path
/port:	<number>	3389	Server port
/u:	[[<domain>\\]<user>|<user>[@<domain>]]	—	Username
/d:	<domain>	—	Domain
/p:	<password>	—	Password (omit value to silence interactive prompt)
/pth:	<hash>	—	Pass-the-hash (restricted admin mode)
/admin	flag	—	Admin / console session
/vmconnect:	<vmid>	—	Hyper-V console (port 2179, disables negotiation)
/shell:	<shell>	—	Alternate shell on the server
/shell-dir:	<dir>	—	Shell working directory
/from-stdin	[force]	—	Read credentials from stdin
/args-from:	<file>|stdin|fd:<n>|env:<name>	—	Read command-line arguments from a source
/timeout:	<ms>	9000	Connection timeout in milliseconds
/auto-reconnect	toggle	off	Automatic reconnection on disconnect
/auto-reconnect-max-retries:	<n>	—	Maximum reconnect attempts (0 = unlimited)
/reconnect-cookie:	<base64>	—	Resume session with reconnect cookie
/load-balance-info:	<string>	—	Load-balancer routing token
/pcb:	<blob>	—	Preconnection Blob (Hyper-V)
/pcid:	<id>	—	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:<n>|tofu|fingerprint:<hash>:<hex>	—	Certificate handling policy
/tls:	ciphers:<list>|seclevel:<0-5>|secrets-file:<path>|enforce[:<ver>]	—	TLS tuning
/nego	toggle	on	Protocol security negotiation
/smartcard-logon	[cert:<p>,key:<k>,pin:<p>,csp:<c>,reader:<r>,card:<c>]	—	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:<url>,cache:<path>,armor:<path>,...	—	Kerberos options
/assistance:	<password>	—	Remote assistance password
/spn-class:	<class>	—	SPN authentication service class
/sspi-module:	<path>	—	External SSPI shared library

Display and window

Option	Format	Default	Description
/w:	<width>	1024	Window/session width in pixels
/h:	<height>	768	Window/session height in pixels
/size:	<w>x<h> or <pct>%[wh]	1024x768	Screen size (alternative to /w: + /h:)
/f	flag	—	Fullscreen mode (Ctrl+Alt+Enter to toggle)
/multimon	[force]	—	Span across all monitors
/monitors:	<id>[,<id>...]	—	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	[<w>x<h>]	—	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:	<pct>	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:	<title>	—	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:

# 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:

# 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

# 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

# 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

# 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.)