Windscribe offers two Linux apps: a graphical app and a command-line app. The graphical app needs a desktop environment, so on a headless or terminal-only machine, use the Linux CLI app. This guide covers installing it, signing in, connecting, and where to configure the rest.
Linux CLI commands use the windscribe-cli name (the -cli suffix), for example windscribe-cli login and windscribe-cli connect.
Downloads for both the GUI and CLI apps are available from the Windscribe download page. Windscribe is open source, and source code and release assets are published on GitHub.
For headless use, download the Linux CLI build that matches your distribution and architecture.
AMD64:
curl -L https://windscribe.com/install/desktop/linux_deb_x64_cli -o windscribe.deb sudo apt install ./windscribe.deb
ARM64:
curl -L https://windscribe.com/install/desktop/linux_deb_arm64_cli -o windscribe.deb sudo apt install ./windscribe.deb
Linux CLI builds for Fedora/CentOS, Arch, and openSUSE are available from the download page. Download the build for your distribution and install it with your distribution's package manager.
Run windscribe-cli commands as your normal user. The only step that needs sudo is the package install above.
Sign in with your Windscribe account:
windscribe-cli login
Connect to the VPN:
windscribe-cli connect
Check your connection status:
windscribe-cli status
Once you are connected, it is worth confirming that your traffic is actually routing through the VPN. A status of Connected is a good sign, but it is not proof on its own. Start with:
windscribe-cli status
Along with the connection state and city, status reports your protocol and port, the Firewall state, and your data usage, which is handy for keeping an eye on a free plan's monthly allowance. Two markers are worth knowing: an asterisk in front of Connected means the tunnel test is still running, and a note about network interference means the test found something worth looking into.
For an independent check on a headless machine, confirm that your public IP address has changed. You can do this without a browser by querying a lookup service before and after connecting:
curl ifconfig.me
If the address returned while connected reflects the location you chose rather than your real one, traffic is leaving through the tunnel. We would rather you check than take our word for it.
DNS is worth a thought too. By default we route DNS through our own servers while you are connected, which is what applies R.O.B.E.R.T. filtering. If you have set a custom DNS server in the config file, confirm that it is the one resolving your queries rather than your provider's.
Running windscribe-cli connect on its own reconnects you to your last used location, or picks one for you. To see the full list of locations you can connect to:
windscribe-cli locations
Locations are listed in the format Region - City - Nickname. You can connect using the city name, the nickname, the region name, or the two-letter country code. Matching is not case-sensitive.
windscribe-cli connect "Toronto" windscribe-cli connect CA
To let the app choose a server for you based on latency:
windscribe-cli connect best
To view your favorite locations, including any pinned IPs:
windscribe-cli locations fav
To disconnect from the VPN at any time:
windscribe-cli disconnect
The Linux CLI app supports WireGuard, OpenVPN in UDP and TCP modes, Stealth, and WStunnel. IKEv2 is available in the Windows and macOS apps, but not on Linux. Stealth and WStunnel are slower and are mainly useful on restrictive networks. To change protocols, add the protocol name after the location:
windscribe-cli connect best wireguard windscribe-cli connect "Toronto" stealth
Protocol names are not case-sensitive. To connect on a specific port, add it after the protocol with a colon:
windscribe-cli connect best udp:443
To list the ports available for a protocol:
windscribe-cli ports wireguard
If you enter a port that is not available, the app falls back to the default port for that protocol.
The Firewall blocks traffic outside the VPN tunnel, which helps prevent leaks if the connection drops. To turn it on or off:
windscribe-cli firewall on windscribe-cli firewall off
Be careful with the Firewall on machines you manage over SSH. If the VPN is not connected while the Firewall is on, it can block your SSH session along with everything else. If you connect over the local network, the AllowLANTraffic option below lets local traffic through.
Logging out with windscribe-cli logout disconnects the VPN and turns the Firewall off. To log out and keep the Firewall up:
windscribe-cli logout on
The Linux CLI app reads its settings from a configuration file:
~/.config/Windscribe/windscribe_cli.conf
Values in this file are case-sensitive and must match the allowed values exactly. If a value does not match, the app uses its default instead. After editing the file, apply your changes:
windscribe-cli preferences reload
Lets devices on your local network reach the machine while the VPN and Firewall are active. This is the setting to enable if you SSH into a headless machine from the same network:
[Connection] AllowLANTraffic=true
Connects to the VPN automatically when the Windscribe service starts:
[Connection] Autoconnect=true
By default, the app uses Windscribe's DNS while connected, which is what applies R.O.B.E.R.T. filtering. To use a different DNS server, switch the mode to Custom and set an upstream. Upstream values accept plain IPs or DNS-over-HTTPS/TLS URLs:
[Connection] ConnectedDNSMode=Custom ConnectedDNSUpstream1=1.1.1.1
Split tunneling routes specific apps or network ranges inside or outside the VPN tunnel. Exclude mode sends everything through the VPN except what you list. Include mode sends only what you list through the VPN:
[Connection] SplitTunnelingEnabled=true SplitTunnelingMode=Exclude SplitTunnelingApps=/usr/bin/curl SplitTunnelingRoutes=192.168.1.0/24
App entries are full paths to executables, separated by commas. Paths that do not exist are silently skipped, so double-check them if an app is not behaving as expected.
You can share the VPN connection with other devices on your network as an HTTP or SOCKS proxy:
[Connection] ShareProxyGatewayEnabled=true ShareProxyGatewayMode=HTTP ShareProxyGatewayPort=8888
Set ShareProxyGatewayMode to HTTP or SOCKS, and pick any port between 1024 and 65535.
For the full list of available options, see the Linux CLI configuration file reference.
Get a new IP address on the same server, available on some plans while connected:
windscribe-cli ip rotate
Check for and install app updates:
windscribe-cli update
Send debug logs to Windscribe support, which is handy when troubleshooting a headless machine:
windscribe-cli logs send
R.O.B.E.R.T. is Windscribe's domain-blocking feature. Rules are not managed from the CLI. Instead, they are set from My Account. The number of custom rules depends on your plan:
When something goes wrong, the CLI prints the error to the terminal and returns exit code 1 instead of 0, so scripts can tell success from failure. A few of the more common messages:
The CLI could not start the background service it talks to. Wait a moment and run the command again. If it keeps happening, check that the windscribe-helper service is running.
The connection between the CLI and the background service dropped partway through a command. This is often temporary, so retry the command. It can also happen right after a Firewall or LAN setting changes while the VPN is active, so give it a second to settle before trying again.
The Firewall is in Always On mode and cannot be turned off from the CLI. This mode is set in the desktop app, so if you need it off you will have to change it there. On a headless machine you are unlikely to see this unless the preference was set earlier on a system with the graphical app.
This usually points to a problem setting up the network adapter. Switching to another protocol, such as UDP or TCP, often gets you connected while you look into it:
windscribe-cli connect best udp
If none of these fit, send your debug logs to our support team so they can take a look:
windscribe-cli logs send
To see the full list of commands the CLI supports, along with a short description of each, run:
windscribe-cli --help
For step-by-step articles and answers to common questions, our knowledge base is a good next stop: windscribe.com/knowledge-base.
If you need to remove the CLI app, use your distribution's package manager. The package is named windscribe-cli.
Remove the package:
sudo apt remove windscribe-cli
To also clear system configuration, use purge instead:
sudo apt purge windscribe-cli
On Fedora/CentOS, Arch, or openSUSE, remove the windscribe-cli package with your package manager, for example dnf remove, pacman -R, or zypper remove.
Your personal settings live in a separate config directory that the package manager does not touch. To remove those as well, delete it:
rm -r ~/.config/Windscribe
Use the Linux CLI-only build. The graphical app needs a desktop environment, so it will not run on a terminal-only or headless machine. The CLI build is the one whose download links end in _cli, and it always sends its output to the terminal.
Yes. Free accounts include 2 GB of data per month, which increases to 10 GB per month once you confirm your email address, and can connect to the free locations. The CLI works the same on free and paid plans. A few things, such as static IPs and IP rotation, need a paid plan.
No. Run windscribe-cli commands as your normal user. The only step that needs sudo is the package install during setup.
WireGuard is a good default and supports post-quantum encryption. If you are on a network that blocks or throttles VPNs, Stealth and WStunnel are built to get through, though they tend to be slower. OpenVPN in UDP or TCP mode is available if you need it. You can list what a protocol offers with windscribe-cli ports.
On the CLI-only build, locations prints to the terminal as expected. If it comes back empty, you are most likely running the graphical desktop app instead, where the locations command opens the list in the app window rather than the terminal. On a headless machine, install the CLI-only build.
Run windscribe-cli login and enter your username and password. If two-factor authentication is enabled, you are prompted for the code afterward. If a CAPTCHA is required, the CLI-only build renders it as ASCII art in the terminal so you can still solve it without a browser.
Set the VPN to connect automatically when the service starts by adding Autoconnect=true to the config file, as shown earlier. On a headless box that never has an interactive login session, you also need the service to run without you logging in. Enable lingering for your user:
loginctl enable-linger <username>
No. Those are handled from the My Account dashboard on the website, not the command line. The same applies to unlocking streaming, static IP management, and downloading manual config files. The CLI covers connecting, protocols, the Firewall, DNS, split tunneling, and proxy sharing.
With the Firewall on and the VPN not connected, all non-VPN traffic is blocked, which can include the SSH session you are managing the machine through. If you connect over the local network, set AllowLANTraffic=true in the config file so local traffic is allowed even when the Firewall is active. If you are already locked out, you will need console or physical access to run windscribe-cli firewall off. To avoid this, set AllowLANTraffic before you turn the Firewall on rather than changing it mid-session.