Fish

May 5, 2026 · View on GitHub

🌐 unifly

Your UniFi Network, at Your Fingertips
_{✦ CLI + TUI for UniFi Network Controllers ✦}

Features • Install • Quick Start • CLI • TUI • Architecture • Library • AI Agent Skill • Development

unifly TUI animated tour — Dashboard, Devices, Clients, Firewall, Topology, and Stats screens

💜 What is unifly?

A complete command-line toolkit for managing Ubiquiti UniFi network controllers. One binary with 28 top-level commands for scripting and a built-in TUI dashboard for real-time monitoring, powered by a shared async engine that speaks every UniFi API dialect, including Site Manager cloud fleet APIs and the cloud connector.

Manage devices, monitor clients, inspect VLANs, stream events, and watch bandwidth charts, all without leaving your terminal.

UniFi controllers expose multiple APIs with different capabilities. unifly unifies them all into a single, coherent interface so you never have to think about which endpoint to hit.

🤖 AI Agent? 👤 Human? Both Welcome.

unifly speaks fluent silicon and carbon.

Coding agents get a dedicated skill bundle: full CLI reference, automation workflows, and a ready-made network manager agent that can provision VLANs, audit firewalls, and diagnose connectivity without asking permission for every command. One command to install:
npx skills add hyperb1iss/unifly
Humans get a gorgeous 10-screen TUI, shell completions, pipe-friendly output, and the quiet satisfaction of never opening the UniFi web UI again. Keep scrolling to Install.

✦ Features

Capability	What You Get
🔮 Triple-Path API Engine	Integration API + Session API via a single API key on UniFi OS, plus Site Manager cloud fleet and connector support. Hybrid mode adds WebSocket for live event streaming
⚡ Real-Time TUI	10-screen dashboard with area-fill traffic charts, CPU/MEM gauges, live client counts, zoomable topology
🦋 28 Top-Level Commands	Devices and switch port config-as-code, clients, networks, WiFi, firewall policies/zones/groups, ACLs, NAT, DNS, full VPN surface, DPI, RADIUS, site settings, topology, cloud fleet, raw API passthrough, `tui`...
📡 Wi-Fi Observability	Neighboring APs, regulatory channels, per-client Wi-Fi experience scores, roam timelines
💎 Flexible Output	Table, JSON, compact JSON, YAML, and plain text. Pipe-friendly for scripting
🔒 Secure Credentials	OS keyring storage for API keys and passwords by default. Explicit `api_key` / `password` in TOML config wins when set, useful for headless or shared machines.
🌐 Multi-Profile	Named profiles for multiple controllers. Switch with a single flag
🧠 Smart Config	Interactive wizard, environment variables, TOML config, CLI overrides
📡 WebSocket Events	Live event streaming with 10K rolling buffer, severity filtering, pause/scroll-back
📊 Historical Stats	WAN bandwidth area fills, client counts, DPI app/category breakdown (1h to 30d)
🎨 SilkCircuit Theme	Neon-on-dark color palette powered by opaline. Token-based theming across CLI and TUI with ANSI fallback

⚡ Install

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/unifly/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/hyperb1iss/unifly/main/install.ps1 | iex

Other Methods

Method	Command
Homebrew	`brew install hyperb1iss/tap/unifly`
AUR	`yay -S unifly-bin`
Cargo	`cargo install --git https://github.com/hyperb1iss/unifly.git unifly`
Binary	Download from GitHub Releases

🔮 Quick Start

Run the interactive setup wizard:

unifly config init            # Local controller
unifly config cloud-setup     # Site Manager / cloud controller

The local wizard walks you through controller URL, authentication method, and site selection. The cloud wizard validates your Site Manager API key, lets you pick a console by name, discovers its sites, and writes a ready-to-use cloud profile. Credentials can be stored in your OS keyring, referenced from UNIFI_API_KEY, or saved in plaintext config, depending on the path you choose.

Once configured:

unifly devices list              # All adopted devices
unifly devices ports my-switch   # Live port states with connected clients
unifly clients list              # Connected clients
unifly networks list             # VLANs and subnets
unifly wifi neighbors            # Nearby APs your radios can see
unifly clients wifi 10.0.0.42    # Per-client Wi-Fi experience score
unifly events watch              # Live event feed (requires Hybrid auth)
unifly cloud hosts               # Consoles visible through Site Manager
unifly cloud switch default      # Re-target the active cloud profile to another site

 ID                                   | Name            | Model           | Status
--------------------------------------+-----------------+-----------------+--------
 a1b2c3d4-e5f6-7890-abcd-ef1234567890 | Office Gateway  | UDM-Pro         | ONLINE
 b2c3d4e5-f6a7-8901-bcde-f12345678901 | Living Room AP  | U6-LR           | ONLINE
 c3d4e5f6-a7b8-9012-cdef-123456789012 | Garage Switch   | USW-Lite-8-PoE  | ONLINE

🔐 Authentication

API Key (recommended)

Generate a key on your controller under Settings > Integrations. On UniFi OS controllers, the same key also authenticates session HTTP endpoints, so API key mode covers most CLI automation: CRUD, device commands, stats, DHCP reservations, admin operations, Wi-Fi observability (wifi neighbors, wifi channels, clients roams, clients wifi), and events list.

unifly config init                     # Select "API Key" during setup
unifly --api-key <KEY> devices list    # Or pass directly

Live WebSocket features still need a session cookie, so events watch requires Username/Password or Hybrid.

Username / Password

Session-based auth with cookie and CSRF token handling. Use this when you need live WebSocket features (events watch) or when your controller does not accept API keys on session HTTP endpoints.

unifly config init                     # Select "Username/Password" during setup

Hybrid Mode

Best of both worlds: API key for Integration API plus session HTTP, and username/password for the WebSocket cookie session. Choose this when you want full live monitoring plus maximum compatibility.

Cloud / Site Manager

Use auth_mode = "cloud" when the controller is only reachable through Site Manager. unifly will route Integration-backed commands through the cloud connector and can auto-resolve host_id when exactly one console, or one owner console, is visible to the API key.

unifly config cloud-setup
unifly cloud hosts
unifly cloud sites
unifly cloud switch default
unifly --profile cloud-home networks list

If the API key can see more than one console, unifly cloud ... still works without host_id, but controller-bound commands such as devices list need a saved host_id or a unique auto-resolution path. unifly cloud switch <site> updates the active cloud profile's controller-side site target using the connector's site names or internal references.

Environment Variables

Variable	Description
`UNIFI_API_KEY`	Integration API key
`UNIFI_HOST_ID`	Site Manager console/host ID for cloud connector mode
`UNIFI_URL`	Controller URL
`UNIFI_PROFILE`	Profile name
`UNIFI_SITE`	Site name or UUID
`UNIFI_OUTPUT`	Default output format
`UNIFI_INSECURE`	Accept self-signed TLS certs
`UNIFI_TIMEOUT`	Request timeout (seconds)

💻 CLI

Commands

Command	Alias	Description
`acl`		Manage ACL rules
`admin`		Administrator management
`alarms`		Manage alarms
`clients`	`cl`	Manage clients and DHCP reservations
`cloud`		Query Site Manager hosts, sites, devices, ISP metrics, SD-WAN, and switch the active cloud site
`completions`		Generate shell completions
`config`		Manage CLI configuration
`countries`		List available country codes
`devices`	`dev`, `d`	Manage adopted and pending devices, plus switch port config-as-code (`ports`, `ports-export`, `port-set`)
`dns`		Manage DNS policies (local records)
`dpi`		DPI reference data
`events`		View and stream events
`firewall`	`fw`	Manage firewall policies, zones, and groups (port / address / ipv6-address)
`nat`		Manage NAT policies (masquerade, SNAT, DNAT)
`hotspot`		Manage hotspot vouchers
`networks`	`net`, `n`	Manage networks and VLANs
`radius`		View RADIUS profiles
`settings`		View and modify site-level settings (Session API)
`sites`		Manage sites
`stats`		Query statistics and reports
`system`	`sys`	System operations and info
`topology`	`topo`	Show network topology tree
`traffic-lists`		Manage traffic matching lists
`vpn`		View VPN inventory, session site-to-site, remote-access, and client records, OpenVPN helpers, VPN connections, WireGuard peers, magic site-to-site configs, and VPN settings
`wans`		View WAN interfaces
`wifi`	`w`	Manage WiFi broadcasts (SSIDs)
`api`		Raw API passthrough (GET/POST/PUT/PATCH/DELETE to any endpoint)
`tui`		Launch the real-time terminal dashboard

Most resource groups support list and get; some also expose create, update, delete, patch, or specialized actions. Run unifly <command> --help for details.

Cloud note: unifly cloud ... talks directly to Site Manager and does not require a controller connection. Session-only commands such as events watch still need direct Session API access.

Global Flags

-p, --profile <NAME>     Controller profile to use
-c, --controller <URL>   Controller URL (overrides profile)
-s, --site <SITE>        Site name or UUID
-o, --output <FORMAT>    Output: table, json, json-compact, yaml, plain
-k, --insecure           Accept self-signed TLS certificates
-v, --verbose            Increase verbosity (-v, -vv, -vvv)
-q, --quiet              Suppress non-error output
-y, --yes                Skip confirmation prompts
    --timeout <SECS>     Request timeout (default: 30)
    --color <MODE>       Color: auto, always, never

Shell Completions

# Bash
unifly completions bash > ~/.local/share/bash-completion/completions/unifly

# Zsh
unifly completions zsh > ~/.zfunc/_unifly

# Fish
unifly completions fish > ~/.config/fish/completions/unifly.fish

# PowerShell
unifly completions powershell | Out-String | Invoke-Expression

🖥️ TUI

unifly tui launches a 10-screen real-time dashboard for monitoring and managing your network.

unifly tui                   # Launch with default profile
unifly tui -p office         # Use a specific profile
unifly tui -k                # Accept self-signed TLS certs

Cloud profiles can launch the TUI for a single connector-backed console. Fleet aggregation, Site Manager host switching, and Session-only live features are still outside the TUI surface today.

unifly TUI — Dashboard screen with WAN traffic chart, gateway info, CPU/MEM gauges, top clients, and recent events

Screen	Highlights
Dashboard	btop-style overview: WAN traffic chart, gateway info, CPU/MEM gauges, top clients, recent events
Devices	Model, firmware, uptime, CPU/MEM. 5-tab detail panel. Restart, locate, upgrade
Clients	Signal, traffic, VLAN. Filter by type. Block/unblock/kick
Networks	VLAN topology with inline edit overlay for live config changes
Firewall	Policies, zones, ACL, NAT across four sub-tabs with drag reordering
Topology	Zoomable network tree with pan, zoom, fit-to-view
Events	Live WebSocket stream with 10K buffer, pause, severity filtering
Stats	WAN bandwidth, client counts, DPI breakdown (1h/24h/7d/30d)
Settings	Profile switching, theme selector, display preferences
Onboarding	First-run setup wizard

✦ Gallery

Devices — model, firmware, uptime, and live CPU/MEM

unifly TUI — Devices screen with status, model, firmware, uptime, and CPU/MEM columns

Clients — all clients (left) and wireless-only filter (right)

unifly TUI — Clients screen, all clients unifly TUI — Clients screen, wireless filter

Wi-Fi observability — per-client experience, signal, AP, TX/RX

unifly TUI — Wi-Fi screen Clients tab with AP, signal, health, and TX/RX

Firewall — policies, zones, ACL, and NAT across four sub-tabs

unifly TUI — Firewall screen showing policies and zones

Topology — full view (left) and zoomed-in detail (right)

unifly TUI — Topology screen, fit-to-view

Stats — 1 hour, 7 days, and 30 days of WAN bandwidth, clients, and DPI

unifly TUI — Stats screen, 1 hour window unifly TUI — Stats screen, 7 day window unifly TUI — Stats screen, 30 day window

Help overlay — every keybinding at a glance

unifly TUI — Help overlay listing all keybindings

Full keybinding reference and screen details in the TUI documentation.

🏗️ Architecture

Two crates, clean dependency chain:

Crate	Purpose
unifly-api	Async HTTP/WebSocket client, Controller lifecycle, reactive DataStore (`DashMap` + `tokio::watch`), entity models. Published on crates.io
unifly	Single binary: CLI commands + `unifly tui` dashboard via feature flags, profile/keyring config, 10-screen ratatui dashboard with SilkCircuit theme

Deep dive: Architecture documentation

⚙️ Configuration

unifly config init             # Local controller setup wizard
unifly config cloud-setup      # Site Manager cloud setup wizard
unifly config profiles         # List profiles (* marks active)
unifly config use office       # Switch default profile
unifly -p home devices list    # One-off override

Named profiles for multiple controllers, OS keyring credential storage, environment variable overrides, and TOML config files. Full details: Configuration guide

📦 Library

· Async HTTP/WebSocket transport, high-level Controller, reactive DataStore, domain models

use unifly_api::{Controller, ControllerConfig, AuthCredentials, TlsVerification};
use secrecy::SecretString;

let config = ControllerConfig {
    url: "https://192.168.1.1".parse()?,
    auth: AuthCredentials::ApiKey(SecretString::from("your-api-key")),
    tls: TlsVerification::DangerAcceptInvalid,
    ..Default::default()
};
let controller = Controller::new(config);
controller.connect().await?;

let devices = controller.devices_snapshot();
println!("Found {} devices", devices.len());

Full API docs on docs.rs/unifly-api. Usage guide with more examples: Library documentation

🤖 AI Agent Skill

Install Options

npx skills add hyperb1iss/unifly                    # Claude Code, Cursor, Copilot, Codex, Gemini, ...
npx skills add hyperb1iss/unifly -a claude-code     # Target a specific agent
/plugin marketplace add hyperb1iss/unifly           # As a Claude Code plugin

What's Included

Component	Description
unifly skill	Complete CLI reference, command patterns, output formats, automation tips
Network Manager agent	Autonomous agent for provisioning, diagnostics, and security audits
Reference docs	Command reference, UniFi networking concepts, workflow patterns

unifly is indy open source. No VC, no telemetry, no upsells. Built by @hyperb1iss on real UniFi hardware, with help from a growing list of contributors. Polished until the TUI sings.

If it saved you a trip to the web UI today, sponsorship is what keeps the polish coming: new screens, deeper API coverage, faster releases.

🦋 Development

Prerequisites

Rust 1.94+ (edition 2024)
A UniFi Network controller (Cloud Key, Dream Machine, or self-hosted)

Build

git clone https://github.com/hyperb1iss/unifly.git
cd unifly
cargo build --workspace

Test & Lint

cargo test --workspace
cargo clippy --workspace --all-targets

Run

cargo run -p unifly -- devices list
cargo run -p unifly -- tui

Workspace Layout

crates/
  unifly-api/      # Library: HTTP/WS transport, Controller, DataStore, domain models
  unifly/          # Single binary: CLI commands + tui subcommand, config, profiles

Lint Policy

Pedantic clippy with unsafe_code = "forbid". See Cargo.toml workspace lints for the full configuration. It's opinionated and we like it that way.

⚖️ License

Apache-2.0. See LICENSE

_{If unifly keeps your network running smooth, sponsor the project or give it a ⭐

✦ Built with obsession by Hyperbliss Technologies ✦}