Unifly

This skill should be used when the user asks to "manage UniFi devices", "configure UniFi networks", "create a VLAN", "provision an SSID", "create firewall ru...

Security Scan

This is an instruction-only UniFi management skill that is internally consistent with its stated purpose (controlling UniFi controllers via the unifly CLI); it contains examples that can forward events or side-load firmware, so use with normal operational caution.

Purpose & Capability

The name/description match the delivered artifacts: the SKILL.md documents the unifly CLI, its commands, auth modes, paths, and examples for UniFi management. There are no unrelated binaries, unusual permissions, or unexplained env var requests in the package metadata.

Instruction Scope

Runtime instructions focus on using the unifly CLI and manipulating UniFi controller objects (networks, WiFi, firewall, NAT, VPN, events, backups, etc.). Examples include piping live events to external webhooks (using $SLACK_WEBHOOK) and a device upgrade flag that accepts an arbitrary firmware URL (upgrade --url). Those behaviors are legitimate features for automation/alerting but can transmit controller-derived data externally or push non-vendor firmware if misused. The skill does not instruct reading unrelated system files or harvesting environment variables beyond standard controller config/env usage.

Install Mechanism

This is instruction-only (no install spec). SKILL.md recommends installing the upstream unifly binary via brew or cargo, which is a reasonable, typical user action and not performed automatically by the skill package itself.

Credentials

The skill declares no required environment variables or credentials. The documentation references common patterns (UNIFI_* envs, storing API keys in the OS keyring, and examples that use a $SLACK_WEBHOOK), which are proportional to a UniFi management tool. Note: a few example payload files include literal example secrets (e.g., WiFi passphrase 'IoTSecure2024!') — these are sample values and not required by the skill, but could mislead users into shipping weak/default creds.

Persistence & Privilege

The skill does not request elevated platform persistence; always:false and default autonomous-invocation settings are normal. It does not modify other skills or global agent configuration.

Scan Findings in Context

[no-findings] expected: The regex scanner found no code-level matches. This is expected because the package is instruction-only and contains no executable code files for the scanner to analyze.

Assessment

This skill is coherent for managing UniFi controllers using the unifly CLI. Before installing/using it: 1) only run the recommended install commands from trusted sources (official GitHub releases or your package manager); 2) never paste real controller credentials into example files—use the OS keyring or env vars as documented; 3) review automation examples that forward events to external webhooks (they will transmit controller event data to whatever webhook you configure); 4) be cautious with 'device upgrade --url' or raw API passthrough: these can be used to side‑load firmware or execute controller operations if pointed at untrusted endpoints; and 5) limit autonomous invocation or credential exposure if you do not want agents to run network-changing commands without explicit user approval.

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:

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] <command> <action> [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 <path.json> (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.

unifly networks create -F examples/network-iot-vlan.json
unifly firewall policies create -F examples/firewall-block-iot.json

Real-time event streaming

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

# Read current order for a zone pair
unifly firewall policies reorder --source-zone <zid> --dest-zone <zid> --get

# Write back an explicit order
unifly firewall policies reorder --source-zone <zid> --dest-zone <zid> \
  --set "<id1>,<id2>,<id3>"

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.

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.

unifly vpn site-to-site list -o json
unifly vpn site-to-site get <id> -o json
unifly vpn site-to-site create -F site-to-site.json
unifly vpn site-to-site update <id> -F site-to-site.json
unifly vpn site-to-site delete <id>

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.

unifly vpn remote-access list -o json
unifly vpn remote-access get <id> -o json
unifly vpn remote-access create -F remote-access.json
unifly vpn remote-access update <id> -F remote-access.json
unifly vpn remote-access suggest-port -o json
unifly vpn remote-access download-config <id> --path .
unifly vpn remote-access delete <id>

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.

unifly vpn clients list -o json
unifly vpn clients get <id> -o json
unifly vpn clients create -F vpn-client.json
unifly vpn clients update <id> -F vpn-client.json
unifly vpn clients delete <id>

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.

unifly vpn peers list -o json
unifly vpn peers list <server-id> -o json
unifly vpn peers get <server-id> <peer-id> -o json
unifly vpn peers create <server-id> -F peer.json
unifly vpn peers update <server-id> <peer-id> -F peer.json
unifly vpn peers delete <server-id> <peer-id>
unifly vpn peers subnets -o json

unifly vpn connections wraps the Session v2 API VPN client connection inventory exposed at v2/api/site/<site>/vpn/connections. restart issues the same controller action the web UI uses for a single connection.

unifly vpn connections list -o json
unifly vpn connections get <id> -o json
unifly vpn connections restart <id>

unifly vpn magic-site-to-site wraps the Session v2 API magicsitetositevpn/configs inventory endpoint. It is currently read-only.

unifly vpn magic-site-to-site list -o json
unifly vpn magic-site-to-site get <id> -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.

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:

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:

# 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

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