# frp-cli

**Repository Path**: DYXZYT/frp-cli

## Basic Information

- **Project Name**: frp-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# frp-cli

> AI 友好的 frp 一体化命令行 — 基于 [fatedier/frp](https://github.com/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](https://github.com/1848431227/frp-cli/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：从源码构建

```bash
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

```bash
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（云服务器上）

```bash
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 — 已运行，热更新隧道（不重启）

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

---

## 📋 命令速查

```text
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`](./.claude/skills/frp-cli/SKILL.md)，clone 到本地后 Claude Code 会自动识别。

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

```bash
# 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           # 守护进程日志
```

---

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

```bash
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](https://github.com/fatedier/frp)（Apache License 2.0）二次开发。原始 frp 项目提供了完整的反向代理 / 内网穿透实现，本仓库在其基础上新增了 `cmd/frp-cli/` 与 `internal/frpcli/` 包，组成一个 AI 友好的统一 CLI 包装层。

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

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