FreeGuard CLI 명령어 참조

FreeGuard CLI는 터미널에서 VPN 연결, 구독, 구성 관리를 위한 완전한 명령어 세트를 제공합니다. 모든 명령은 스크립팅 및 AI 에이전트 통합을 위한 --json 출력을 지원합니다.

전역 플래그

다음 플래그는 모든 명령에서 사용할 수 있습니다:

Flag	Description
`--json`	JSON 형식으로 출력 (에이전트 친화적)
`--quiet`, `-q`	무음 모드, 결과만 출력
`--verbose`, `-v`	디버그 정보를 포함한 자세한 출력
`--no-color`	컬러 출력 비활성화
`--lang <code>`	인터페이스 언어 (`auto`, `en`, `zh`, `ja`, etc.)
`--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

사람이 읽기 쉬운 출력:

✓ Connected to 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`, etc.)
`--tun`	시스템 전역 VPN을 위해 TUN Mode 사용 (상승된 권한 필요)

`freeguard disconnect`

현재 VPN 서버에서 연결을 끊습니다.

freeguard disconnect

✓ Disconnected

freeguard disconnect --json

{"status": "disconnected"}

`freeguard status`

현재 연결 상태와 트래픽 통계를 표시합니다.

freeguard status

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)

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

✓ Logged in successfully!
✓ Found 1 active subscription (Pro Plan, expires 2026-12-01)

계정 로그인(브라우저 열기):

freeguard login --account

플래그:

Flag	Description
`--email <address>`	이메일 인증으로 로그인
`--send-code`	이메일로 인증 코드 전송
`--code <digits>`	6자리 인증 코드 제출
`--account`	브라우저 OAuth를 통해 FreeGuard 계정으로 로그인

`freeguard logout`

저장된 자격 증명을 지우고, 현재 연결되어 있으면 연결을 끊습니다.

freeguard logout

✓ Logged out. Credentials cleared.

`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

freeguard config get proxy.port --json

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

`freeguard config set`

구성 값을 변경합니다.

freeguard config set proxy.port 8080

✓ proxy.port set to 8080

일반적인 구성 키:

Key	Default	Description
`proxy.port`	`7890`	HTTP/SOCKS5 proxy port
`proxy.mode`	`rule`	Proxy mode: `rule`, `global`, `direct`
`core.api_port`	`9090`	Mihomo API port
`core.pinned_version`	(empty)	Pin mihomo to a specific version
`dns.provider`	`auto`	DNS provider
`update.auto_check`	`true`	Check for updates on startup

`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

플래그:

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

마지막 업데이트: March 2026