--- name: Unifly slug: unifly category: DevOps description: Unifly manages UniFi network infrastructure from the command line. Use it to configure devices, networks, firewall rules, DHCP, DNS, VPN, backups, and live event monitoring. github: "https://github.com/hyperb1iss/unifly/tree/main/skills/unifly" language: Rust stars: 250 forks: 15 install: "npx degit https://github.com/hyperb1iss/unifly/tree/main/skills/unifly ~/.claude/skills/unifly" installs_to: ~/.claude/skills/unifly source_path: skills/unifly/SKILL.md collection_size: 1 category_size: 828 added: 2026-09-02T05:20:55.715Z last_synced: 2026-09-02T05:20:55.715Z canonical_url: "https://dirskills.com/skills/unifly" --- # Unifly Unifly manages UniFi network infrastructure from the command line. Use it to configure devices, networks, firewall rules, DHCP, DNS, VPN, backups, and live event monitoring. **Install:** ```bash npx degit https://github.com/hyperb1iss/unifly/tree/main/skills/unifly ~/.claude/skills/unifly ``` ## README # 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: ```bash 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] [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 | | `clients` | `cl` | list, find, get, roams, wifi, authorize, unauthorize, block, unblock, kick, forget, reservations (`res`), set-ip, remove-ip | | `cloud` | | hosts [get], sites, switch, devices, isp [query], sdwan [get, status] | | `networks` | `net`, `n` | list, get, create, update, delete, refs | | `wifi` | `w` | list, get, neighbors, channels, create, update, delete | | `firewall` | `fw` | policies {list, get, create, update, patch, delete, reorder}, zones {list, get, create, update, delete}, groups {list, get, create, update, delete} | | `nat` | | policies {list, get, create, update, delete} | | `acl` | | list, get, create, update, delete, reorder | | `dns` | | list, get, create, update, delete | | `traffic-lists` | | list, get, create, update, delete | | `hotspot` | | list, get, create, delete, purge | | `events` | | list, watch | | `alarms` | | list, archive, archive-all | | `stats` | | site, device, client, gateway, dpi | | `dpi` | | apps, categories, status, enable, disable | | `topology` | `topo` | _(no subcommands)_ | | `system` | `sys` | info, health, sysinfo, backup {create, list, download, delete}, reboot, poweroff | | `settings` | | list, get, set, export | | `sites` | | list, create, delete | | `admin` | | list, invite, revoke, update | | `wans` | | list | | `vpn` | | servers [get], tunnels [get], status, health, site-to-site {list, get, create, update, delete}, remote-access {list, get, create, update, suggest-port, download-config, delete}, clients {list, get, create, update, delete}, connections {list, get, restart}, peers {list, get, create, update, delete, subnets}, magic-site-to-site {list, get}, settings {list, get, set, patch} | | `radius` | | profiles | | `countries` | | _(no subcommands)_ | | `api` | | Raw API passthrough (GET/POST/PUT/PATCH/DELETE any path) | | `config` | | init, cloud-setup, show, set, profiles, use, set-password, theme | | `tui` | | _(no subcommands)_ | | `completions` | | bash, zsh, fish, powershell, elvish | For flag details and gotchas, consult `references/commands.md`. Every entity command accepts `--help` at runtime as the authoritative reference. ## Output Formats All list and get commands accept `--output` / `-o`: | Format | Flag | Use Case | | -------------- | ----------------- | ------------------------------------- | | `table` | `-o table` | Human display (default) | | `json` | `-o json` | Agent processing, pipe to `jq` | | `json-compact` | `-o json-compact` | Single-line JSON for scripting | | `yaml` | `-o yaml` | Config file output | | `plain` | `-o plain` | One ID per line for `xargs` pipelines | **Default for agent use: `-o json`.** Emit structured output, pipe through `jq`, and only fall back to `table` when the result is being shown to a human. ## Power Patterns These patterns unlock unifly's most distinctive capabilities. For full recipes with runnable shell scripts, consult `references/workflows.md`. ### `--from-file` for complex create/update Most entities accept `--from-file ` (or `-F`) instead of flag salad: `networks`, `wifi`, `firewall policies`, `firewall zones`, `firewall groups`, `nat policies`, `acl`, `dns`, `traffic-lists`, `vpn site-to-site`, `vpn remote-access`, `vpn clients`, `vpn peers`, `vpn settings patch`, and `devices port-set` (JSONC for switch port config-as-code). Construct the JSON payload, validate it, then apply. See `examples/` for payload templates. ```bash unifly networks create -F examples/network-iot-vlan.json unifly firewall policies create -F examples/firewall-block-iot.json ``` ### Real-time event streaming ```bash # All events unifly events watch # Filter by EventCategory (case-insensitive): Device, Client, Network, # System, Admin, Firewall, Vpn, Unknown unifly events watch --types "Firewall,Admin" # JSON stream for piping into alerting (severity serializes PascalCase) unifly events watch --types Client -o json | jq -c 'select(.severity == "Warning")' ``` ### Firewall policy reorder (round-trippable) ```bash # Read current order for a zone pair unifly firewall policies reorder --source-zone --dest-zone --get # Write back an explicit order unifly firewall policies reorder --source-zone --dest-zone \ --set ",," ``` ### Raw API escape hatch For endpoints unifly does not wrap (including UniFi v2 routes and Integration paths), use `unifly api`. It routes through the Session client, so CSRF token management and session caching are automatic. ```bash unifly api "v2/api/site/default/traffic-flow-latest-statistics" unifly api "cmd/stamgr" -m post -d '{"cmd":"kick-sta","mac":"aa:bb:cc:dd:ee:ff"}' unifly api "api/s/default/set/setting/teleport" -m put -d '{"enabled":true}' ``` ### Session API VPN payloads and settings `unifly vpn site-to-site` wraps Session API `rest/networkconf` records whose `purpose` is `site-vpn`. This is the current CRUD path for manual IPsec and OpenVPN site-to-site records exposed by the controller. ```bash unifly vpn site-to-site list -o json unifly vpn site-to-site get -o json unifly vpn site-to-site create -F site-to-site.json unifly vpn site-to-site update -F site-to-site.json unifly vpn site-to-site delete ``` `unifly vpn remote-access` wraps Session API `rest/networkconf` records whose `purpose` is `remote-user-vpn`. This is the current CRUD path for L2TP, OpenVPN, and WireGuard remote-access servers exposed by the controller. ```bash unifly vpn remote-access list -o json unifly vpn remote-access get -o json unifly vpn remote-access create -F remote-access.json unifly vpn remote-access update -F remote-access.json unifly vpn remote-access suggest-port -o json unifly vpn remote-access download-config --path . unifly vpn remote-access delete ``