mcpField
U
unifi-cli

unifi-cli

github.com/dl-alexandreクラウド・DevOps145 回インストール4 週間前に更新
リポジトリ

unifi-cli について

unifi-cliは、Dream Machine、Cloud Key、セルフホスト環境などのローカルUniFi Networkコントローラーを操作する`unifi`コマンドラインツールのスキルです。サイト、ネットワーク機器、接続中のクライアントを確認できます。

主な機能

  1. 01コントローラー接続の設定
  2. 02コントローラーのサイト一覧
  3. 03UniFi機器と状態の確認
  4. 04接続中クライアントの一覧
  5. 05結果のJSON出力

活用シーン

  1. 01サイト別コマンドの実行前にサイトを特定
  2. 02機器の状態と採用状況を確認
  3. 03IPまたはMACアドレスでクライアントを検索
  4. 04分析用に機器一覧をエクスポート

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/unifi-cliを入力して読み込まれたか確認します。

詳細

スキル：unifi-cli

ローカル UniFi Controller CLI

このスキルでは、ローカルの UniFi Network コントローラー向けのコマンドラインインターフェースである unifi CLI ツールの使用方法を説明します。

概要

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 対応