/unifly

name: unifly
version: "0.10.0"
description: >-
  This skill should be used when the user asks to "manage UniFi devices",
  "configure UniFi networks", "create a VLAN", "provision an SSID",
  "create firewall rules", "reorder firewall policies", "create a NAT rule",
  "set up port forwarding", "configure masquerade NAT", "add DNS records",
  "manage traffic matching lists", "create DHCP reservations", "list DHCP reservations",
  "block a client", "kick a client", "find a client by IP or name",
  "adopt a device", "restart a UniFi device", "cycle a PoE port",
  "upgrade device firmware", "run a speed test", "stream UniFi events",
  "watch real-time events", "query UniFi stats", "analyze DPI traffic",
  "enable DPI", "generate hotspot vouchers", "show network topology",
  "audit firewall policies", "create a backup", "call the raw UniFi API",
  "check network health", or any task involving UniFi network infrastructure
  management via the unifly CLI. Also triggers on mentions of unifly, UniFi,
  Ubiquiti, UDM, UCG, USG, USW, UAP, UXG, UNVR, U6, U7, or UniFi controller
  operations.

unifly: UniFi Network Management

unifly is a Rust CLI for managing Ubiquiti UniFi network infrastructure. It unifies the modern Integration API (REST, API key), the Session API (cookie plus CSRF), and Site Manager cloud APIs behind a single coherent interface, plus real-time WebSocket event streaming. 28 top-level commands cover devices and switch port config-as-code, clients, networks, WiFi, firewall policies, zones, and groups, NAT policies, ACLs, DNS, traffic matching lists, hotspot vouchers, DPI, stats, backups, the full VPN surface, site settings, cloud fleet queries, and a raw API escape hatch.

Unique capabilities worth leading with when the user's task suits them:

• **Dual-API enrichment** merges Integration and Session data (e.g. client

bytes, hostnames, uplink MACs only exist in the Session API; configuration CRUD only exists in Integration). On UniFi OS, API key mode can already reach session HTTP; Hybrid adds the WebSocket session for live monitoring.

• **Real-time event streaming** via `unifly events watch` over WebSocket.
• **Firewall policy reordering** via `reorder --get` / `reorder --set` for

deterministic, round-trippable ordering edits.

• **`unifly api` raw passthrough** for endpoints unifly does not wrap.
• **Multi-profile** (`-p home`, `-p office`) for managing multiple controllers

from one command line.

Prerequisites

Verify availability before running any command:

command -v unifly >/dev/null 2>&1 && unifly --version || echo "unifly not installed"

If unifly is not installed, prefer `brew install hyperb1iss/tap/unifly` on macOS or `cargo install --git https://github.com/hyperb1iss/unifly.git unifly` elsewhere. After install, run `unifly config init` for a local controller or `unifly config cloud-setup` for Site Manager. See `examples/config.toml` for manual configuration.

Authentication Modes

unifly supports four modes. **API key mode is enough for most HTTP automation on UniFi OS controllers.** Choose **Hybrid** when the task needs live WebSocket features (`events watch`) or you want maximum compatibility.

| Mode | Credentials | What It Unlocks | | ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `integration` | API key | Integration API plus session HTTP on UniFi OS: CRUD, device commands, stats, reservations, admin, event list | | `session` | Username + password | Session HTTP + WebSocket only: events watch, stats, device commands, DPI control, admin, backups, NAT policies, firewall groups, switch port config-as-code, site settings | | `hybrid` | API key + username/pass | Everything above, including session WebSocket plus enriched records with maximum controller compatibility | | `cloud` | Site Manager API key | Connector-routed Integration CRUD plus `unifly cloud` fleet commands against `api.ui.com` |

Session WebSocket still rejects API keys, so `events watch` needs `session` or `hybrid`. Cloud mode does **not** expose Session API endpoints or WebSocket streaming.

For the complete command-to-API gate matrix (which commands require which auth mode), consult `references/concepts.md`.

Command Inventory

All commands follow `unifly [global-flags] <command> <action> [args]`.

| Command | Aliases | Actions | | --------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `devices` | `dev`, `d` | list, get, adopt, remove, restart, locate, port-cycle, ports, ports-export, port-set, stats, pending, upgrade, provision, speedtest, tags