UniFi Site Manager CLI (usm-cli) 使用指南 - 命令行管理 UniFi 云站点

usm-cli by dl-alexandre/skills

5 周安装量

GitHub

安装命令

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

云服务命令行工具网络协议分析

🇨🇳中文介绍

Skill: 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/

快速开始

从 unifi.ui.com → 设置 → 控制平面 → 集成 → API 密钥获取 API 密钥
配置：

🇺🇸English

Skill: usm-cli

UniFi Site Manager CLI

This skill provides guidance for the usm CLI tool, a command-line interface for the UniFi Site Manager API.

Overview

usm provides cloud-based management of UniFi sites via the official Site Manager API at api.ui.com. For local controller APIs (Network, Protect), see the separate unifi CLI.

Installation

Homebrew

brew tap dl-alexandre/tap
brew install usm

Manual

Download from 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/

Quick Start

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

145,500 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

142,000 周安装

Azure 配额管理指南：服务限制、容量验证与配额增加方法

116,900 周安装

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

104,900 周安装

# 或者：export USM_API_KEY="your-api-key"

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

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

--force - 覆盖现有配置

列出所有站点，支持分页和筛选。

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

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

usm sites list                          # 默认：50 个站点
usm sites list --page-size 0            # 获取所有站点
usm sites list --search "office"        # 按名称筛选
usm sites list --output json            # JSON 输出
usm sites list --no-headers             # 用于管道传输到其他工具

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

需要某个特定站点的详细信息
拥有站点 ID 并想验证其是否存在

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

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

验证 API 密钥是否有效
检查当前以哪个账户身份认证

usm whoami
usm whoami --output json

显示版本信息。

检查已安装版本
检查更新（使用 --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	网络错误

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

Get API Key from unifi.ui.com → Settings → Control Plane → Integrations → API Keys
Configure:

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

Interactive configuration setup. Creates ~/.config/usm/config.yaml.

First-time setup
Changing default settings (base URL, output format, color mode)

--force - Overwrite existing config

List all sites with pagination and filtering.

Getting an overview of all UniFi sites
Finding a specific site by name
Exporting site data

--page-size=N - Number of sites per page (default: 50, 0 = fetch all)
--search=<term> - Filter by name/description
--output=json|table - Output format
--no-headers - Table without headers (for scripts)

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

Get detailed information about a specific site.

You need details about one specific site
You have a site ID and want to verify it exists

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

Show authenticated user account information.

Verifying API key is working
Checking which account you're authenticated as

usm whoami
usm whoami --output json

Show version information.

Checking installed version
Checking for updates (with --check)

--check - Check GitHub for latest release

Config file: ~/.config/usm/config.yaml

Note: API keys are NOT stored in config. Use environment variables or flags.

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

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

Environment Variables

Variable	Description
`USM_API_KEY`	API key for authentication (required)
`USM_BASE_URL`	API base URL (default: https://api.ui.com)
`USM_TIMEOUT`	Request timeout in seconds
`USM_FORMAT`	Default output format
`USM_COLOR`	Color mode
`USM_NO_HEADERS`	Disable table headers
`USM_CONFIG`	Path to config file

Code	Meaning
0	Success
1	General error
2	Authentication failure
3	Permission denied
4	Validation error
5	Rate limited
6	Network error

unifi CLI - For local UniFi Network and Protect APIs

List all sites and export to JSON

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

Find a site by name and get its details

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

Check authentication in CI/CD

usm whoami || exit 1

Table output for reports

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

Supabase Postgres 最佳实践指南 - 8大类别性能优化规则与SQL示例

78,800 周安装

UniFi Site Manager CLI (usm-cli) 使用指南 - 命令行管理 UniFi 云站点

🇨🇳中文介绍

Skill: usm-cli

UniFi Site Manager CLI

概述

安装

Homebrew

手动安装

快速开始

🇺🇸English

Skill: usm-cli

UniFi Site Manager CLI

Overview

Installation

Homebrew

Manual

Quick Start

相关 Skills

可用命令

usm init

usm sites list

usm sites get

usm whoami

usm version

配置

环境变量

退出代码

API 参考

相关工具

常见工作流

列出所有站点并导出为 JSON

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

在 CI/CD 中检查认证

用于报告的表格输出

Available Commands

usm init

usm sites list

usm sites get

usm whoami

usm version

Configuration

Environment Variables

Exit Codes

API Reference

Related Tools

Common Workflows

List all sites and export to JSON

Find a site by name and get its details

Check authentication in CI/CD

Table output for reports

最新 Skills