usm-cli

技能：usm-cli

UniFi Site Manager CLI

本技能为 usm CLI 工具提供使用指南。该工具是 UniFi Site Manager API 的命令行接口。

概览

usm 通过 api.ui.com 上的官方 Site Manager API，提供基于云端的 UniFi 站点管理。对于本地控制器 API（Network、Protect），请参阅单独的 unifi CLI。

安装

Homebrew

brew tap dl-alexandre/tap
brew install usm

手动安装

从 GitHub Releases 下载：

# macOS (Apple Silicon)
curl -L https://github.com/dl-alexandre/UniFi-Site-Manager-CLI/releases/latest/download/usm-darwin-arm64 -o usm
chmod +x usm
sudo mv usm /usr/local/bin/

快速入门

1. 从 unifi.ui.com → Settings → Control Plane → Integrations → API Keys 获取 API 密钥

2. 配置：

usm init
# Or: export USM_API_KEY="your-api-key"

3. 验证：

usm whoami

4. 列出站点：

usm sites list

可用命令

usm init

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

适用场景：

• 首次设置
• 更改默认设置（基础 URL、输出格式、颜色模式）

标志：

• --force - 覆盖现有配置

usm sites list

分页并筛选列出所有站点。

适用场景：

• 概览所有 UniFi 站点
• 按名称查找特定站点
• 导出站点数据

标志：

• --page-size=N - 每页站点数（默认值：50，0 = 获取全部）
• --search=<term> - 按名称/描述筛选
• --output=json|table - 输出格式
• --no-headers - 表格不显示表头（用于脚本）

示例：

usm sites list                          # Default: 50 sites
usm sites list --page-size 0            # Fetch all sites
usm sites list --search "office"        # Filter by name
usm sites list --output json            # JSON output
usm sites list --no-headers             # For piping to other tools

usm sites get

获取特定站点的详细信息。

适用场景：

• 需要了解某个特定站点的详细信息
• 已有站点 ID，想要验证其是否存在

示例：

usm sites get 60abcdef1234567890abcdef
usm sites get 60abcdef1234567890abcdef --output json

usm whoami

显示已认证用户的账户信息。

适用场景：

• 验证 API 密钥是否有效
• 查看当前通过哪个账户完成认证

示例：

usm whoami
usm whoami --output json

usm version

显示版本信息。

适用场景：

• 查看已安装的版本
• 检查是否有更新（使用 --check）

标志：

• --check - 检查 GitHub 上的最新版本

配置

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

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

api:
  base_url: https://api.ui.com
  timeout: 30

output:
  format: table      # table, json
  color: auto        # auto, always, never
  no_headers: false

环境变量

变量	描述
USM_API_KEY	用于身份验证的 API 密钥（必需）
USM_BASE_URL	API 基础 URL（默认值：https://api.ui.com）
USM_TIMEOUT	请求超时时间（秒）
USM_FORMAT	默认输出格式
USM_COLOR	颜色模式
USM_NO_HEADERS	禁用表格表头
USM_CONFIG	配置文件路径

退出代码

代码	含义
0	成功
1	一般错误
2	身份验证失败
3	权限被拒绝
4	验证错误
5	请求过多
6	网络错误

API 参考

• Site Manager API 文档

相关工具

• unifi CLI - 用于本地 UniFi Network 和 Protect API

常见工作流

列出所有站点并导出为 JSON

usm sites list --page-size 0 --output json > sites.json

按名称查找站点并获取其详细信息

SITE_ID=$(usm sites list --search "Office" --output json | jq -r '.[0]._id')
usm sites get "$SITE_ID"

在 CI/CD 中检查身份验证

usm whoami || exit 1

用于报告的表格输出

usm sites list --no-headers | column -t