frp-cli

AI 友好的 frp 一体化命令行 — 基于 fatedier/frp 二次开发。

frp-cli 把 frpc / frps 的常用操作收敛成一个 git 风格的命令树，覆盖 profile / tunnel / visitor / 模板 / 守护进程 / Admin API / 体检诊断等全部场景，所有读类命令支持 --json，原生贴合 AI Agent 调用。

仓库还自带了一份 Claude Code Skill，让 Claude 在被问到「内网穿透 / 反向代理 / 暴露本地服务 / SSH 跳板 / 公网访问 NAS」等场景时自动驱动本 CLI。

---

✨ 与原生 frp 的区别

维度	原生 frp	frp-cli
命令结构	frpc -c config.toml 一把梭	frp-cli <noun> <verb> git 风格树状
Profile	无（每次 -c 指定文件）	多 profile 隔离，profile use 切换
隧道增删	手改 TOML	tunnel add/update/remove，自动分片
进程管理	自己 nohup / systemd	跨平台 start/stop/restart/status/logs
模板	无	内置 ssh / web / rdp / mysql / minecraft 等
状态聚合	看 dashboard	status --json 一条命令出聚合视图
体检	无	doctor 一键检 5 项
AI 友好	无	全命令 --json、非 TTY 自动结构化、附 Skill

进程管理、Tunnel、Admin API 全部在进程内通过 client.NewService / server.NewService 调起，没有 fork frpc/frps 二进制，单文件分发即可。

---

📦 安装

方式 1：下载预编译二进制（推荐）

到 Releases 下载对应平台的包：

平台	文件
Windows x64	frp-cli-windows-amd64.zip
Linux x64	frp-cli-linux-amd64.tar.gz
Linux ARM64	frp-cli-linux-arm64.tar.gz
macOS Intel	frp-cli-darwin-amd64.tar.gz
macOS Apple Silicon	frp-cli-darwin-arm64.tar.gz

解压后把 frp-cli 放到 $PATH 任意目录即可（Windows 自行加 .exe 到 PATH）。

方式 2：从源码构建

git clone https://github.com/1848431227/frp-cli.git
cd frp-cli
go build -o frp-cli ./cmd/frp-cli/         # Linux/macOS
go build -o frp-cli.exe ./cmd/frp-cli/     # Windows

要求 Go 1.25+。国内可设 GOPROXY=https://goproxy.cn,direct。

---

🚀 5 分钟上手

场景 A — 已有 frps 服务器，想暴露本地 SSH

frp-cli init                                              # 初始化 ~/.frp-cli
frp-cli profile add home --role client \
    --server-addr frps.example.com --server-port 7000 \
    --token <your-token>
frp-cli profile use home
frp-cli template apply ssh --var remotePort=7022          # 生成 SSH 隧道
frp-cli client start                                      # 后台启动 frpc
frp-cli client status --json                              # 看状态

场景 B — 自建 frps（云服务器上）

frp-cli profile add my-frps --role server \
    --bind-port 7000 --dashboard-port 7500 --dashboard-user admin
frp-cli profile show my-frps --json     # 拿到自动生成的 token + dashboard 密码
frp-cli server start
frp-cli doctor --json                   # 5 项体检

场景 C — 已运行，热更新隧道（不重启）

frp-cli tunnel add web --type tcp --local-port 8080 --remote-port 7080
frp-cli client reload                   # 热加载，连接不中断

---

📋 命令速查

frp-cli init                              初始化 FRP_HOME（默认 ~/.frp-cli）
frp-cli version                           CLI + 内嵌 frp 版本

frp-cli profile add|list|show|use|rename|remove|export|import
frp-cli config  show|edit|validate
frp-cli tunnel  add|list|show|update|remove|enable|disable
frp-cli visitor add|list|show|update|remove|enable|disable     # stcp/xtcp 访问端
frp-cli template list|show|apply                                # ssh / web-http / rdp / mysql ...

frp-cli client  run|start|stop|restart|status|reload|logs       # 客户端守护进程
frp-cli server  run|start|stop|restart|status|logs              # 服务端守护进程
frp-cli server  clients|proxies|traffic                         # dashboard API 快捷方式

frp-cli api     get <path> | post <path> --data '{}'            # webServer 透传
frp-cli status  [--all] [--json]                                # 进程 + admin 聚合
frp-cli doctor  [--json]                                        # 体检
frp-cli completion bash|zsh|fish|powershell                     # shell 补全

全局 flags：--profile <name> --json --frp-home <path> -v -vv。

---

🤖 Claude Code Skill

仓库自带 .claude/skills/frp-cli/SKILL.md，clone 到本地后 Claude Code 会自动识别。

如果想全局生效（不依赖项目目录），把它复制到用户全局 skills 目录：

# Linux / macOS
mkdir -p ~/.claude/skills/frp-cli
cp .claude/skills/frp-cli/SKILL.md ~/.claude/skills/frp-cli/

# Windows (PowerShell)
mkdir $HOME\.claude\skills\frp-cli -Force
copy .claude\skills\frp-cli\SKILL.md $HOME\.claude\skills\frp-cli\

触发关键词：frp / frpc / frps / 内网穿透 / 反向代理 / 暴露本地服务 / SSH 跳板 / NAT 穿透 / 公网访问 NAS / webhook 调试 等。

Skill 内含：决策树、JSON 输出契约、5 个常见 recipe、故障排查流程、危险操作守门、escape hatch。

---

📁 目录约定

$FRP_HOME/                       # 默认 ~/.frp-cli，可用 --frp-home 或 FRP_HOME 覆盖
├── config.toml                  # CLI 自身配置（active profile 等）
├── profiles/
│   └── <profile>/
│       ├── config.toml          # frp 主配置
│       ├── tunnels/*.toml       # 每条隧道一个文件，主配置以 includes 聚合
│       ├── visitors/*.toml      # 同上
│       └── meta.toml            # CLI 元数据（角色、token 等）
├── run/<profile>.pid            # 守护进程 PID 文件
└── logs/<profile>.log           # 守护进程日志

---

🛠️ 从源码交叉编译多平台

make -j 5 frp-cli-cross    # 见 Makefile target；或手工：
for t in windows/amd64 linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do
    GOOS=${t%/*} GOARCH=${t#*/} go build -ldflags="-s -w" \
        -o dist/frp-cli-${t/\//-} ./cmd/frp-cli/
done

---

🙏 致谢与许可

本项目基于 fatedier/frp（Apache License 2.0）二次开发。原始 frp 项目提供了完整的反向代理 / 内网穿透实现，本仓库在其基础上新增了 cmd/frp-cli/ 与 internal/frpcli/ 包，组成一个 AI 友好的统一 CLI 包装层。

• 原项目 README 保留为 README-frp.md / README-frp_zh.md
• 见 NOTICE 了解归属信息
• 许可证：Apache License 2.0（与上游一致）

如果你觉得 frp-cli 有用，请同样去给上游 frp 点个 star ⭐：https://github.com/fatedier/frp。