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