# Hyperb1iss Unifly Unifly > unifly: UniFi Network Management - Skill: `tomevault-io/hyperb1iss-unifly-unifly` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hyperb1iss-unifly-unifly` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hyperb1iss-unifly-unifly/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hyperb1iss-unifly-unifly --- # 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, clients, networks, WiFi, firewall policies and zones, NAT policies, ACLs, DNS, traffic matching lists, hotspot vouchers, DPI, stats, backups, 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 | | `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, 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} | | `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 {list, get}, tunnels {list, 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 | | `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`, `nat policies`, `acl`, `dns`, `traffic-lists`, `hotspot`, `vpn site-to-site`, `vpn remote-access`, `vpn clients`, and `vpn peers`. 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 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 ``` `unifly vpn clients` wraps Session API `rest/networkconf` records whose `purpose` is `vpn-client`. This is the current CRUD path for configured OpenVPN and WireGuard client profiles exposed by the controller. ```bash unifly vpn clients list -o json unifly vpn clients get -o json unifly vpn clients create -F vpn-client.json unifly vpn clients update -F vpn-client.json unifly vpn clients delete ``` `unifly vpn peers` wraps the Session v2 API WireGuard peer endpoints for remote-access VPN servers. `list` can enumerate all peers or scope to a single server ID; `create`, `update`, and `delete` require the parent remote-access server ID. ```bash unifly vpn peers list -o json unifly vpn peers list -o json unifly vpn peers get -o json unifly vpn peers create -F peer.json unifly vpn peers update -F peer.json unifly vpn peers delete unifly vpn peers subnets -o json ``` `unifly vpn connections` wraps the Session v2 API VPN client connection inventory exposed at `v2/api/site//vpn/connections`. `restart` issues the same controller action the web UI uses for a single connection. ```bash unifly vpn connections list -o json unifly vpn connections get -o json unifly vpn connections restart ``` `unifly vpn magic-site-to-site` wraps the Session v2 API `magicsitetositevpn/configs` inventory endpoint. It is currently read-only. ```bash unifly vpn magic-site-to-site list -o json unifly vpn magic-site-to-site get -o json ``` `unifly vpn settings` wraps the Session API `rest/setting` records for the VPN feature toggles the controller exposes today: `teleport`, `magic-site-to-site-vpn`, `openvpn`, and `peer-to-peer`. ```bash unifly vpn settings list -o json unifly vpn settings get peer-to-peer -o json unifly vpn settings set teleport --enabled true unifly vpn settings patch peer-to-peer -F peer-to-peer.json ``` `site-to-site get`, `remote-access get`, `clients get`, `connections get`, `peers get`, and `magic-site-to-site get` return redacted records with summary fields and the sanitized controller payload under `fields`. `settings get` returns a redacted wrapper with `key`, `enabled`, and `fields`. `patch` accepts either the raw session setting body or that wrapper shape and will send the inner `fields` object back to the controller. ### Bulk operations via filter DSL `hotspot purge --filter` accepts the Integration filter DSL for bulk deletion without ID iteration: ```bash unifly hotspot purge --filter "status.eq('UNUSED')" unifly hotspot purge --filter "name.contains('Conference')" ``` ### TUI handoff for human verification Propose a change, let a human visually confirm in the TUI before committing: ```bash # Agent inspects, proposes. Human runs unifly tui and verifies on # screen 4 (Networks) or 5 (Firewall) before the agent applies the change. unifly tui ``` ### Multi-profile targeting ```bash unifly -p home devices list unifly -p office firewall policies list UNIFI_PROFILE=warehouse unifly system health ``` ## Essential Gotchas 1. **Default list limit is 25.** The CLI prints a truncation hint when results hit the default. For enumeration, always pass `--all` or `--limit 200` (or higher). 2. **Environment variables use the `UNIFI_` prefix, not `UNIFLY_`.** Relevant vars: `UNIFI_URL`, `UNIFI_API_KEY`, `UNIFI_USERNAME`, `UNIFI_PASSWORD`, `UNIFI_SITE`, `UNIFI_PROFILE`, `UNIFI_OUTPUT`, `UNIFI_INSECURE`, `UNIFI_TIMEOUT`, `UNIFI_TOTP`. The only `UNIFLY_*` var is `UNIFLY_THEME` for the TUI. 3. **`--yes` / `-y`** skips confirmation prompts for mutations. Required for non-interactive use. 4. **API key mode covers most commands** on UniFi OS, including Session API endpoints (stats, device commands, Wi-Fi observability, client enrichment). Use **Hybrid only when live WebSocket streaming is needed** (`events watch`, TUI live refresh). Client and device enrichment fields work in API key mode. 5. **Cloud support is Integration-only.** `unifly cloud ...` talks to Site Manager and `auth_mode = "cloud"` routes Integration-backed commands through the connector, but Session-only features still need direct controller access. 6. **Exit codes are meaningful.** `0` on success, non-zero on error. Capture stderr for diagnostics. ## Agent Workflow 1. Verify the tool exists with `command -v unifly`. 2. Check auth mode with `unifly config show` before running commands that require Session or Integration specifically. 3. Run `unifly system health -o json` as the first touch to confirm connectivity. 4. Inspect before mutating: `list` / `get` the entity first, capture IDs. 5. For complex creates, write a JSON payload and use `--from-file`. 6. After mutations, re-fetch the entity with `get` to confirm state. 7. For irreversible operations (delete, reboot, poweroff), surface a summary to the user before running even with `--yes`. ## Additional Resources ### Reference Files - **`references/commands.md`**: Per-command flag reference with gotchas (non-obvious flags, dual-API boundaries, correct argument forms) - **`references/concepts.md`**: UniFi networking concepts, dual-API gate matrix, auth decision tree, environment variables, platform config paths, MFA/TOTP, error taxonomy - **`references/workflows.md`**: Runnable automation recipes (event streaming, safe firewall reorder, bulk DHCP reservations, ad-blocking via DNS policies, cafe voucher flow, incident response) ### Example Files - **`examples/config.toml`**: Multi-profile config template - **`examples/network-iot-vlan.json`**: VLAN creation payload for `--from-file` - **`examples/firewall-block-iot.json`**: Firewall policy payload - **`examples/nat-masquerade.json`**: NAT masquerade policy payload - **`examples/nat-port-forward.json`**: Destination NAT (port forward) payload - **`examples/wifi-iot.json`**: WiFi SSID payload - **`examples/vpn-remote-access-wireguard.json`**: WireGuard remote-access VPN payload - **`examples/vpn-site-to-site-ipsec.json`**: IPsec site-to-site tunnel payload - **`examples/vpn-client-openvpn.json`**: OpenVPN client payload - **`examples/vpn-wireguard-peer.json`**: WireGuard peer configuration payload --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/hyperb1iss) — claim your Tome and manage your conversions.