PandaVPN CLI FAQs

Panda CLI is Panda’s command-line client and supports the following through the terminal:

• Login and account management
• Node refresh and node connection
• Switching between PandaVPN / Proxy / WireGuard / Auto modes
• System proxy configuration
• Split rules
• Split DNS configuration
• Kill-switch protection
• Auto-connect
• Logs and diagnostics

It is suitable for internal beta users, developers, advanced users, and testing scenarios that require scripted operations.

Panda CLI is operated through the command line and is better suited for:

• Automated testing
• Remote troubleshooting
• Scripted connections
• Viewing detailed diagnostic information
• Validating low-level behaviors such as Kill-switch, DNS, routing, and system proxy

The desktop client is better suited for everyday graphical operations by regular users.

Note: The legacy Qt desktop client and CLI are not recommended to manage VPN / system proxy at the same time, to avoid overwriting each other’s configuration.

Some capabilities require system-level permissions, such as:

• Creating TUN / WireGuard network interfaces
• Modifying DNS
• Setting the system proxy
• Applying the Kill-switch
• Repairing routes
• Managing the packet VPN runtime

Therefore, the CLI performs these operations through the platform-specific daemon / service.

Daemon forms on different platforms:

The key difference is: On Windows and macOS, the service is usually installed automatically through the installer, while on Linux users usually need to manually run sudo panda service install.

On Windows, you only need to run the following in an administrator PowerShell if you are not using the installer and are placing the binary manually:

panda service install windows

On macOS, this is only needed for development and debugging, when not using the .pkg installer, or when the daemon does not start automatically:

sudo panda start

On Linux, we recommend:

sudo panda service install
panda service status

Yes. The main difference is the architecture of the installation package you download.

The installation steps, commands, and service management method are the same. The installer will automatically elevate privileges and register the Windows Service.

Mainly supports:

Common settings:

panda mode auto
panda mode pandavpn global
panda mode proxy global
panda mode wireguard

openvpn is currently not recommended as a mainline mode in user documentation.

Recommendation:

Note: mode proxy and Kill-switch are mutually exclusive.

mode auto is the new default mode.

Its behavior is:

• API node / smart connect prioritizes the runtime based on meta.protocol;
• If WireGuard is recommended, it will try WireGuard first;
• If WireGuard metadata, address allocation, runtime startup, handshake, or connectivity probing fails, it falls back to PandaVPN global compiled from the SS payload;
• SS, OPENVPN, unknown, or missing protocols use PandaVPN global as the fallback;
• mode auto does not accept a policy parameter, and the resolved runtime is always global.

Recommended for new users:

panda mode auto
panda connect

direct-region is the recommended syntax; bypass-region / bypass are compatibility aliases.

For example:

panda mode pandavpn direct-region in

Equivalent to the compatibility alias:

panda mode pandavpn bypass-region in

The new version supports a more complete split profile syntax:

panda mode pandavpn split default direct proxy-region <cc>
panda mode pandavpn split default proxy direct-region <cc>

Common tokens:

Examples:

panda mode pandavpn split default direct proxy-region us custom-rules
panda mode pandavpn split default proxy direct-region in direct-lan custom-rules

Long commands are not recommended for beginner documentation. They are better suited for advanced split routing documentation.

doctor is a read-only diagnostic command used to view the current key status of Panda CLI.

panda doctor
panda doctor --json

Short form:

panda do

Focus on:

runtime
kill_switch
selected_node
vpn_dns
dns_lockdown
split_policy
system_proxy_state
vpn_routes
last_error

trace is used to see which rule, DNS action, and route a target will use.

panda trace example.com:443
panda trace 8.8.8.8:53 --json

Note: full trace capability requires an active PandaVPN packet runtime. Without a compatible runtime, only limited validation is available, or it falls back to legacy trace.

This usually happens because the official service / LaunchDaemon is installed, and you also manually ran:

sudo panda start

sudo panda start starts an unmanaged daemon, which may manage the following at the same time as the official daemon:

• VPN routes
• DNS
• TUN
• system proxy
• Kill-switch

The rule is: keep only one daemon.

Common handling on macOS / Linux:

panda disconnect
panda kill-switch off
sudo panda stop
panda repair
panda doctor

On Linux, if you use systemd service, restart the official service afterwards:

sudo panda service restart
panda doctor

On macOS, if installed with .pkg, usually let LaunchDaemon / helper manage the daemon, and do not use sudo panda start long-term as your daily startup method.

If you only want to disconnect the VPN, you do not need to exit the daemon:

panda disconnect
panda kill-switch off

If you really want to stop the daemon:

sudo panda stop

Confirm:

panda status

If it shows panda daemon unavailable, it means the main daemon has stopped.

Note: The LaunchDaemon / helper installed by the macOS .pkg may be managed by the system. Regular users are not advised to manually stop the service frequently.

panda log
panda log --lines 200
panda log --all

Clear logs:

panda log clear

Temporarily enable debug:

panda log level debug dns,tcp --ttl 10m

Restore default:

panda log level reset

panda repair is more comprehensive and may repair:

• VPN route
• DNS snapshot
• Kill-switch guard
• system proxy-related state

panda proxy repair mainly repairs system proxy drift for the current user.

panda repair
panda proxy repair

On a Fresh install, the default is proxy system-proxy on.
If the user explicitly saved off, that configuration is preserved.

View or set:

panda proxy system-proxy on
panda proxy system-proxy off
panda proxy system-proxy lock-on

Note: under mode auto, pandavpn, and wireguard, the VPN runtime ignores the persisted system proxy preference; the VPN companion proxy remains available and uses scoped egress.

Windows system proxy is the current user's HKCU WinINET setting and requires a per-user user-agent.
If you are in an SSH or non-interactive session, proxy repair may not always be able to start the user-agent automatically.

Recommended:

panda proxy status
panda proxy repair
panda doctor

If it still does not take effect, try again in a desktop login session.

Linux Phase 1 mainly supports GNOME gsettings.
Environments such as KDE / XFCE may show as unsupported.

This does not necessarily affect the PandaVPN packet runtime, but it may affect the system proxy mode experience.

The meaning of Kill-switch is to allow traffic only through TUN, while other normal traffic is blocked.

proxy mode is a standalone local proxy mode. It does not have packet VPN / TUN, nor does it provide equivalent DNS and routing protection. Therefore, Kill-switch does not support standalone proxy mode.

When you need Kill-switch, use:

panda mode auto
panda kill-switch on

Or:

panda mode pandavpn global
panda kill-switch on

Or:

panda mode wireguard
panda kill-switch on

No.

Auto-connect mainly covers best-effort connect when the daemon / service starts, plus pending retry when the network is temporarily unavailable at startup.

Enable:

panda config auto-connect on

Disable:

panda config auto-connect off

It is not a general runtime automatic reconnection mechanism.

Split rules are used to specify that certain domains, keywords, regex, or IPs go through proxy, direct, or block.

Rule files:

split/rules/proxy.txt
split/rules/direct.txt
split/rules/block.txt

Common commands:

panda split rules list
panda split rules add proxy suffix:github.com
panda split rules add direct ip-cidr:10.0.0.0/8
panda split rules add block keyword:adservice

Current known limitation: after login, pending auto-connect waiting for retry will not be woken automatically.

After login, manually run:

panda connect

Usually no. Split DNS configuration changes are hot-loaded.

Common commands:

panda split dns status
panda split dns local set 223.5.5.5 114.114.114.114
panda split dns policy tunnel-only
panda split dns fake-ip on

If the platform does not support certain local DNS sources, doctor will show a warning.