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.

PandaVPN CLI is better suited for automated testing, remote troubleshooting, and scripted connections.

Panda Desktop and PandaVPN CLI are two control interfaces for the same PandaVPN daemon and share the same connection state, so they can be used together.

Do not run legacy desktop apps, such as Panda-Qt or the old Linux AppImage, at the same time as PandaVPN CLI, as this may cause network configuration conflicts.

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.

Yes. The main difference is the architecture of the downloaded .pkg package.

The installation steps are the same. After installing with .pkg, LaunchDaemon / helper is usually installed and started automatically.

For global users, we recommend using mode auto by default:

panda login
panda node refresh
panda mode auto
panda connect
panda doctor

If a new installation already defaults to mode auto, you can use a simpler version:

panda login
panda node refresh
panda connect
panda doctor

Corresponding shorthand version:

panda login
panda no re
panda conn
panda do

The official download page and beginner onboarding should prioritize showing the full commands; shorthand should be shown later in advanced documentation or interactive mode explanations.

gfwlist is a specific source for split rules and is not suitable as the default mode for global users.

For global users, the recommended default is:

panda mode auto

Or use PandaVPN global mode consistently:

panda mode pandavpn global

gfwlist can remain in advanced split-routing documentation, but it is not recommended for the official website’s first screen, the download page Hero, or the beginner quick start.

It is recommended to disconnect first and turn off Kill-switch:

panda disconnect
panda kill-switch off

For a manual upgrade or Linux service upgrade, it is recommended to also stop the daemon:

sudo panda stop

When upgrading macOS and Windows with an installer, the installer usually handles service installation and restart automatically. After the upgrade is complete, run:

panda version
panda doctor
panda connect

After a manual Linux upgrade, run:

sudo panda service install
sudo panda service restart
panda version
panda doctor

panda connect us

This means a bare group selector. It does not pin the VIP / SVIP / FREE tab; the API selects the appropriate tab.

panda connect svip us

This means always using us under the SVIP tab.

The colon form is equivalent and suitable for scripts:

panda connect svip:us

The favorite tab is currently a flat favorite channel list and does not support favorite group smart connect such as connect fav us; for favorites, use:

panda connect fav

or:

panda connect --node <NODE_ID>

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.

View all nodes:

panda node list

Refresh and then view again:

panda node refresh
panda node list

Short form:

panda no re
panda no list

View a specific region or group:

panda node list us
panda node list jp
panda node list de

View node groups:

panda node group

View details for a specific group:

panda node group show us

Search for the node first:

panda node list us

Then connect:

panda connect --node 1822

You can also connect by name:

panda connect --node "US Node"

Shorthand:

panda no list us
panda conn --node 1822

panda connect uses the last target.
If there is no previous target, it attempts global smart connect.

Smart connect requires:

• you are logged in;
• the node directory is cached;
• when needed, run panda node refresh first.

Short form:

panda conn

Common reasons:

• you are not logged in yet;
• the node directory has not been refreshed;
• the current account has no available nodes;
• the network is unavailable;
• the daemon is not running;
• the current mode is incompatible with the target node;
• under mode auto, the recommended protocol failed to start and fallback also failed.

Recommended checks:

panda account
panda node refresh
panda node list
panda mode
panda doctor
panda log --lines 200

panda status

Structured output:

panda status --json

Shorthand:

panda stat

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

In a no-tunnel IPv6 scenario, awdl0 / llw0 may be blocked, causing AirDrop / Continuity to become temporarily unavailable.
It usually recovers after disconnect.

If it is still abnormal, recommended:

panda disconnect
panda kill-switch off
panda repair
panda doctor

Supported versions can configure this:

panda config tcp-fast-open auto
panda config tcp-fast-open on
panda config tcp-fast-open off

Notes:

• The recommended default is auto;
• Changing it will not trigger a hot reconnect;
• A reconnect is required for it to take effect on new TCP sockets;
• Nodes that do not support TFO should not show a noticeable connection latency regression.

If the current version does not have this config option, follow panda config --help or the actual CLI help.

Privacy mode can be understood as a stricter security mode, and is recommended to be equivalent to:

panda mode pandavpn global
panda kill-switch on

Or, under the default automatic protocol selection:

panda mode auto
panda kill-switch on

In Privacy mode, the following restrictions are recommended:

• Does not support proxy mode;
• Does not support split mode;
• Only allows VPN global semantics;
• Kill-switch must be enabled;
• Normal egress is blocked.

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.

In newer versions, Windows Kill-switch has been upgraded from a daemon-held dynamic session to persistent WFP filters.
This means the guard can remain in place after the daemon exits abnormally.

However, persistent WFP is not the same as a boot-time filter. The very early startup window is still part of future hardening scope.

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

Yes.

mode auto + kill-switch on is allowed, but the final path must resolve to PandaVPN / WireGuard and must not fall back to standalone proxy. During connection, if it falls back from WireGuard to PandaVPN, it must also keep guard active, and there must not be any fail-open window.

Recommended:

panda mode auto
panda kill-switch on
panda connect
panda doctor

Not recommended.

Kill-switch is an enhanced privacy protection option, and it is not suitable for the shortest usable path. Reasons:

• disconnect does not turn off Kill-switch;
• After it is enabled, normal networking may be blocked;
• It also involves LAN access, DNS lockdown, firewall, and platform permission differences;
• New users may mistakenly think the network is broken.

New users are recommended to complete this first:

panda login
panda node refresh
panda mode auto
panda connect
panda doctor

After confirming the connection works normally, enable it as needed:

panda kill-switch on
panda doctor

No.

This is expected behavior. Kill-switch is a persistent safety switch, and disconnect only disconnects the current runtime; it does not automatically turn off Kill-switch.

To restore normal network access, run:

panda kill-switch off

In strict mode, Kill-switch blocks normal LAN / WAN traffic.
Versions that support allow-lan can enable limited LAN access:

panda kill-switch allow-lan on

Turn off LAN allowlisting:

panda kill-switch allow-lan off

Note: allow-lan allows private network / link-local / ULA unicast and v1 discovery, but LAN DNS should still be blocked to avoid bypassing Panda DNS lockdown.