UniFi Network Monitoring Skill

Monitor and manage UniFi network infrastructure through the UniFi Controller API.

Device Information

User's UniFi Setup:

• UniFi Security Gateway (USG3) - Router/Gateway

• Cloud Key Gen 2 - UniFi Controller host

• Access Points, Switches (to be discovered)

Available Commands

All commands are executed via the UniFi CLI wrapper located at ~/.claude/skills/Unifi/unifi-cli.ts .

Run commands using:

bun ~/.claude/skills/Unifi/unifi-cli.ts <command>

Network Status Commands

Get Site Status

bun ~/.claude/skills/Unifi/unifi-cli.ts site-status

Shows overall network health, controller version, and site information.

List All Devices

bun ~/.claude/skills/Unifi/unifi-cli.ts devices

Shows all UniFi devices (USG, APs, Switches) with status, uptime, and firmware.

List Connected Clients

bun ~/.claude/skills/Unifi/unifi-cli.ts clients

Shows all connected clients with hostname, IP, MAC, connection type, and bandwidth usage.

Get Device Health

bun ~/.claude/skills/Unifi/unifi-cli.ts health

Shows health metrics for all devices including CPU, memory, uptime.

Get Recent Alerts

bun ~/.claude/skills/Unifi/unifi-cli.ts alerts

Shows recent network alerts and events.

Get WAN Status

bun ~/.claude/skills/Unifi/unifi-cli.ts wan

Shows WAN connection status, public IP, speeds, and uptime.

Get Bandwidth Stats

bun ~/.claude/skills/Unifi/unifi-cli.ts bandwidth

Shows current bandwidth usage by client and overall network.

Configuration

Configuration is stored in ~/.claude/skills/Unifi/config.json :

{ "controller": { "host": "192.168.1.x", "port": 8443, "username": "admin", "password": "your-password", "site": "default" } }

Security Notes:

• Config file contains credentials - NEVER commit to public repos

• Stored in ~/.claude/skills/Unifi/ which should be in .gitignore

• Uses local network connection to Cloud Key

• Read-only operations by default (safe queries only)

First-Time Setup

If this is the first time using the skill:

Install dependencies:

cd ~/.claude/skills/Unifi && bun install

Create config file:

cp ~/.claude/skills/Unifi/config.example.json ~/.claude/skills/Unifi/config.json

Edit config with actual values:

• Set host to Cloud Key IP address

• Set username and password for UniFi Controller

• Site is usually "default" unless using multiple sites

Test connection:

bun ~/.claude/skills/Unifi/unifi-cli.ts site-status

Usage Instructions for AI

When user asks about network status:

Check if skill is configured:

• Verify ~/.claude/skills/Unifi/config.json exists

• If not, guide user through setup

Run appropriate command:

• Network status → site-status

• Who's online → clients

• Device health → health or devices

• Internet status → wan

• Recent issues → alerts

Parse and present results:

• Format output in readable tables

• Highlight important metrics (high bandwidth, offline devices, alerts)

• Provide context and interpretation

Example Queries

User asks: "Who's connected to my network?"

bun ~/.claude/skills/Unifi/unifi-cli.ts clients

User asks: "Is my internet working?"

bun ~/.claude/skills/Unifi/unifi-cli.ts wan

User asks: "What's wrong with my network?"

bun ~/.claude/skills/Unifi/unifi-cli.ts alerts bun ~/.claude/skills/Unifi/unifi-cli.ts health

User asks: "How's my network doing?"

bun ~/.claude/skills/Unifi/unifi-cli.ts site-status bun ~/.claude/skills/Unifi/unifi-cli.ts devices

Limitations

• Read-only operations (no configuration changes)

• Requires local network access to Cloud Key

• Depends on UniFi Controller being online and accessible

• Some features require specific UniFi device types

Future Enhancements

Potential additions:

• Port forwarding management

• DHCP lease information

• Deep packet inspection (DPI) stats

• Guest network management

• WiFi configuration queries

• Historical bandwidth trends

• Alert notifications

Troubleshooting

Connection Failed:

• Verify Cloud Key is online and accessible

• Check IP address in config.json

• Ensure username/password are correct

• Verify port 8443 is accessible (HTTPS to Controller)

Authentication Failed:

• Verify username/password in config.json

• Check if account has admin privileges

• Try logging into Controller web UI with same credentials

Command Not Found:

• Run cd ~/.claude/skills/Unifi && bun install

• Verify bun is installed: bun --version

• Check file exists: ls -la ~/.claude/skills/Unifi/unifi-cli.ts