Command-Line Interface

The Mullvad VPN command-line interface (CLI) provides full control over the VPN client through terminal commands. It’s ideal for automation, scripting, and advanced users who prefer terminal-based workflows.

Overview

The CLI communicates with the mullvad-daemon system service to control all VPN functionality.

Binary Name

mullvad

Platform Availability

Windows: mullvad.exe (in Program Files)
macOS: /usr/local/bin/mullvad
Linux: /usr/bin/mullvad

The CLI is automatically installed with the desktop application on all platforms.

Installation

Desktop Platforms

The CLI is included with the desktop app installation:

Automatic: Installed alongside the GUI application
PATH: Added to system PATH during installation
Permissions: No special permissions required (communicates with daemon)

Verify Installation

mullvad version

Should display the installed version.

Basic Usage

Connection Management

Connect to VPN

# Connect to VPN
mullvad connect

# Connect and wait until connected
mullvad connect --wait
mullvad connect -w

Disconnect from VPN

# Disconnect from VPN
mullvad disconnect

# Disconnect and wait until fully disconnected
mullvad disconnect --wait
mullvad disconnect -w

Reconnect

# Reconnect to VPN (disconnect and connect again)
mullvad reconnect

# Reconnect and wait
mullvad reconnect --wait

Check Status

# Show current connection status
mullvad status

# Show status with detailed information
mullvad status -v
mullvad status --verbose

# Output status as JSON
mullvad status --json

Example output:

Secured
Connected to se-got-wg-001
IPv4: 10.68.124.45
IPv6: fc00:bbbb:bbbb:bb01::3:7c2c

Account Management

Manage your Mullvad account:

# Login with account number
mullvad account login 1234567890123456

Account Information

# Show account information
mullvad account show

# Show account expiry
mullvad account expiry

Logout

# Logout and remove account from device
mullvad account logout

Device Management

# List devices on account
mullvad account list-devices

# Remove a device
mullvad account remove-device <device-id>

# Set device name
mullvad account set-device-name "My Laptop"

Server Selection

List Available Servers

# List all countries
mullvad relay list countries

# List all cities in a country
mullvad relay list cities se  # Sweden

# List all servers in a city
mullvad relay list servers se got  # Gothenburg, Sweden

Set Server Location

# Set specific country
mullvad relay set location se

# Set specific city
mullvad relay set location se got

# Set specific server
mullvad relay set location se got-wg-001

# Use any server
mullvad relay set location any

Server Constraints

# Show current constraints
mullvad relay show

# Set server by ownership
mullvad relay set ownership mullvad-owned
mullvad relay set ownership rented
mullvad relay set ownership any

# Set server by provider
mullvad relay set provider 31173  # AS number

Tunnel Configuration

WireGuard Settings

# Show current tunnel protocol
mullvad tunnel show

# Set WireGuard port
mullvad tunnel wireguard port set 51820
mullvad tunnel wireguard port set auto

# Show WireGuard key
mullvad tunnel wireguard key show

# Rotate WireGuard key
mullvad tunnel wireguard key rotate

# Set custom MTU
mullvad tunnel wireguard mtu set 1380
mullvad tunnel wireguard mtu unset

# Enable quantum-resistant tunnel
mullvad tunnel wireguard quantum-resistant on
mullvad tunnel wireguard quantum-resistant off

Multihop

# Enable multihop
mullvad tunnel wireguard multihop on

# Disable multihop
mullvad tunnel wireguard multihop off

# Set entry location (used with multihop)
mullvad relay set location entry se

DAITA

# Enable DAITA (Defense Against AI-Guided Traffic Analysis)
mullvad tunnel wireguard daita on

# Disable DAITA
mullvad tunnel wireguard daita off

Obfuscation

Configure obfuscation to bypass censorship:

Anti-Censorship Settings

# Show obfuscation settings
mullvad anti-censorship show

# Enable automatic obfuscation
mullvad anti-censorship on

# Disable obfuscation
mullvad anti-censorship off

# Set specific obfuscation protocol
mullvad anti-censorship set protocol udp2tcp
mullvad anti-censorship set protocol shadowsocks

# Set obfuscation port
mullvad anti-censorship set port auto
mullvad anti-censorship set port 443

DNS Configuration

DNS Settings

# Show current DNS settings
mullvad dns show

# Set custom DNS server (through tunnel)
mullvad dns set custom 1.1.1.1
mullvad dns set custom 1.1.1.1 1.0.0.1  # Multiple servers

# Use default DNS (VPN server)
mullvad dns set default

# Enable content blocking
mullvad dns set blocking-options ads trackers malware

# Disable content blocking
mullvad dns unset blocking-options

Content Blocking Options

ads - Block advertisements
trackers - Block tracking domains
malware - Block malicious domains
gambling - Block gambling sites
adult - Block adult content
social-media - Block social media platforms

Split Tunneling

Configure application exclusions:

Application-Based Split Tunneling

# Show split tunneling status
mullvad split-tunnel show

# Enable split tunneling
mullvad split-tunnel on

# Disable split tunneling
mullvad split-tunnel off

# Add application to exclusions
mullvad split-tunnel add /usr/bin/firefox
mullvad split-tunnel add "C:\Program Files\Firefox\firefox.exe"

# Remove application from exclusions
mullvad split-tunnel remove /usr/bin/firefox

# List excluded applications
mullvad split-tunnel list

# Clear all exclusions
mullvad split-tunnel clear

Security Settings

Auto-Connect

# Enable auto-connect on app start
mullvad auto-connect on

# Disable auto-connect
mullvad auto-connect off

# Show current setting
mullvad auto-connect show

Lockdown Mode

# Enable lockdown mode (block traffic when disconnected)
mullvad lockdown-mode on

# Disable lockdown mode
mullvad lockdown-mode off

# Show current setting
mullvad lockdown-mode show

# Enable local network access
mullvad lan on

# Disable local network access
mullvad lan off

# Show current setting
mullvad lan show

API Access Methods

Configure how to reach Mullvad API:

# List API access methods
mullvad api-access list

# Add SOCKS5 proxy
mullvad api-access add socks5 127.0.0.1:1080

# Add Shadowsocks proxy
mullvad api-access add shadowsocks <server-ip>:8388 <password> <cipher>

# Enable/disable access method
mullvad api-access enable <id>
mullvad api-access disable <id>

# Remove access method
mullvad api-access remove <id>

# Test access methods
mullvad api-access test

Custom Lists

Create and manage lists of favorite servers:

# Create custom list
mullvad custom-list create "My Favorites"

# Add location to list
mullvad custom-list add "My Favorites" se got

# Remove location from list
mullvad custom-list remove "My Favorites" se got

# List all custom lists
mullvad custom-list list

# Delete custom list
mullvad custom-list delete "My Favorites"

# Select relay from custom list
mullvad relay set location "My Favorites"

Settings Management

Export Settings

# Export settings to file
mullvad export-settings settings.json

# Export to stdout
mullvad export-settings -

Import Settings

# Import settings from file
mullvad import-settings settings.json

# Import from stdin
cat settings.json | mullvad import-settings -

Reset Settings

# Reset all settings (stays logged in)
mullvad reset-settings

# Reset with confirmation prompt
mullvad reset-settings --assume-yes

# Factory reset (logout and clear everything)
mullvad factory-reset
mullvad factory-reset --assume-yes

Beta Program

Opt in/out of beta updates:

# Show beta program status
mullvad beta-program show

# Enable beta updates
mullvad beta-program on

# Disable beta updates
mullvad beta-program off

Logging

Manage logging and tracing:

# Show current log level
mullvad log show

# Set log level
mullvad log set-level error
mullvad log set-level warning
mullvad log set-level info
mullvad log set-level debug
mullvad log set-level trace

# Enable verbose logging (all modules)
mullvad log set-verbose on
mullvad log set-verbose off

# Set per-module log level
mullvad log set-module mullvad_daemon=trace
mullvad log unset-module mullvad_daemon

Debugging Commands

Debug commands are hidden and intended for internal testing. They may set the app in an invalid state.

# Show hidden debug commands
mullvad debug --help

Shell Completions

Generate shell completion scripts (Linux/macOS):

# Generate completions for bash
mullvad shell-completions bash .

# Generate completions for zsh
mullvad shell-completions zsh .

# Generate completions for fish
mullvad shell-completions fish .

Installing Completions

Bash

mullvad shell-completions bash /usr/share/bash-completion/completions/

Zsh

mullvad shell-completions zsh /usr/local/share/zsh/site-functions/

Fish

mullvad shell-completions fish ~/.config/fish/completions/

Scripting Examples

Auto-Connect on Specific Network

#!/bin/bash
# Connect to VPN when on public WiFi

SSID=$(iwgetid -r)

if [[ "$SSID" == "CoffeeShop" || "$SSID" == "Airport" ]]; then
    mullvad connect --wait
    echo "Connected to VPN on public network"
fi

Rotate Between Servers

#!/bin/bash
# Rotate to random server every hour

while true; do
    # Select random country
    COUNTRY=$(mullvad relay list countries | shuf -n1)
    
    # Connect to random server in that country
    mullvad relay set location "$COUNTRY"
    mullvad reconnect --wait
    
    echo "Connected to $COUNTRY"
    sleep 3600
done

Monitor Connection Status

#!/bin/bash
# Monitor and log connection status

while true; do
    STATUS=$(mullvad status)
    TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
    echo "[$TIMESTAMP] $STATUS" >> vpn-log.txt
    
    # Alert if disconnected
    if [[ "$STATUS" == *"Unsecured"* ]]; then
        notify-send "VPN Disconnected" "Warning: No VPN connection!"
    fi
    
    sleep 60
done

Connection Test Script

#!/bin/bash
# Test connection to different servers

for country in se de us; do
    echo "Testing $country..."
    mullvad relay set location "$country"
    mullvad reconnect --wait
    
    # Test speed (requires speedtest-cli)
    speedtest-cli --simple
    
    echo "---"
done

Output Formats

Many commands support JSON output for scripting:

# Get status as JSON
mullvad status --json

# Parse with jq
mullvad status --json | jq '.state'

# Extract IP address
mullvad status --json | jq -r '.ipv4'

Exit Codes

The CLI uses standard exit codes:

0 - Success
1 - General error
Other non-zero values indicate specific errors

Example Error Handling

if mullvad connect --wait; then
    echo "Successfully connected"
else
    echo "Failed to connect" >&2
    exit 1
fi

Environment Variables

The CLI respects standard terminal environment variables:

NO_COLOR - Disable colored output
MULLVAD_RPC_SOCKET_PATH - Override daemon socket path (advanced)

Troubleshooting

CLI Cannot Connect to Daemon

# Check if daemon is running
sudo systemctl status mullvad-daemon  # Linux
sc.exe query mullvadvpn  # Windows
sudo launchctl list | grep mullvad  # macOS

# Check socket path
ls -l /var/run/mullvad-vpn  # Linux/macOS

Command Not Found

# Check if CLI is in PATH
which mullvad

# Linux: Ensure installed
apt list --installed | grep mullvad

# macOS: Check installation
ls -l /usr/local/bin/mullvad

# Windows: Check PATH includes Program Files
echo %PATH%

Permissions Errors

The CLI communicates with the daemon via socket/pipe:

Linux: User must have access to /var/run/mullvad-vpn socket
macOS: Similar to Linux
Windows: All users should have access by default

To restrict access (Linux/macOS):

# Set via environment variable
export MULLVAD_MANAGEMENT_SOCKET_GROUP=vpnusers

Next Steps

Desktop Guide

Learn about the desktop application

Automation

Automate VPN with scripts

Settings Reference

Detailed settings documentation

Troubleshooting

Common CLI issues and solutions

Getting Started

Features

Platform Guides

Security & Privacy

Account & Devices

​Overview

​Binary Name

​Platform Availability

​Installation

​Desktop Platforms

​Verify Installation

​Basic Usage

​Connection Management

​Connect to VPN

​Disconnect from VPN

​Reconnect

​Check Status

​Account Management

​Login

​Account Information

​Logout

​Device Management

​Server Selection

​List Available Servers

​Set Server Location

​Server Constraints

​Tunnel Configuration

​WireGuard Settings

​Multihop

​DAITA

​Obfuscation

​Anti-Censorship Settings

​DNS Configuration

​DNS Settings

​Content Blocking Options

​Split Tunneling

​Application-Based Split Tunneling

​Security Settings

​Auto-Connect

​Lockdown Mode

​Local Network Sharing

​API Access Methods

​Custom Lists

​Settings Management

​Export Settings

​Import Settings

​Reset Settings

​Beta Program

​Logging

​Debugging Commands

​Shell Completions

​Installing Completions

​Bash

​Zsh

​Fish

​Scripting Examples

​Auto-Connect on Specific Network

​Rotate Between Servers

​Monitor Connection Status

​Connection Test Script

​Output Formats

​Exit Codes

​Example Error Handling

​Environment Variables

​Troubleshooting

​CLI Cannot Connect to Daemon

​Command Not Found

​Permissions Errors

​Next Steps

Desktop Guide

Automation

Settings Reference

Troubleshooting

Build docs developers (and LLMs) love

Overview

Binary Name

Platform Availability

Installation

Desktop Platforms

Verify Installation

Basic Usage

Connection Management

Connect to VPN

Disconnect from VPN

Reconnect

Check Status

Account Management

Login

Account Information

Logout

Device Management

Server Selection

List Available Servers

Set Server Location

Server Constraints

Tunnel Configuration

WireGuard Settings

Multihop

DAITA

Obfuscation

Anti-Censorship Settings

DNS Configuration

DNS Settings

Content Blocking Options

Split Tunneling

Application-Based Split Tunneling

Security Settings

Auto-Connect

Lockdown Mode

Local Network Sharing

API Access Methods

Custom Lists

Settings Management

Export Settings

Import Settings

Reset Settings

Beta Program

Logging

Debugging Commands

Shell Completions

Installing Completions

Bash

Zsh

Fish

Scripting Examples

Auto-Connect on Specific Network

Rotate Between Servers

Monitor Connection Status

Connection Test Script

Output Formats

Exit Codes

Example Error Handling

Environment Variables

Troubleshooting

CLI Cannot Connect to Daemon

Command Not Found

Permissions Errors

Next Steps