mcpField
U
unifi-cli

unifi-cli

github.com/dl-alexandre云与 DevOps145 次安装4 周前更新
代码仓库

关于 unifi-cli

unifi-cli 是使用 `unifi` 命令行工具管理本地 UniFi Network 控制器的技能，适用于 Dream Machine、Cloud Key 和自托管实例。它可查看站点、网络设备及已连接客户端。

主要功能

  1. 01配置控制器连接
  2. 02列出控制器站点
  3. 03查看 UniFi 设备及状态
  4. 04列出已连接客户端
  5. 05以 JSON 导出结果

适用场景

  1. 01执行站点命令前查找站点
  2. 02检查设备状态和采用状态
  3. 03按 IP 或 MAC 地址查找客户端
  4. 04导出设备清单以供分析

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dl-alexandre/skills --skill unifi-cli

安装后在 Claude Code 中输入/unifi-cli确认已加载。

详细介绍

Skill：unifi-cli

本地 UniFi Controller 命令行工具

本 Skill 介绍 unifi CLI 工具，这是一个用于本地 UniFi Network 控制器的命令行界面。

概述

unifi 可直接连接到本地 UniFi Controller（Dream Machine、Cloud Key 或可自托管的控制器），以管理站点、设备和客户端。若要通过云端管理多个站点，请使用独立的 usm CLI。

安装

Homebrew
brew tap dl-alexandre/tap
brew install unifi
手动安装

从 GitHub Releases 下载。

快速入门

  1. 配置：
unifi init
# Or set environment variables:
export UNIFI_BASE_URL="https://192.168.1.1"
export UNIFI_USERNAME="admin"
export UNIFI_PASSWORD="your-password"
  1. 列出站点：
unifi sites list
  1. 列出设备：
unifi devices list
  1. 列出客户端：
unifi clients list

可用命令

unifi init

交互式配置设置。创建 ~/.config/unifi/config.yaml。

适用场景：

  • 首次设置
  • 更改控制器 URL 或用户名
unifi sites list

列出控制器上的所有站点。

适用场景：

  • 查找可用站点
  • 查找其他命令所需的站点 ID
unifi devices list

列出所有 UniFi 设备（AP、交换机、网关）。

适用场景：

  • 查看网络硬件
  • 检查设备状态和采用状态
  • 查找设备 MAC 地址

标志：

  • --site=<id> - 指定站点（默认：第一个可用站点）
unifi clients list

列出已连接的客户端。

适用场景：

  • 查看已连接的设备
  • 检查无线信号强度
  • 查找客户端 MAC 地址

标志：

  • --site=<id> - 指定站点（默认：第一个可用站点）
unifi version [--check]

显示版本信息。

配置

配置文件：~/.config/unifi/config.yaml

**注意：**密码不会存储在配置中。请使用环境变量或标志。

api:
  base_url: https://192.168.1.1
  timeout: 30

auth:
  username: admin

output:
  format: table
  color: auto

环境变量

变量描述
UNIFI_BASE_URL控制器 URL（例如，https://192.168.1.1）
UNIFI_USERNAME用于身份验证的用户名
UNIFI_PASSWORD用于身份验证的密码
UNIFI_FORMAT输出格式：table、json
UNIFI_COLOR颜色模式：auto、always、never
UNIFI_NO_HEADERS禁用表格标题
UNIFI_CONFIG配置文件路径

身份验证

本地 UniFi Controller 使用基于会话的身份验证：

  1. 客户端将用户名和密码发送到 /api/auth/login
  2. 服务端设置会话 Cookie
  3. 客户端在后续请求中使用该 Cookie
  4. 会话过期时自动重新登录

安全提示：

  • 使用本地管理员账户（不要使用云端/SSO 账户）
  • 密码不会存储在配置中
  • 会话 Cookie 会自动处理

退出代码

代码含义
0成功
1一般错误
2身份验证失败
4验证错误
5请求过于频繁
6网络错误

常见工作流

检查所有站点中的设备
for site in $(unifi sites list --output json | jq -r '.[].name'); do
  echo "=== Site: $site ==="
  unifi devices list --site "$site"
done
将设备列表导出为 JSON
unifi devices list --output json > devices.json
按 IP 查找客户端
unifi clients list --output json | jq '.[] | select(.ip == "192.168.1.100")'
检查采用状态
unifi devices list --output json | jq '.[] | select(.adopted == false)'

API 参考

本地 UniFi Controller API 端点：

  • GET /api/self/sites - 列出站点
  • GET /api/s/{site}/stat/device - 列出设备
  • GET /api/s/{site}/stat/sta - 列出客户端
  • GET /api/s/{site}/stat/health - 站点健康状况

相关工具

  • usm - 用于云端 UniFi Site Manager API（多站点概览）

故障排除

连接被拒绝：

  • 确认控制器 URL 正确
  • 检查控制器是否正在运行
  • 确保使用 HTTPS（而不是 HTTP）

身份验证失败：

  • 使用本地管理员账户（不要使用 UniFi 云账户）
  • 确认用户名和密码
  • 检查是否启用了 2FA（不支持）

证书错误：

  • 本地控制器常使用自签名证书
  • 使用等效的 curl -k 选项，或将证书添加到信任存储

评论

支持 Markdown