Agent-ready VPN CLI

A VPN CLI for AI agents that read state.

Free VPN CLI is documented for agent workflows through SKILL.md. Agents can inspect JSON output, check regions and service presets, connect, diagnose, and report state without scraping screenshots or guessing command behavior.

Download SKILL.md Read CLI docs
SKILL.md JSON output Exit codes Doctor
Works with Claude Cursor Codex OpenClaw Hermes+ any MCP tool
#1 Free VPN
App Store · Play Store · Mac
100M+
Installs worldwide
10+ yrs
Battle-tested VPN core
1,000+
Servers · global exits
Agent setup

Give the agent the skill before it touches VPN state.

The useful setup is not only installing the CLI. The agent needs instructions, parseable commands, and clear permission boundaries.

Agent-safe preflight

Have the agent check whether the CLI exists, read status, list regions only when needed, and use doctor output for evidence.

Paste in Terminal
$command -v freevpn >/dev/null 2>&1 && freevpn version --json
$freevpn status --json
$freevpn doctor --json
Agent operating rules
  • Prefer --json for every command the agent parses.
  • Ask before installing, changing service state, or switching regions.
  • Treat CLI status as authoritative over screenshots.
  • Run doctor --json before producing a troubleshooting summary.
Agent workflows

Where AI agents can use a VPN CLI safely.

The best agent workflow is bounded and inspectable: check state, act only when asked, verify, and report structured evidence.

State inspection

Check current VPN state before a network-sensitive task.

Region changes

List regions and set a requested location only when the task requires it.

Diagnostics

Run doctor output when network behavior looks wrong.

Project instructions

Add SKILL.md to the agent context so command names and safety notes are not guessed.

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
Agent workflow

Check, act, verify, report.

Agents should treat VPN work as an explicit sequence. Avoid hidden state changes and always verify with JSON output.

Paste in Terminal
$command -v freevpn >/dev/null 2>&1 && freevpn version --json
$freevpn status --json
$freevpn regions --json
$freevpn set-region "US East"
$freevpn up --json
$freevpn doctor --json
CommandWhy it matters
freevpn status --jsonRead current VPN state without scraping text.
freevpn regions --jsonFind available region labels or slugs before a requested switch.
freevpn set-region <slug|label>Persist a user-approved region choice.
freevpn up --jsonConnect and return parseable connection output.
freevpn doctor --jsonGather evidence before summarizing network issues.
Features

Agent-focused Free VPN CLI features.

Agents need predictable commands, parseable output, and diagnostics more than a visual app.

SKILL.md guidance

Works with Claude, Cursor, Codex, OpenClaw, Hermes, and any MCP tool, and documents command intent, JSON behavior, exit codes, install flow, GUI scope, and troubleshooting.

Every command accepts JSON

Use structured output for state, regions, connection changes, and diagnostics.

Exit-code decisions

Use documented outcomes for wait, retry, already-down, and license-required flows.

No GUI dependency

Agents should drive the CLI directly; the GUI is for humans.

Explicit region control

List, set, connect, verify, and report region changes.

Doctor reports

Structured diagnostics help agents explain DNS, route, controller, license, and egress issues.

Service presets

Use service presets without scraping the app UI.

SKILL.md documents freevpn services so agents can list service categories, inspect the current preset, or choose Off and General without reading screenshots. Non-default service presets are paid and return license_required for free users.

  • 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

Agent safety notes.

A VPN changes network state, so agent usage should be explicit, parseable, and reversible where possible.

  • Do not let agents scrape human terminal output.
  • Do not ask agents to hand-edit VPN configuration files.
  • Use status --json before and after connection changes.
  • Use doctor --json when a network task fails.
FAQ

VPN for AI agents FAQ.

What file should an AI agent read first?
Use SKILL.md. It is written for agents and documents commands, JSON output, exit codes, installation flow, GUI scope, and troubleshooting.
Should an agent parse normal terminal output?
No. Use --json for every command the agent needs to parse.
Can an agent switch VPN regions?
Yes, when the user asks for it. Use regions --json, set-region, up --json, and status verification.
What should an agent do when VPN state looks wrong?
Run freevpn doctor --json and summarize the structured diagnostics.
Does the agent need the desktop GUI?
No. Agents should use the CLI directly. The GUI is a human companion that talks to the same daemon.

Make Free VPN CLI agent-readable.

Download SKILL.md, add it to your agent workflow, and use JSON commands for every parseable VPN step.

Download SKILL.md Main CLI page