ez-unifi

# 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...