Scriptable VPN CLI

A VPN CLI for automation scripts.

Free VPN CLI gives scripts a bounded VPN workflow: check install, read status as JSON, connect, run the task, capture diagnostics on failure, and disconnect when cleanup matters. Use exit codes and JSON instead of scraping terminal prose.

Install Free VPN CLI CLI overview

Scripts JSON Exit codes Cron

Works with

Claude

Cursor

Codex

OpenClaw

Hermes+ any MCP tool

script flow

$ freevpn up --json

$ freevpn status --json

$ freevpn doctor --json

$ freevpn down

# branch on exit codes, not terminal prose

#1 Free VPN

App Store · Play Store · Mac

100M+

Installs worldwide

10+ yrs

Battle-tested VPN core

1,000+

Servers · global exits

Automation setup

Start scripts with explicit checks.

Check that freevpn exists, then use version and status output before changing VPN state.

Script preflight

Use small predictable command sequences and parse JSON for decisions.

Paste in Terminal

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

$freevpn status --json

$freevpn up --json

Automation rules

Do not scrape human terminal output.
Use --json for anything your script reads.
Branch on documented exit codes.
Run doctor --json in failure traps, not on every happy path.

Automation use cases

Where scripts use VPN state.

Keep VPN automation explicit so retries, logs, and failures are understandable.

Cron jobs

Check status before recurring jobs that depend on network location.

Deploy checks

Verify VPN state around deployment or release tasks when needed.

Test automation

Connect to an expected region before a network-sensitive test suite.

Failure logs

Capture doctor output when automated networking fails.

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

user@shell $ freevpn status

VPN : disconnected

region : Fastest (auto)

your IP : 122.179.8.116

location : Bengaluru, India

user@shell $ freevpn up

Connected to Fastest (auto)

your IP : 85.195.125.198

location: Frankfurt, Germany

2 Switch region · verify · disconnect

freevpn set-region · status · down

user@shell $ freevpn set-region "US East"

Switched to US East

user@shell $ freevpn status

VPN : connected

region : US East

your IP : 23.108.55.113

location : Miami, United States

user@shell $ freevpn down

tunnel down · routes restored

Script workflow

Preflight, connect, verify, clean up.

Automation works best when VPN state is visible and each failure mode has a branch.

Paste in Terminal

$set -e

$freevpn up --json

$freevpn status --json | jq .

$freevpn doctor --json

$freevpn down

Command	Why it matters
`freevpn status --json`	Read current VPN state before changing anything.
`freevpn set-region "US East"` `freevpn up --json`	Connect to an explicit egress location.
`freevpn doctor --json`	Capture diagnostics in failure branches.
`freevpn down`	Clean up state when the workflow requires it.
`freevpn regions --json`	List available region choices for script configuration.

Features

Automation-focused CLI features.

Scripts need parseable output, stable commands, clear exit behavior, and diagnostics.

Every command accepts JSON

SKILL.md works with Claude, Cursor, Codex, OpenClaw, Hermes, and any MCP tool and says to prefer JSON for anything you will parse.

Stable exit codes

Use numeric outcomes for retry, wait, escalate, or ignore decisions.

Doctor for failure branches

Run doctor output when a network-dependent script fails.

Region parameters

Set a default region or pass a region for one run.

Shell-friendly

Works naturally in bash, cron, deploy scripts, and local test helpers.

Agent-compatible

The same JSON workflow is useful for AI coding agents.

Service presets

Choose service presets from the terminal when needed.

The CLI includes the same service preset surface as the desktop and mobile apps. Free users can list choices and use Off or General; non-default service presets are paid and return a license-required response.

freevpn services list shows supported service presets.
freevpn services categories groups presets such as Streaming, Sports, Social, AI, and Other where available.
freevpn services current prints the current preset name on one line.
freevpn services --json is the safest form for scripts and agents.

Paste in Terminal

$freevpn services list

$freevpn services categories

$freevpn services current

$freevpn services --json

Practical notes

Script handling notes.

Make automation robust by handling expected VPN outcomes intentionally.

Exit 8/free_break means wait and retry for free-tier timing, per SKILL.md.
Exit 7 can mean already down for freevpn down.
Do not scrape human text output.
Use doctor --json in failure traps.

FAQ

VPN for automation scripts FAQ.

Can I use Free VPN CLI in cron?

Yes, if the machine has the CLI and daemon installed and the environment has the needed permissions.

How should scripts parse status?

Use freevpn status --json and a JSON parser such as jq, Python, Node, or PowerShell.

What is free_break?

SKILL.md documents exit 8/free_break as a wait-and-retry case for free users.

Should scripts run doctor every time?

Usually no. Run doctor --json when a preflight or network step fails.

Can scripts switch regions?

Yes. Use freevpn set-region <slug|label>.

Automate VPN state without scraping text.

Install Free VPN CLI, use JSON output, and handle documented exit codes in your scripts.

Install Free VPN CLI Main CLI page