uniflySAFE

🌐 Elegant UniFi network management CLI & TUI - for humans and agents

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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:

```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 (add `--profile release-small` for a smaller binary on low-power
hosts). 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                                               

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

found

Findings (7)

api_key = "your-integration-api-key-here"

CLAUDE.md

controller = "https://192.168.1.1"

controller = "https://10.0.0.1"

controller = "https://192.168.1.1"

UNIFI_TOTP=$(op read "op://Personal/UniFi/one-time password") \

| Empty `clients list` wireless/bytes fields    | No session HTTP access (non-UniFi-OS, integration mode)  | API key on UniFi OS or `hybrid` mode        |

Gates applied: no_behavioural_pass.