CI VPN CLI

A careful VPN CLI for GitHub Actions workflows.

Free VPN CLI can support CI-style network checks when the runner environment permits VPN services and tunnel creation. Treat it as a self-hosted or controlled-runner workflow, not a blanket promise for GitHub-hosted runners.

Read CLI setup Downloads

Actions Self-hosted JSON logs Permission-aware

self-hosted runner

$ freevpn status --json

$ freevpn up --json

$ freevpn doctor --json

$ freevpn down

# use only where VPN service permissions are allowed

#1 Free VPN

App Store · Play Store · Mac

100M+

Installs worldwide

10+ yrs

Battle-tested VPN core

1,000+

Servers · global exits

CI setup

Use only where the runner permits VPN services.

GitHub-hosted runner compatibility is not promised here. Use Free VPN CLI on self-hosted runners or environments where installing services and creating VPN tunnels is allowed.

Prepared runner flow

Install and permit the VPN service in a controlled runner environment, then use status and doctor output around network-sensitive jobs.

Paste in Terminal

$freevpn status --json

$freevpn up --json

$freevpn doctor --json

Runner caveats

Best fit: self-hosted runners or controlled CI machines.
VPN service setup may be blocked by runner permissions.
Avoid storing sensitive diagnostics in public logs without review.
Treat daemon or tunnel failures as environment setup failures.

CI use cases

Where VPN CLI usage makes sense in CI.

Keep CI usage permission-aware and transparent. The runner must allow the network behavior you need.

Self-hosted runners

Use a runner you control when tests require VPN egress.

Network-sensitive tests

Capture status before tests that depend on region or egress.

Failure artifacts

Save doctor output when a job fails due to networking.

Controlled environments

Avoid hidden VPN changes in shared or restricted CI contexts.

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

CI workflow

Preflight, run, diagnose.

Prepare the runner outside the job or in a controlled setup step. During the job, capture status before network-sensitive steps and doctor output only when needed.

Paste in Terminal

$freevpn status --json

$freevpn set-region "US East"

$freevpn up --json

$freevpn status --json

$freevpn doctor --json

Command	Why it matters
`freevpn status --json`	Log current VPN state before the sensitive step.
`freevpn set-region "US East"` `freevpn up --json`	Connect to an explicit region when the runner permits it.
`freevpn doctor --json`	Collect diagnostics when a network-dependent job fails.
`freevpn down`	Clean up runner VPN state when your workflow requires it.

Features

CI-relevant CLI features.

CI needs headless operation, parseable output, and failure evidence more than visual controls.

Headless operation

The CLI does not require a desktop window for status, connection, or diagnostics.

Machine-readable output

Use --json for workflow logs and artifacts.

Doctor command

Capture DNS, route, controller, license, and egress diagnostics when a network step fails.

Region pinning

Use a documented region slug or label and verify status.

Permission-aware setup

Runner network permissions decide whether VPN setup can work.

Auditable logs

Make VPN state visible in job logs where appropriate.

Service presets

Choose service presets from the terminal when needed.

On permitted self-hosted runners, services output can be logged as JSON before network-sensitive checks. Keep paid preset handling explicit and do not assume hosted CI allows VPN tunnels.

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

GitHub Actions caveats.

VPN use in CI should be explicit and environment-aware.

Best fit: self-hosted runners.
Do not overpromise GitHub-hosted runner support; permissions may block VPN service setup.
Use status --json before tests and doctor --json on failure.
Review diagnostics before storing them in public logs.

FAQ

VPN for GitHub Actions FAQ.

Does this work on GitHub-hosted runners?

This page does not promise GitHub-hosted runner compatibility. VPN permissions and service installation can be restricted.

What runner type is best?

Self-hosted runners or controlled CI machines where VPN and network permissions are allowed.

What should a workflow log?

Log freevpn status --json before the sensitive step and doctor --json only when troubleshooting.

Can I pin a region in CI?

Yes, use a documented region slug or label with freevpn set-region, then verify status.

What if the daemon is unavailable?

Treat it as an environment/setup failure and run doctor where possible.

Use Free VPN CLI carefully in CI.

Start with a self-hosted or controlled runner, then use JSON status and doctor output around network-sensitive jobs.

Read CLI setup Main CLI page