Skill: araa47/ez-unifi (version 1.0.1)

--- name: ez-unifi description: Use when asked to manage UniFi network - list/restart/upgrade devices, block/unblock clients, manage WiFi networks, control PoE ports, manage traffic rules, create guest vouchers, or any UniFi controller task. Works with UDM Pro/SE, Dream Machine, Cloud Key Gen2+, or self-hosted controllers. metadata: {"openclaw":{"emoji":"📶"}} --- # ez-unifi Agent-friendly UniFi Network tools powered by the `aiounifi` library. Supports UDM Pro/SE, Dream Machine, Cloud Key Gen2+, and self-hosted controllers. **Run all commands with:** `uv run scripts/unifi.py <command> [args]` ## Setup **Step 1: Ask user to create a dedicated local admin account** > To manage your UniFi network, I need API access. Please create a dedicated local admin account: > > 1. Open your UniFi controller (e.g., https://192.168.1.1) > 2. Go to **Settings → System → Admins & Users** > 3. Click **Add Admin** > 4. Enter a username (e.g., `agent-api`) > 5. Enter an email and password > 6. **Important: Disable "Remote Access"** - local-only avoids MFA issues > 7. Set Role to **Super Admin** or **Site Admin** > 8. Click **Add** > > Then provide: > - Controller IP (e.g., `192.168.1.1`) > - Username > - Password > - Is it a UDM Pro/SE/Dream Machine? (yes/no) **Step 2: Save credentials to `.env`** ```bash UNIFI_HOST=https://192.168.1.1 UNIFI_USERNAME=agent-api UNIFI_PASSWORD=the_password UNIFI_SITE=default UNIFI_IS_UDM=true ``` Set `UNIFI_IS_UDM=false` for Cloud Key Gen1 or self-hosted controllers. --- ## System & Sites ```bash unifi.py sites # List all sites unifi.py sysinfo # System information unifi.py health # Site health status (WAN, WLAN, LAN) ``` ## Devices (APs, Switches, Gateways) ```bash unifi.py devices # List all devices unifi.py device MAC # Device details unifi.py restart MAC # Restart device unifi.py restart MAC --hard # Hard restart (cycles PoE on switches) unifi.py upgrade MAC # Upgrade device firmware unifi.py locate MAC # Blink LED to locate unifi.py unlocate MAC # Stop LED blinking unifi.py led MAC on|off|default # Set LED status unifi.py led MAC on --color=#FF0000 --brightness=50 # With color/brightness ``` ## Switch Ports ```bash unifi.py ports # List all switch ports unifi.py port MAC PORT_IDX # Port details unifi.py port-enable MAC PORT_IDX # Enable switch port unifi.py port-disable MAC PORT_IDX # Disable switch port unifi.py poe MAC PORT_IDX MODE # Set PoE mode (auto|off|passthrough|24v) unifi.py power-cycle MAC PORT_IDX # Power cycle a PoE port ``` ## Smart Power (PDU/Outlets) ```bash unifi.py outlets # List all outlets unifi.py outlet MAC IDX on|off # Control outlet relay unifi.py outlet-cycle MAC IDX on|off # Enable/disable auto-cycle on internet down ``` ## Clients ```bash unifi.py clients # List active clients unifi.py clients-all # List all clients (including offline/known) unifi.py client MAC # Client details unifi.py block MAC # Block client from network unifi.py unblock MAC # Unblock client unifi.py reconnect MAC # Kick/reconnect client unifi.py forget MAC [MAC2...] # Forget client(s) permanently ``` ## WiFi Networks ```bash unifi.py wlans # List wireless networks unifi.py wlan ID # WLAN details unifi.py wlan-enable ID # Enable WLAN unifi.py wlan-disable ID # Disable WLAN unifi.py wlan-password ID NEWPASS # Change WLAN password unifi.py wlan-qr ID # Generate WiFi QR code (PNG file) unifi.py wlan-qr ID -o myqr.png # Custom output filename ``` ## Port Forwarding ```bash unifi.py port-forwards # List port forwarding rules unifi.py port-forward ID # Port forward details ``` ## Traffic Rules ```bash unifi.py traffic-rules # List traffic rules unifi.py traffic-rule ID # Traffic rule details unifi.py traffic-rule-enable ID # Enable traffic rule unifi.py traffic-rule-disable ID # Disable traffic rule unifi.py traffic-rule-toggle ID on|off # Toggle traffic rule state ``` ## Traffic Routes ```bash unifi.py traffic-routes # List traffic routes unifi.py traffic-route ID # Traffic route details unifi.py traffic-route-enable ID # Enable traffic route unifi.py traffic-route-disable ID # Disable traffic route ``` ## Firewall ```bash unifi.py firewall-policies # List firewall policies unifi.py firewall-policy ID # Firewall policy details unifi.py firewall-zones # List firewall zones unifi.py firewall-zone ID # Firewall zone details ``` ## DPI (Deep Packet Inspection) ```bash unifi.py dpi-apps # List DPI restriction apps unifi.py dpi-app ID # DPI app details unifi.py dpi-app-enable ID # Enable DPI app restriction unifi.py dpi-app-disable ID # Disable DPI app restriction unifi.py dpi-groups # List DPI restriction groups unifi.py dpi-group ID # DPI group details ``` ## Hotspot Vouchers ```bash unifi.py vouchers # List vouchers unifi.py voucher-create --duration=60 --quota=1 --note="Guest" unifi.py voucher-create --duration=1440 --quota=5 --rate-up=5000 --rate-down=10000 unifi.py voucher-delete ID # Delete voucher ``` Voucher options: - `--duration` - Duration in minutes (default: 60) - `--quota` - Number of uses (default: 1) - `--usage-quota` - Usage quota in MB - `--rate-up` - Upload rate limit in Kbps - `--rate-down` - Download rate limit in Kbps - `--note` - Note/description ## Events ```bash unifi.py events # Stream events in real-time (Ctrl+C to stop) ``` ## Raw API Access ```bash unifi.py raw GET /stat/health # Raw GET request unifi.py raw POST /cmd/devmgr '{"cmd":"restart","mac":"aa:bb:cc:dd:ee:ff"}' unifi.py raw PUT /rest/wlanconf/ID '{"enabled":false}' ``` ## Output Options Add `--json` flag to any list command for JSON output: ```bash unifi.py devices --json # JSON output unifi.py clients --json ``` --- ## Examples ```bash # Check network health uv run scripts/unifi.py health # List all connected clients uv run scripts/unifi.py clients # Block a device uv run scripts/unifi.py block "aa:bb:cc:dd:ee:ff" # Restart an access point uv run scripts/unifi.py restart "11:22:33:44:55:66" # Disable guest WiFi uv run scripts/unifi.py wlan-disable "5f8b3d2e1a4c7b9e0d6f8a2c" # Upgrade device firmware uv run scripts/unifi.py upgrade "11:22:33:44:55:66" # Power cycle a PoE port (useful for rebooting PoE devices) uv run scripts/unifi.py power-cycle "switch_mac" 5 # Create a guest voucher (24 hours, single use) uv run scripts/unifi.py voucher-create --duration=1440 --quota=1 --note="Guest access" # Generate WiFi QR code for easy connection uv run scripts/unifi.py wlan-qr "wlan_id" -o guest_wifi.png # Control traffic rule uv run scripts/unifi.py traffic-rule-disable "rule_id" ``` ## Finding IDs - **WLAN IDs**: Run `wlans` and look for the `ID` column - **Device MACs**: Run `devices` and look for the `MAC` column - **Client MACs**: Run `clients` or `clients-all` and look for the `MAC` column - **Traffic Rule IDs**: Run `traffic-rules` and look for the `ID` column - **Voucher IDs**: Run `vouchers` and look for the `ID` column ## Notes - MAC addresses can be any format (with colons, dashes, or none) - All output is JSON for easy parsing - Using a dedicated local account avoids MFA issues with cloud-linked accounts - If you get rate limited (429 error), wait a few minutes before retrying


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)