Agent-ready VPN CLI

A VPN CLI for AI agents that read state.

Free VPN CLI gives agents a documented command surface: SKILL.md for operating rules, JSON output for parsing, stable exit codes for decisions, region commands for explicit changes, and doctor reports for troubleshooting.

Download SKILL.md Read CLI docs

SKILL.md JSON output Exit codes Doctor

Works with

Claude

Cursor

Codex

OpenClaw

Hermes+ any MCP tool

agent workflow

$ freevpn status --json

$ freevpn regions --json

$ freevpn set-region "US East"

$ freevpn up --json

$ freevpn doctor --json

# agents should parse JSON, 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

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 && 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 && freevpn version --json

$freevpn status --json

$freevpn regions --json

$freevpn set-region "US East"

$freevpn up --json

$freevpn doctor --json

Command	Why it matters
`freevpn status --json`	Read current VPN state without scraping text.
`freevpn regions --json`	Find available region labels or slugs before a requested switch.
`freevpn set-region <slug\|label>`	Persist a user-approved region choice.
`freevpn up --json`	Connect and return parseable connection output.
`freevpn doctor --json`	Gather 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.

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