FreeGuard CLI Quick Start

FreeGuard CLI is a command-line VPN client that connects in one command. Install it on macOS, Linux, or Windows, login with your email, and run freeguard connect to secure your internet in under 5 minutes.

Installation

macOS and Linux

Install with a single command:

curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh

Or use Homebrew on macOS:

brew install freeguardvpn/tap/freeguard

After installation, verify it worked:

freeguard version

Expected output:

FreeGuard CLI v1.0.0
Core: mihomo v1.19.21
OS: darwin/arm64

Windows

Open PowerShell as Administrator and run:

irm https://downloadcli.freeguardvpn.com/cli/install.ps1 | iex

After installation, restart your terminal and run freeguard version to confirm.

Login

FreeGuard CLI uses email-based verification — no account registration required.

freeguard login --email [email protected] --send-code

You will receive a 6-digit verification code at your email. Enter it:

freeguard login --email [email protected] --code 123456

Example output:

✓ Logged in successfully!
✓ Found 1 active subscription (Pro Plan, expires 2026-12-01)
✓ Configuration generated: ~/.freeguard/profiles/default.yaml

If you have a FreeGuard account, you can also login via browser:

freeguard login --account

This opens your browser for OAuth authentication and returns a token automatically.

Connect

Connect to the fastest available server with one command:

freeguard connect

Example output:

✓ Connected to United States - New York (us-new-01)
  Protocol: anytls | Latency: 42ms
  Proxy: 127.0.0.1:7890 (HTTP/SOCKS5)

To connect to a specific country:

freeguard connect --country JP

To connect to a specific node:

freeguard connect jp-tok-01

Verify

Check that your connection is active:

freeguard status

Example output:

FreeGuard VPN Status
────────────────────
Status:     ● Connected
Node:       United States - New York (us-new-01)
Protocol:   anytls
Latency:    42ms
Upload:     1.2 MB/s
Download:   15.8 MB/s
Duration:   2h 15m
Mode:       System Proxy (HTTP/SOCKS5)

To get machine-readable output (useful for scripting or AI agents):

freeguard status --json

{
  "connected": true,
  "node": {"id": "us-new-01", "name": "United States - New York", "country": "US"},
  "protocol": "anytls",
  "latency_ms": 42,
  "traffic": {"upload_bps": 1258291, "download_bps": 16569754},
  "duration_seconds": 8100,
  "mode": "system_proxy",
  "proxy_port": {"mixed": 7890}
}

Next Steps

• CLI Commands Reference — Full list of all commands, flags, and output formats.
• CLI Troubleshooting — Solutions for common installation, login, and connection issues.
• FreeGuard CLI Agent — Let AI diagnose and fix issues for you automatically.
• Run freeguard --help to explore all available commands from your terminal.

Frequently Asked Questions

How do I install FreeGuard CLI on my system?

Run curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh on macOS or Linux. On macOS, you can also use brew install freeguard. The installer auto-detects your OS and architecture.

Can I use FreeGuard CLI without a GUI?

Yes. FreeGuard CLI is fully headless — it runs entirely in the terminal with no graphical interface required. This makes it ideal for servers, containers, and remote SSH sessions.

How do I switch VPN protocols with the CLI?

Use freeguard connect --protocol <name>. Supported protocols include Hysteria2, Anytls, and Trojan. The CLI defaults to the fastest available protocol for your network.

Does FreeGuard CLI work on ARM devices like Raspberry Pi?

Yes. The CLI supports arm64 and armv7 architectures. The install script auto-detects your platform and downloads the correct binary.

Last updated: March 2026