FreeGuard CLI 指令參考
FreeGuard CLI 提供一套完整的指令，可從終端機管理您的 VPN 連線、訂閱與設定。每個指令都支援 `--json` 輸出，方便用於腳本與 AI 代理整合。
FreeGuard CLI 指令參考
FreeGuard CLI 提供一套完整的指令，可從終端機管理您的 VPN 連線、訂閱與設定。每個指令都支援 --json 輸出，方便用於腳本與 AI 代理整合。
全域旗標
這些旗標可搭配任何指令使用：
| Flag | Description |
|---|---|
--json |
以 JSON 格式輸出（適合代理） |
--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
人類可讀輸出：
✓ 已連線到 United States - New York (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}
旗標：
| Flag | Description |
|---|---|
--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
旗標：
| Flag | Description |
|---|---|
--email <address> |
使用電子郵件驗證登入 |
--send-code |
將驗證碼寄送到電子郵件 |
--code <digits> |
提交 6 位數驗證碼 |
--account |
透過瀏覽器 OAuth 使用 FreeGuard 帳號登入 |
freeguard logout
清除已儲存的憑證，並在目前已連線時中斷連線。
freeguard logout
✓ 已登出。憑證已清除。
訂閱
freeguard subscribe list
檢視可用的訂閱方案與您目前的訂閱狀態。
freeguard subscribe list
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]
旗標：
| Flag | Description |
|---|---|
--plan <name> |
訂閱方案（basic, pro） |
--email <address> |
訂閱配送用電子郵件 |
設定
freeguard config get
讀取設定值。
freeguard config get proxy.port
7890
freeguard config get proxy.port --json
{"key": "proxy.port", "value": 7890}
freeguard config set
變更設定值。
freeguard config set proxy.port 8080
✓ proxy.port 已設為 8080
常見設定鍵：
| Key | Default | Description |
|---|---|---|
proxy.port |
7890 |
HTTP/SOCKS5 proxy 埠號 |
proxy.mode |
rule |
Proxy mode: rule, global, direct |
core.api_port |
9090 |
Mihomo API 埠號 |
core.pinned_version |
(empty) | 將 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: 已登入（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
旗標：
| Flag | Description |
|---|---|
--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 月