คลังความรู้

On Linux, macOS or Windows with no graphical app, use vilanet-cli. It is one static file. Sign in with your VilaVPN account. Do not import a subscription link. Full-device access is TUN.

1. Download the matching package

Use the releases page or cli.vilavpn.com. From mainland China, if GitHub does not open, use the mirror picker on cli.vilavpn.com. x86_64 from uname -m is AMD64; arm64 or aarch64 is ARM64.

• Linux: linux_amd64.tar.gz, linux_arm64.tar.gz, or linux_armv7.tar.gz.
• macOS: darwin_arm64.tar.gz (Apple silicon) or darwin_amd64.tar.gz (Intel).
• Windows: windows_amd64.zip or windows_arm64.zip.

2. Install

Linux. Extract the archive, then:

sudo install -m 0755 vilanet-cli /usr/local/bin/
sudo setcap 'cap_net_admin,cap_net_bind_service+eip' /usr/local/bin/vilanet-cli

macOS. Extract, then sudo install -m 0755 vilanet-cli /usr/local/bin/. Full-device TUN needs sudo. A local proxy does not.

Windows. Extract the ZIP. Download Wintun only from wintun.net and put wintun.dll beside vilanet-cli.exe. Open PowerShell as Administrator in that folder. Run it in the foreground the first time; you do not need a Windows service.

Then run vilanet-cli version (.\vilanet-cli.exe version on Windows). It should print a version, not an error.

3. Sign in and connect

Do not put the password in the command. login prompts for it.

vilanet-cli login --email [email protected]
vilanet-cli list packages
vilanet-cli list servers
vilanet-cli connect --country HK

Credentials are encrypted on this device. A headless server with no keyring uses an encrypted file, so sign-in also works over SSH. Do not add --insecure-store. You can add --country with your country code. On macOS, add sudo when TUN needs it. On Windows, stay in the elevated window. Leave the command running; Ctrl+C stops it. With no default package, connect uses the first package that still has traffic. Add --package for one connection. For the desktop app with a window, see which VilaNet app to use. See Linux if the desktop app fails on GLIBC.

Wrong package, or the traffic is used up

1. vilanet-cli list packages. If connect uses sudo, use sudo here too.
2. vilanet-cli settings set selected_package <id>
3. vilanet-cli connect --country HK, or add --package <id>.

login and connect must be the same user: both with sudo, or neither. Check the default with vilanet-cli settings get selected_package. See switch plan.

How to tell it is connected

• Foreground: keep the terminal open. An IP-check page should show a public IP different from your ISP. Do not use status for this run.
• Linux or macOS background: vilanet-cli status. egress_ip is the exit address. It can also appear when the health check cannot confirm the tunnel (running-unverified); this is common in China and does not mean the exit is unusable. If it is empty, run status again shortly.
• Windows foreground: disconnect, status and switch do not control it. Stop with Ctrl+C.

Disconnect

On Linux or macOS, vilanet-cli disconnect stops a background connection. vilanet-cli logout deletes stored credentials and cached account data; you do not need it merely to disconnect. Local proxy mode changes the system proxy only if you also pass --system-proxy, and disconnect restores the previous proxy. TUN does not need that flag.

Errors

• command not found: run it from the extracted folder.
• Exit 2: check email and password, then login.
• Exit 4: sign in first, or wait if requests were rate-limited.
• Exit 5: use the required administrator rights. On Linux, repeat setcap.
• no daemon active: run vilanet-cli connect. This is Linux/macOS background, not Windows foreground.
• Another daemon is running: use it, or disconnect first.
• Node ID not found: run list servers and use a current ID.
• Keyring unavailable (the OS keyring is unavailable on this build or Specified keyring backend not available): this is an older program. Replace the file from the releases page, then login. Do not put the password in the command.
• Windows Wintun: official wintun.dll must sit beside vilanet-cli.exe.
• Windows has no vilanet-cli update. Replace the program from a new ZIP on the releases page.

update needs GitHub, so it fails offline. Do not update first when you cannot connect. Replace the file from cli.vilavpn.com or the releases page and run vilanet-cli version.

Still not working?

Run vilanet-cli logs --follow, disconnect, and send a redacted excerpt. Do not post the configuration directory. Open a ticket if needed. Next: cannot connect. Docs: VilaNet CLI.