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

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

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

Verify:

usm whoami

List sites:

usm sites list

Available Commands

usm init

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

Use when:

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

Flags:

--force - Overwrite existing config

usm sites list

List all sites with pagination and filtering.

Use when:

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

Flags:

--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)

Examples:

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

Get detailed information about a specific site.

Use when:

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

Examples:

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

usm whoami

Show authenticated user account information.

Use when:

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

Examples:

usm whoami
usm whoami --output json

usm version

Show version information.

Use when:

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

Flags:

--check - Check GitHub for latest release

Configuration

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

Exit Codes

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

API Reference

Site Manager API Documentation

Related Tools

unifi CLI - For local UniFi Network and Protect APIs

Common Workflows

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