unifly

unifly is a command-line toolkit for managing Ubiquiti UniFi network controllers. It provides a single binary with 28 top-level commands for automation and scripting, alongside a built-in Terminal User Interface (TUI) for real-time monitoring.

Key capabilities include:

• Unified API Engine: Supports Integration API, Session API (via UniFi OS API keys), Site Manager cloud fleet APIs, and the cloud connector.
• Real-Time Monitoring: An 11-screen TUI featuring traffic charts, CPU/MEM gauges, and zoomable topology.
• Observability: Wi-Fi experience scores, neighboring AP detection, and live event streaming via WebSockets.
• Automation-Friendly: Pipe-friendly output in Table, JSON, compact JSON, YAML, and plain text formats.

Unifly provides two primary interfaces for managing UniFi infrastructure directly from the terminal, eliminating the need for the web dashboard:

• unifly <command>: A CLI designed for scripting, automation, and quick lookups.
• unifly tui: A real-time terminal dashboard for monitoring network status.

Both interfaces are powered by a shared async engine that automatically handles routing, authentication, and data merging across different UniFi API dialects.

The unifly-audit tool performs a security-focused audit of your UniFi configuration. It identifies vulnerabilities such as open WiFi networks, permissive firewall rules, outdated device firmware, and network isolation issues. Findings are categorized by severity levels:

• CRITICAL: Open WiFi networks, no firewall between zones.
• HIGH: WPA2-only networks, allow-all firewall rules, no logging.
• MODERATE: Outdated firmware, unused networks.
• INFO: Network isolation status, device counts.

The unifly-api crate provides an async Rust client for communicating with Ubiquiti UniFi Network controllers via two distinct API surfaces:

1. Integration API: A RESTful OpenAPI-based interface. It uses X-API-KEY header authentication and is the primary surface for CRUD operations on managed entities like devices, clients, networks, and firewall rules.
2. Session API: Authenticated via session cookies and CSRF tokens (under /proxy/network/api/ and /proxy/network/v2/api/), or via X-API-KEY on UniFi OS session HTTP. This surface provides access to events, traffic stats, Wi-Fi observability, DPI, admin users, system info, switch port management, firewall groups, site settings, and the WebSocket event stream.

When using the unifly-api library, you can choose between two connection modes depending on your use case:

1. Controller::connect(): Use this for long-running applications (like a TUI). It manages the full lifecycle, including background data refreshes and real-time WebSocket event handling.
2. Controller::oneshot(): Use this for short-lived tasks (like a CLI command). It is a "fire-and-forget" mode that does not spawn background refresh tasks.

unifly provides several advanced features for UniFi management:

• Dual-API enrichment: Merges data from the Integration and Session APIs. This is useful because certain data (like client bytes, hostnames, and uplink MACs) only exists in the Session API, while configuration CRUD requires the Integration API.
• Real-time event streaming: Use unifly events watch to stream live events over WebSockets (requires session or hybrid mode).
• Firewall policy reordering: Use reorder --get and reorder --set for deterministic, round-trippable ordering of firewall rules.
• Raw API access: Use unifly api as an escape hatch to call endpoints not explicitly wrapped by the CLI.
• Multi-profile management: Use the -p flag (e.g., -p home, -p office) to manage multiple controllers from a single CLI instance.

Unifly is composed of two main parts:

1. unifly: The single binary containing both the CLI and the TUI.
2. unifly-api: A library crate available on crates.io for Rust developers.

If you are building custom integrations in Rust, you should use the unifly-api crate. The library manages the following components:

• Integration Client: Handles REST + API Key.
• Session Client: Handles Cookie + CSRF.
• WebSocket: Handles Live Events.
• DataStore: Uses DashMap and watch channels for state management.

When a setting is requested, unifly resolves the value using the following priority (highest to lowest):

1. CLI flags (e.g., --controller, --site, -o json)
2. Environment variables (e.g., UNIFI_URL, UNIFI_API_KEY)
3. Profile config (the specific [profiles.<name>] section in config.toml)
4. Default values (the [defaults] section in config.toml, then built-in defaults)

Special Resolution Rules

• Timeout: Resolves via Flag $\rightarrow$ Env $\rightarrow$ Profile timeout $\rightarrow$ [defaults].timeout $\rightarrow$ Built-in (30s).
• TLS/Insecure: An explicit insecure = true (via flag, env, or profile) skips verification. If not explicitly set, a profile's ca_cert takes precedence over [defaults].insecure = true. Passing --insecure=false forces verification regardless of configuration.

The library is organized into several layers that work together to provide a reactive data experience:

• Controller: The main entry point that routes requests and manages the lifecycle.
• Clients: IntegrationClient (REST + API Key) and SessionClient (Cookie + CSRF) handle the actual communication with the UniFi controller.
• WebSocket: Provides live event updates.
• DataStore: Uses DashMap and watch channels to store entities in a lock-free manner.
• EntityStream<T>: Provides reactive subscriptions. Use .current() for a snapshot and .changed() to await updates. .changed() returns None when the controller disconnects.

Select the appropriate client based on your application's requirements:

The cloud connector only proxies the Integration API. Features that require a direct connection to the controller (Session-backed features) will not work in cloud mode. These include:

• events list / events watch and live event streams.
• stats (historical reports) and DPI status/control.
• Device commands (e.g., restart, adopt, locate, upgrade, speedtest).
• Switch port configuration, firewall groups, NAT, and site settings.
• The Session-backed VPN surface.
• Admin management and backups.

To use these features, you must use a direct profile (integration, session, or hybrid) from a network that has a direct path to the controller. You can switch between profiles per-command using the -p flag.