中文版本在下方 / Chinese version below
Using the Geph 5.8+ command-line client
Geph 5.8 ships a new command-line interface built around two binaries:
-
geph5-client— the VPN engine itself. You never run it directly. -
geph5— the command-line tool. It contains both the privileged manager (a background supervisor that owns the engine process) and all the user-facing commands, which talk to the manager over loopback.
Installation
Install both binaries from crates.io:
cargo install --locked geph5-client
cargo install --locked geph5
This puts the binaries in ~/.cargo/bin. One more step is required: the manager runs with elevated privileges (root on Linux/macOS, SYSTEM on Windows), and it looks for geph5-client next to the geph5 binary or on its PATH. A privileged process's PATH usually does not include ~/.cargo/bin, so copy both binaries somewhere system-wide:
# Linux / macOS:
sudo install -m755 ~/.cargo/bin/geph5 ~/.cargo/bin/geph5-client /usr/local/bin/
# Windows (Administrator PowerShell) — any directory on the system PATH works:
copy $env:USERPROFILE\.cargo\bin\geph5.exe C:\Windows\System32\
copy $env:USERPROFILE\.cargo\bin\geph5-client.exe C:\Windows\System32\
(Alternatively, set the GEPH_CLIENT_BIN environment variable to the engine's path — but installing into a system directory is simpler and more reliable.)
Registering the manager
The manager is a privileged background service that keeps your connection alive across logins and reboots. Register and start it with:
sudo geph5 register-manager
(On Windows, run geph5 register-manager in an Administrator terminal instead — no sudo.)
This creates and starts a background service — geph-manager.service (systemd) on Linux, io.geph.manager (launchd) on macOS, and the "Geph Manager" boot-time scheduled task on Windows — that runs geph5 manager and restarts it automatically on failure. To remove the service later:
sudo geph5 unregister-manager
Once the manager is running, all other commands run as your normal user — no sudo needed.
Logging in
Log in with your 24-digit account secret (from the Geph app or your records):
geph5 login <your-account-secret>
If you omit the secret, it is read from stdin (useful for scripts and password managers):
pass geph/secret | geph5 login
Check your account info anytime with geph5 account, and log out with geph5 logout.
Connecting and disconnecting
geph5 connect # bring the tunnel up
geph5 status # show connection status
geph5 disconnect # tear the tunnel down
geph5 reconnect # re-establish the tunnel with current settings, leak-free
Choosing an exit server
geph5 exits # list available exits
geph5 exit-constraint get # show the current exit constraint
geph5 exit-constraint set # pick automatically
geph5 exit-constraint set --country us # constrain by country
geph5 exit-constraint set --country us --city newark
Changing the exit while connected switches over without a leak window — no need to disconnect first.
Tuning how you connect
Each of these shows the current value when run without an argument, and sets it with on/off:
geph5 vpn on # full-tunnel VPN mode (default on fresh setups)
geph5 proxy on # local SOCKS5/HTTP proxy
geph5 auto-proxy on # auto-configure the system proxy while connected
geph5 lan-access off # whether private/LAN addresses bypass the tunnel
geph5 allow-direct on # allow direct (non-bridge) connections to exits:
# faster, but easier to block (default off)
By default, fresh setups use full-tunnel VPN mode with the local proxy off. VPN mode includes fail-closed leak protection: if the tunnel drops, traffic stops.
Troubleshooting
geph5 logs # show the last 20 log lines from the engine
geph5 logs -n 200 # show more
If geph5 connect fails with "could not spawn geph5-client", the manager cannot find the engine binary — revisit the installation section and make sure both binaries are in /usr/local/bin (or another directory on the system PATH).
迷雾通 5.8+ 命令行使用教程
迷雾通 5.8+ 提供了全新的命令行界面，由两个程序组成：
-
geph5-client—— VPN 核心引擎本身，用户无需直接运行。 -
geph5—— 命令行工具。它既包含需要 root 权限运行的管理器（manager，负责监管引擎进程的后台服务），也包含所有面向用户的命令（通过本地回环与管理器通信）。
安装
使用 cargo 从 crates.io 安装两个程序：
cargo install --locked geph5-client
cargo install --locked geph5
程序会被安装到 ~/.cargo/bin。还需要关键一步：管理器以特权身份运行（Linux/macOS 上为 root，Windows 上为 SYSTEM），它会在 geph5 所在目录或其 PATH 中寻找 geph5-client。特权进程的 PATH 通常不包含 ~/.cargo/bin，因此请把两个程序复制到系统级目录：
# Linux / macOS：
sudo install -m755 ~/.cargo/bin/geph5 ~/.cargo/bin/geph5-client /usr/local/bin/
# Windows（以管理员身份运行 PowerShell）——系统 PATH 中的任意目录均可：
copy $env:USERPROFILE\.cargo\bin\geph5.exe C:\Windows\System32\
copy $env:USERPROFILE\.cargo\bin\geph5-client.exe C:\Windows\System32\
（也可以设置 GEPH_CLIENT_BIN 环境变量指向引擎路径，但安装到系统目录更简单可靠。）
注册管理器
管理器是常驻后台的特权服务，保证连接在注销和重启后依然在线。注册并启动：
sudo geph5 register-manager
（在 Windows 上，改为在管理员终端中运行 geph5 register-manager，无需 sudo。）
这会创建并启动一个后台服务——Linux 上为 geph-manager.service（systemd），macOS 上为 io.geph.manager（launchd），Windows 上为「Geph Manager」开机计划任务——运行 geph5 manager 并在失败时自动重启。如需移除该服务：
sudo geph5 unregister-manager
管理器运行后，其余所有命令都以普通用户身份执行——无需 sudo。
登录
使用您的 24 位账户密钥登录（可在迷雾通应用中查看）：
geph5 login <账户密钥>
省略密钥时会从标准输入读取（便于配合脚本或密码管理器）：
pass geph/secret | geph5 login
随时可用 geph5 account 查看账户信息，geph5 logout 退出登录。
连接与断开
geph5 connect # 建立连接
geph5 status # 查看连接状态
geph5 disconnect # 断开连接
geph5 reconnect # 按当前设置无泄漏地重建连接
选择出口服务器
geph5 exits # 列出可用出口节点
geph5 exit-constraint get # 查看当前出口约束
geph5 exit-constraint set # 自动选择
geph5 exit-constraint set --country us # 按国家限定
geph5 exit-constraint set --country us --city newark
连接状态下更改出口会即时切换，全程无泄漏——无需先断开。
调整连接方式
以下命令不带参数时显示当前值，加 on/off 进行设置：
geph5 vpn on # 全局 VPN 模式（新装默认开启）
geph5 proxy on # 本地 SOCKS5/HTTP 代理
geph5 auto-proxy on # 连接时自动配置系统代理
geph5 lan-access off # 私有/局域网地址是否绕过隧道
geph5 allow-direct on # 允许直连出口服务器：
# 速度更快，但更容易被封锁（默认关闭）
新安装默认使用全局 VPN 模式，本地代理关闭。VPN 模式带 fail-closed 防泄漏保护：隧道断开时，流量立即停止。
故障排查
geph5 logs # 显示引擎最近 20 行日志
geph5 logs -n 200 # 显示更多
如果 geph5 connect 报错「could not spawn geph5-client」，说明管理器找不到引擎程序——请回顾安装一节，确认两个程序都已放入 /usr/local/bin（或系统 PATH 中的其他目录）。