内容
# freebox-cli
全面掌控您的 **Freebox Ultra** （Freebox 操作系统）从终端：一个 **交互式应用程序**，只需输入 `fbx` 即可打开，一个完整的 **可脚本化 CLI**，以及一个 **MCP 服务器**，让 AI 代理控制您的 Freebox - 连接、局域网、DHCP、端口转发、Wi-Fi、下载、文件、电话和 **虚拟机管理器**（未公开的 API）。
**非官方。** 本项目与 Free 或 Iliad 集团无关。
*(英文摘要 [如下](#english)。)*
## 安装
使用 [Homebrew](https://brew.sh)，或从 [PyPI](https://pypi.org/project/freebox-cli/) 使用 [`uv`](https://astral.sh/uv) / `pipx` 在与 Freebox 相同的网络中的一台机器上：
```sh
brew install kevingallaccio/tap/freebox-cli
# 或
uv tool install freebox-cli # 或：pipx install freebox-cli
```
软件包名为 `freebox-cli`；命令名为 **`fbx`** - 三个字母，就像 Freebox一样。无需安装任何软件：`uvx --from freebox-cli fbx system info`。
## 应用程序
输入 `fbx`，您就进入了：一个 Freebox 控制面板 - 直接显示 WAN 速度、Wi-Fi 信息、设备、虚拟机、存储、下载、电话 - 以及 **建议**，指出需要关注的内容（WPS 仍然启用、已完成的下载需要清理、虚拟机停止运行、设备无名称...）。在每个部分导航、执行操作、退出时输入 `q`。所有破坏性操作都需要确认。
在应用程序中：实时 `top` 视图（速度曲线、温度、Wi-Fi 信号强度）、**文件 Shell** 在终端（`/Freebox > ls`、`cd`、`mkdir`、`mv`、`cp`、`rm`、`share`）和一个完整的虚拟机屏幕，附带 **串行控制台**（Ctrl-] 退出，您将返回应用程序）。
应用程序是同一个核心的三个界面之一 - 下面的 CLI 和 MCP 服务器在字节级别上保持可脚本化；`fbx` 不带参数仅在真正的终端上打开应用程序（在管道中，它像以前一样显示帮助）。
## 快速入门
在您的机器上授权此应用程序 - 需要一步物理操作：
```sh
fbx auth login
```
`fbx` 在您的 Freebox 上注册，然后要求您按 ▶（右箭头）在 Freebox 显示屏上。令牌存储在 `~/.config/fbx/credentials.json`（模式 0600）中；会话随后会自动续期。
```sh
fbx auth status # 我们是否被授权， 在哪台 Freebox 上？
fbx auth permissions # 此应用程序可以执行什么操作？
fbx system info # 固件、型号、运行时间、温度、风扇
```
## 读取 Freebox
每个领域都有其自己的命令，带有 Rich 表格（和 `--json` 用于脚本）：
```sh
fbx connection status # WAN 状态、地址、实时速度
fbx connection ftth # 光纤连接 + SFP 功率（光纤健康状况）
fbx connection ipv6 # 委托前缀
fbx connection logs # WAN 历史记录
fbx lan devices # 网络上的设备（--all 获取历史记录）
fbx lan interfaces # 可导航接口（pub、wifiguest 等）
fbx dhcp leases # 活动租约
fbx dhcp static # 静态预留
fbx fw redirs # 端口转发规则
fbx fw dmz # DMZ 主机
fbx fw incoming # 集成服务的入站端口
fbx fw upnp # UPnP IGD 状态（+ upnp-redirs 获取映射）
fbx wifi status # Wi-Fi 信息（2.4/5/5/6 GHz 在 Ultra 上）
fbx wifi ap # 每个无线电的频道/带宽/状态
fbx wifi bss # SSID + 安全（密钥仅通过 --json）
fbx wifi stations # 连接的客户端、信号、速度
fbx wifi mac-filter # MAC 地址过滤列表
fbx wifi neighbors 10 # 通道扫描：AP 10 监听的内容（--scan）
fbx wifi key # 显示 Wi-Fi 密钥（通过 pbcopy 传输）
fbx downloads list # 下载任务
fbx downloads stats # 管理器计数器
fbx storage disks # 物理磁盘
fbx storage partitions # 空间占用
fbx fs ls /Freebox # 浏览 Freebox 上的文件
fbx calls list # 固定电话呼叫日志
fbx contacts list # 通讯录
```
## 控制 Freebox
每个领域也有其自己的写入命令。写入操作在 stderr 上显示可读确认，在 stdout 上显示 Freebox 的响应对象（兼容 `--json`）；确实不可逆的操作需要确认，可以使用 `--yes` 跳过：
```sh
# DHCP 预留 + Wake-on-LAN
fbx dhcp static-add 02:00:00:00:00:99 192.168.1.222 -c "打印机"
fbx dhcp static-rm 02:00:00:00:00:99
fbx wol 02:00:00:00:00:0a
# 端口转发 / DMZ / UPnP
fbx fw redir-add 192.168.1.42 8080 --wan-port 8080 --comment web
fbx fw redir-rm 3
fbx fw dmz-set 192.168.1.50 # ... 或 dmz-off
fbx fw upnp-set --disabled
# Wi-Fi（全局关闭 Wi-Fi 需要先确认 - 您可能正在使用它）
fbx wifi bss-set 02:00:00:00:00:10 --ssid "房屋" --key "s3cret..."
fbx wifi mac-filter-add 02:00:00:00:00:99 --type blacklist
fbx wifi ap-set 10 --no-he --no-eht # 关闭 Wi-Fi 6/7（旧 IoT 设备）
fbx wifi config-set --disabled # 需要确认，除非 --yes
# 下载
fbx downloads add "magnet:?xt=urn:btih:..."
fbx downloads pause 3 && fbx downloads resume 3
fbx downloads erase 3 # 删除文件 → 需要确认
# 文件（mv/cp/rm 是跟踪完成的任务）
fbx fs mkdir /Freebox/下载 新建
fbx fs cp /Freebox/a --to /Freebox/b
fbx fs rm /Freebox/旧 --yes
fbx fs share /Freebox/电影.mkv --days 7
# 局域网 / 连接 / 系统 / 通讯录
fbx lan rename ether-02:00:00:00:00:0a "客厅电视"
fbx connection config-set --no-ping
fbx system reboot # 需要确认，除非 --yes
fbx contacts add "Sandy Kilo" --first Sandy --last Kilo
```
## 虚拟机
Freebox Ultra 配备了一个 aarch64 超级管理程序。`fbx vm` 管理整个生命周期 - 包括 **WebSocket 串行控制台**，就像 `virsh console` 一样，可以附加到 guest 的 tty：
```sh
fbx vm list # 每个虚拟机 + 状态、vCPU、RAM
fbx vm info # 超级管理程序容量
fbx vm distros # Free 的云镜像目录
# 创建磁盘，然后创建虚拟机并启动它
fbx vm disk-create /Freebox/VMs/web.qcow2 8G
fbx vm create --name web --disk /Freebox/VMs/web.qcow2 \
--memory 512 --vcpus 1 --cloudinit-file cloud-init.yaml
fbx vm start 2
fbx vm console 2 # 串行控制台（Ctrl-] 退出）
fbx vm shutdown 2 # 干净的 ACPI 关机
fbx vm stop 2 # 强制停止（需要确认）
fbx vm rm 2 # 删除定义（需要确认）
# 在串行控制台上执行命令（需要在 guest shell 上）
fbx vm exec 2 "uptime"
fbx vm userdata 2 # 原始 cloud-init 数据
```
串行控制台使用包含的 `websockets` 依赖项；`--disk`/`--cd` 路径是绝对的 (`/Freebox/...`)，`cloudinit_userdata`（包含 SSH 密钥和密码）仅通过 `--json` 显示，从不显示在表格中。
## MCP 服务器 - 让一个代理控制 Freebox
`fbx mcp serve` 在 stdio 上公开整个 API（109 种工具，分成 13 个集合：system、connection、lan、dhcp、fw、wifi、downloads、files、calls、contacts、storage、vm、raw）和一个 **MCP 服务器**。与 CLI 使用相同的核心，因此行为相同；破坏性操作带有 MCP 注释，代理在执行前请求。
两个默认代理保护（可禁用）：cloud-init userdata 和 Wi-Fi 密钥等 **秘密字段** 除非 `include_secrets: true`（人类使用 `fbx vm userdata` / `fbx wifi key`），否则会 **屏蔽**，`fbx_lan_devices` 除非 `all: true`，否则仅返回可连接的设备（完整历史记录可达数百 KB）。
**Claude Code 插件（推荐）。** 一个安装同时提供 MCP 服务器 *和* fbx 技能（代理使用保护）。在 Claude Code 中：
```
/plugin marketplace add KevinGallaccio/freebox-cli
/plugin install fbx@fbx
```
插件通过 `uv` **从其自身的代码副本** 启动服务器：更新插件会更新服务器，无需其他刷新：
```
/plugin marketplace update fbx
```
您需要 `uv` 在 PATH 中，并且已经配对的 Freebox (`fbx auth login`，一个物理确认)。
**任何 MCP 客户端（Claude Desktop，Cursor，Zed 等）。** 使用额外的 `mcp` 安装并将您的客户端指向 `fbx mcp serve`：
```sh
uv tool install 'freebox-cli[mcp]'
fbx mcp install # 显示当前客户端的确切线路
```
```json
{ "mcpServers": { "fbx": { "command": "fbx", "args": ["mcp", "serve"] } } }
```
**根据您的喜好调整 API 暴露级别。** 默认情况下，所有内容都已暴露 - 由操作员决定，而不是工具：
```sh
fbx mcp serve --read-only # 没有写入权限
fbx mcp serve --toolsets vm,wifi # 只有这些工具集
fbx mcp serve --exclude raw # 没有原始 API 陷阱
fbx mcp tools # 预览过滤器公开的内容
```
## `--json` 契约
每个生成数据的命令都接受 `--json` 并显示 **完整** 结果对象 - 没有截断。数据放在 stdout 上；所有消息、旋转器和错误放在 stderr 上，管道保持干净：
```sh
fbx --json system info | jq '.firmware_version'
fbx api GET connection/ | jq '{state, media, rate_down}'
```
### `fbx api` - 备用陷阱
对任何端点的身份验证原始调用。适用于任何命令类型尚不存在的位置，以及探索 API。路径直接来自文档（前缀 `/api/latest/` 或 `/api/v16/` 被删除）：
```sh
fbx api GET system/
fbx api GET vm/
fbx api POST vm/1/start
fbx api PUT wifi/config/ --data '{"enabled": true}'
```
## 路线图
- [x] 阶段 0 - 在真正的 Freebox Ultra 上识别 API（私有）
- [x] 阶段 1 - 发现，身份验证，`fbx system info`，`fbx api`（**v0.1.0**）
- [x] 阶段 2 - 所有领域的读取，`--json` everywhere（**v0.2.0**）
- [x] 阶段 3 - 每个领域的写入操作（**v0.3.0**）
- [x] 阶段 4 - 虚拟机生命周期 + 串行控制台（**v0.4.0**）
- [x] 阶段 5 - MCP 服务器 + Claude Code 插件和技能（**v0.5.0**）
- [x] 阶段 6 - PyPI + Homebrew Tap + 交互式应用程序（**v0.6.0**）
- [x] 阶段 7 - 准备存储库以供贡献（规则、模板、保护）
- [ ] 阶段 8 - 现实世界的反馈和应用程序的 UI/UX 改进
## 贡献
欢迎贡献 - 所有开发和测试 **无需 Freebox**（套件模拟 Freebox）。阅读 [CONTRIBUTING.md](CONTRIBUTING.md)；安全漏洞通过 [SECURITY.md](SECURITY.md) 报告，而不是公开的问题。
## 开发
无需安装任何东西即可修改存储库 - `./fbx` shim 启动 `uv` 并从源代码启动 CLI：
```sh
git clone https://github.com/KevinGallaccio/freebox-cli
cd freebox-cli
./fbx --version
uv sync # 依赖项 + 开发工具
uv run pytest # 套件完全脱机运行（模拟 Freebox）
uv run ruff check src tests scripts
```
无需 Freebox 即可贡献：测试模拟 Freebox。
---
## 英文
`freebox-cli` 为您提供对 **Freebox Ultra** （法国 ISP Free 的光纤路由器/NAS/超级管理程序）的完全控制，从终端：一个 **交互式应用程序**（只需键入 `fbx`：仪表盘、实时瓷砖、上下文建议、确认门控操作）、一个完整的 **可脚本化 CLI** - 连接、局域网、DHCP、端口转发、Wi-Fi、下载、文件、电话和 **虚拟机管理器** 使用 WebSocket 串行控制台 - 以及一个 **MCP 服务器**（109 种工具）和 Claude Code 插件，以便 AI 代理控制 Freebox。
```sh
brew install kevingallaccio/tap/freebox-cli # 或：uv tool install freebox-cli
fbx auth login # 一次性配对 - 按下 Freebox 前面板上的 ▶
fbx # 交互式应用程序
fbx system info # 可脚本化 CLI， everywhere --json
fbx --json api GET connection/ | jq
```
