headless VPN CLI

A VPN CLI for headless terminals.

Free VPN CLI works from the command line, so server and SSH workflows can check status, connect, switch regions, and diagnose issues without a desktop window.

Install Free VPN CLI CLI overview

Headless SSH JSON output Doctor

headless shell

$ command -v freevpn >/dev/null 2>&1 && freevpn version --json

$ freevpn status --json

$ freevpn up --json

$ freevpn doctor --json

verify before relying on a tunnel

#1 Free VPN

App Store · Play Store · Mac

100M+

Installs worldwide

10+ yrs

Battle-tested VPN core

1,000+

Servers · global exits

Headless setup

Check the CLI before changing network state.

For headless work, start with an explicit binary check and status read. Install from the downloads page or documented shell installer when needed.

Headless preflight

Confirm the CLI exists, read current state, then connect when the environment allows VPN tunnels.

Paste in Terminal

$command -v freevpn >/dev/null 2>&1 && freevpn version --json

$freevpn status --json

$freevpn up --json

Support notes

Use headless VPN only in environments where VPN tunnel and route changes are allowed.
Be careful over SSH: verify access and expected routing before relying on the tunnel.
Use freevpn doctor --json for route, DNS, controller, license, and egress evidence.
No desktop app is required for headless use.

Runs where your work already lives

A VPN command surface for servers and SSH sessions.

Keep VPN work inside the shell where your server, scripts, and diagnostics already run.

SSH terminals

Run status, up, down, doctor, and region commands without a GUI.

Servers and VMs

Use the CLI where the host allows VPN service and tunnel permissions.

Scripts

Parse --json output for automation and monitoring.

Diagnostics

Use doctor output when DNS, routes, or egress behavior is unclear.

Two lines and you're connected

Check state, then connect.

Headless sessions should verify the CLI and current VPN state before bringing the tunnel up.

Paste in Terminal

$command -v freevpn >/dev/null 2>&1 && freevpn version --json

$freevpn up --json

If the host blocks tunnel permissions, use freevpn doctor --json for evidence.

How it works

up. status. down.

Three verbs cover most day-to-day VPN work. set-region and doctor cover region selection and troubleshooting.

1 Check where you are · connect

freevpn status · up

$ freevpn status

$ freevpn up

connected · verify with freevpn status

2 Switch region · verify · disconnect

freevpn set-region · status · down

$ freevpn set-region "US East"

$ freevpn status

$ freevpn down

tunnel down · routes restored

Headless workflow

Preflight, connect, verify, diagnose.

Headless VPN work should be explicit. Check install, read status, connect, verify again, and use doctor output on failure.

Paste in Terminal

$command -v freevpn >/dev/null 2>&1 && freevpn version --json

$freevpn status --json

$freevpn up --json

$freevpn status --json

$freevpn doctor --json

Command	Why it matters
`command -v freevpn >/dev/null 2>&1 && freevpn version --json`	Verify the CLI exists before a script changes VPN state.
`freevpn status --json`	Read current VPN state in a machine-friendly format.
`freevpn up --json`	Connect and return structured output.
`freevpn down`	Restore state when the workflow requires cleanup.
`freevpn doctor --json`	Collect troubleshooting evidence on headless hosts.

Features

Headless-relevant CLI features.

The CLI is useful where a desktop window is unavailable or inappropriate.

No GUI required

Every core workflow is available through terminal commands.

JSON output

Use --json for scripts, logs, agents, and monitors.

Service-aware flow

The installer registers the daemon during setup on supported systems.

Region control

Set explicit exits for test or troubleshooting sessions.

Ad Block

Use VPN-layer blocking while the tunnel is connected.

Doctor diagnostics

Capture route, DNS, controller, license, and egress checks.

Ad Block

Use Ad Block in headless network flows.

When the VPN is connected, Ad Block can help scripts, terminals, and server-side tools avoid known ad, analytics, and tracker domains.

Blocks known ad, analytics, and tracker domains across the device.
Works at the VPN layer, so it helps outside the browser too.
Use stats to inspect what was blocked during the current VPN session.

adblock · Free VPN CLI

$ freevpn adblock on

$ freevpn adblock update

$ freevpn adblock stats

stats are useful when checking a session

Optional desktop app

The CLI stays primary; the desktop app is optional.

These workflows are terminal-first. On a desktop machine, you can add the optional companion window for human status checks while keeping scripts and agents on CLI commands.

Paste in Terminal

$freevpn gui install

$freevpn gui open

$freevpn gui uninstall

Agent Skill

Give VPN commands to coding agents.

SKILL.md documents Free VPN CLI commands, JSON output, exit handling, and troubleshooting flows so agents can use terminal commands without guessing from screenshots.

Download SKILL.md CLI overview

Works with

Claude

Cursor

Codex

OpenClaw

Hermes+ any MCP tool

agent · SKILL.md

$ freevpn status --json

$ freevpn regions --json

$ freevpn doctor --json

structured output for agents, scripts, and CI checks

Built for

Headless workflows that need VPN state.

Use Free VPN CLI when SSH sessions, scripts, or servers need command-line VPN control.

Self-managed servers

Use only where tunnel permissions are allowed.

SSH sessions

Keep status and diagnostics in terminal output.

Automation

Use JSON output and explicit cleanup.

Agents

Give SKILL.md to coding agents for safer command usage.

Pricing

Free forever. Upgrade only if you want it.

Free VPN CLI is genuinely free to use: no signup, no email, no credit card. Use it for terminal, scripts, and developer workflows. The paid option removes the continuous connection limit for people who want the VPN running all day. Cancel any time. Prices in USD.

Always free

Free plan — $0 forever

No signup. No card. No expiry. Use it as much as you want.

30-min sessions with a 3-min break in between, on repeat, forever.
Same servers, regions and Ad Block as the paid plan.

Install free

free plan · status

$ freevpn up

30-min session, then 3-min break, then back online on repeat

Need the VPN running non-stop?

The paid plans below remove the 30-min session limit. Nothing else changes.

Weekly

$7.99/wk

Unlimited time, billed weekly. Cancel in one click from the billing portal.

Get unlimited

Annual

$99/yr

Unlimited time. Save ~58% vs. monthly: one charge a year, nothing else to think about.

Get unlimited

Monthly

$21.99/mo

Unlimited time, billed monthly. Swap plans any time from freevpn manage.

Get unlimited

Payments handled by Stripe Cancel anytime No email required for billing

Practical notes

Headless notes.

Avoid broad promises on hosts you do not control.

Best suited to machines where service install and VPN tunnel permissions are allowed.
Be careful with SSH routing and verify status after connecting.
Use freevpn doctor --json instead of guessing when a tunnel fails.
Use freevpn down when your workflow requires cleanup.

FAQ

Headless VPN CLI FAQ.

Does a headless VPN CLI need a desktop app?

No. Free VPN CLI can connect, disconnect, check status, switch regions, and diagnose from the terminal.

Can I use it over SSH?

Yes, on hosts where VPN tunnel and route changes are allowed. Be careful to avoid disrupting your SSH access.

What command checks whether it is installed?

Use command -v freevpn >/dev/null 2>&1 && freevpn version --json.

How do I troubleshoot a headless VPN failure?

Run freevpn doctor --json and inspect the structured diagnostics.

Is this intended for locked-down containers?

Only if the environment allows the required VPN/tunnel permissions. Some containers and hosted systems block that.

Run Free VPN CLI without a desktop window.

Check state, connect, verify, and diagnose from the terminal.

Install Free VPN CLI Main CLI page