usm-cli

スキル：usm-cli

UniFi Site Manager CLI

このスキルでは、UniFi Site Manager API 用のコマンドラインインターフェースである usm CLI ツールの使用方法を説明します。

概要

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 - 1 ページあたりのサイト数（デフォルト：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