FreeGuard CLI 命令参考

FreeGuard CLI 提供了一整套命令，可从终端管理你的 VPN 连接、订阅和配置。每个命令都支持 --json 输出，便于脚本和 AI agent 集成。

全局标志

这些标志可用于任何命令：

标志	描述
`--json`	以 JSON 格式输出（适合 agent）
`--quiet`, `-q`	静默模式，仅输出结果
`--verbose`, `-v`	详细输出，包含调试信息
`--no-color`	禁用彩色输出
`--lang <code>`	界面语言（`auto`、`en`、`zh`、`ja` 等）
`--config <path>`	使用指定的配置文件

连接

`freeguard connect`

连接到 VPN 服务器。不带参数时，会自动选择可用的最快节点。

# 自动连接到最佳服务器
freeguard connect

# 按 ID 连接到指定节点
freeguard connect us-new-01

# 连接到某个国家中最佳的服务器
freeguard connect --country JP

# 使用指定协议
freeguard connect --protocol anytls

# 启用 TUN Mode（需要 sudo/admin）
freeguard connect --tun

人类可读输出：

✓ 已连接到美国 - 纽约 (us-new-01)
  Protocol: anytls | Latency: 42ms
  Proxy: 127.0.0.1:7890 (HTTP/SOCKS5)

JSON 输出：

freeguard connect --json

{"status": "connected", "node": "us-new-01", "protocol": "anytls", "latency_ms": 42}

标志：

标志	描述
`--country <code>`	连接到该国家的最佳节点（ISO 3166-1 alpha-2）
`--protocol <name>`	首选协议（`anytls`、`hysteria2`、`vless` 等）
`--tun`	使用 TUN Mode 进行系统级 VPN（需要提升权限）

`freeguard disconnect`

断开当前 VPN 服务器连接。

freeguard disconnect

✓ 已断开连接

freeguard disconnect --json

{"status": "disconnected"}

`freeguard status`

显示当前连接状态和流量统计。

freeguard status

FreeGuard VPN Status
────────────────────
Status:     ● 已连接
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)

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}
}

身份验证

`freeguard login`

使用 FreeGuard 进行身份验证。支持邮箱验证（无需账户）或 FreeGuard 账户登录。

邮箱登录（推荐）：

# 步骤 1：请求验证码
freeguard login --email [email protected] --send-code

# 步骤 2：输入验证码
freeguard login --email [email protected] --code 123456

✓ 登录成功！
✓ 找到 1 个有效订阅（Pro Plan，2026-12-01 到期）

账户登录（打开浏览器）：

freeguard login --account

标志：

标志	描述
`--email <address>`	使用邮箱验证登录
`--send-code`	向邮箱发送验证码
`--code <digits>`	提交 6 位验证码
`--account`	通过浏览器 OAuth 使用 FreeGuard 账户登录

`freeguard logout`

清除已存储的凭据，并在当前已连接时断开连接。

freeguard logout

✓ 已退出登录。凭据已清除。

Your Subscription
─────────────────
Plan:       Pro
Status:     Active
Expires:    2026-12-01
Traffic:    450 GB / Unlimited

Available Plans
───────────────
Plan        Monthly   Quarterly   Annual
Basic       $4.99     $12.99      $39.99
Pro         $9.99     $24.99      $79.99

freeguard subscribe list --json

{
  "current": {"plan": "pro", "status": "active", "expires": "2026-12-01"},
  "plans": [
    {"name": "basic", "prices": {"monthly": 4.99, "quarterly": 12.99, "annual": 39.99}},
    {"name": "pro", "prices": {"monthly": 9.99, "quarterly": 24.99, "annual": 79.99}}
  ]
}

`freeguard subscribe create`

创建新订阅。会打开浏览器，通过 Stripe 或加密货币完成支付。

# 交互式选择方案
freeguard subscribe create

# 直接指定方案
freeguard subscribe create --plan pro --email [email protected]

标志：

标志	描述
`--plan <name>`	订阅方案（`basic`、`pro`）
`--email <address>`	用于接收订阅信息的邮箱

配置

`freeguard config get`

读取配置值。

freeguard config get proxy.port

freeguard config get proxy.port --json

{"key": "proxy.port", "value": 7890}

`freeguard config set`

更改配置值。

freeguard config set proxy.port 8080

✓ proxy.port 已设置为 8080

常见配置键：

键	默认值	描述
`proxy.port`	`7890`	HTTP/SOCKS5 Proxy 端口
`proxy.mode`	`rule`	Proxy 模式：`rule`、`global`、`direct`
`core.api_port`	`9090`	Mihomo API 端口
`core.pinned_version`	(空)	将 mihomo 固定到特定版本
`dns.provider`	`auto`	DNS 提供商
`update.auto_check`	`true`	启动时检查更新

`freeguard config edit`

在默认编辑器中打开配置文件。

freeguard config edit

诊断

`freeguard doctor`

运行全面的环境检查来诊断问题。

freeguard doctor

FreeGuard Environment Check
───────────────────────────
✓ OS:              macOS 15.2 (arm64)
✓ CLI version:     v1.0.0
✓ Core version:    mihomo v1.19.21
✓ Config dir:      ~/.freeguard/
✓ Credentials:     Logged in (email: u***@example.com)
✓ Subscription:    Active (expires 2026-12-01)
✓ Network:         Internet reachable
✓ DNS:             Working (8.8.8.8)
✗ TUN permission:  Not available (run with sudo for TUN mode)
✓ Port 7890:       Available
✓ GeoIP database:  Up to date (2026-03-15)

Result: 10/11 checks passed. TUN mode requires elevated privileges.

freeguard doctor --json

{
  "checks": [
    {"name": "os", "status": "pass", "detail": "macOS 15.2 (arm64)"},
    {"name": "cli_version", "status": "pass", "detail": "v1.0.0"},
    {"name": "tun_permission", "status": "fail", "detail": "Not available (run with sudo)"}
  ],
  "passed": 10,
  "total": 11
}

`freeguard version`

显示 CLI 和核心引擎的版本信息。

freeguard version

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

freeguard version --json

{"cli": "1.0.0", "core": "1.19.21", "os": "darwin", "arch": "arm64"}

高级功能（Phase 2+）

以下命令计划在未来版本中提供。

`freeguard node list`

列出可用 VPN 节点，并支持筛选和排序。

freeguard node list
freeguard node list --country US --sort latency

标志：

标志	描述
`--country <code>`	按国家代码筛选
`--protocol <name>`	按协议筛选
`--sort <field>`	按 `speed`、`latency` 或 `load` 排序

`freeguard node test`

测试节点的延迟和速度。

freeguard node test us-new-01
freeguard node test --all

`freeguard monitor`

在终端中显示实时流量监控。

freeguard monitor

↑ 0.8 MB/s  ↓ 12.3 MB/s  Connections: 47

`freeguard core`

管理底层的 mihomo 引擎。

# Check core status
freeguard core status

# Update to latest core version
freeguard core update

# Restart the core engine
freeguard core restart

`freeguard shell`

进入交互式 REPL 模式，在一个会话中运行多个命令。

freeguard shell

`freeguard dashboard`

打开带有实时流量图、节点列表和连接详情的 TUI 仪表盘。

freeguard dashboard

最后更新：2026 年 3 月