🌐 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

💜 What is unifly?

A complete command-line toolkit for managing Ubiquiti UniFi network controllers. One binary with 23 CLI 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.

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. It also ships as an AI agent skill, so your coding assistant can manage your network infrastructure too.

✦ Features

Capability	What You Get
🔮 Dual API Engine	Integration API (REST, API key) + Legacy API (session, cookie/CSRF) with automatic Hybrid negotiation
⚡ Real-Time TUI	8-screen dashboard with area-fill traffic charts, CPU/MEM gauges, live client counts, zoomable topology
🦋 23 Resource Commands	Devices, clients, networks, WiFi, firewall policies, zones, ACLs, DNS, VPN, hotspot vouchers, DPI, RADIUS, topology...
💎 Flexible Output	Table, JSON, compact JSON, YAML, and plain text. Pipe-friendly for scripting
🔒 Secure Credentials	OS keyring storage for API keys and passwords. Nothing in plaintext
🌐 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

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

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

The wizard walks you through controller URL, authentication method, and site selection. Credentials are stored in your OS keyring, never written to disk in plaintext.

Once configured:

unifly devices list          # All adopted devices
unifly clients list          # Connected clients
unifly networks list         # VLANs and subnets
unifly events watch          # Live event feed

 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. Full CRUD access via the Integration API.

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

Username / Password

Legacy session-based auth with cookie and CSRF token handling. Required for events, statistics, and device commands not yet in the Integration API.

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

Hybrid Mode

Best of both worlds: API key for Integration API CRUD, username/password for Legacy API features. The wizard offers this when both are available.

Environment Variables

Variable	Description
`UNIFI_API_KEY`	Integration API key
`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 connected clients
`completions`		Generate shell completions
`config`		Manage CLI configuration
`countries`		List available country codes
`devices`	`dev`, `d`	Manage adopted and pending devices
`dns`		Manage DNS policies (local records)
`dpi`		DPI reference data
`events`		View and stream events
`firewall`	`fw`	Manage firewall policies and zones
`hotspot`		Manage hotspot vouchers
`networks`	`net`, `n`	Manage networks and VLANs
`radius`		View RADIUS profiles
`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 servers and tunnels
`wans`		View WAN interfaces
`wifi`	`w`	Manage WiFi broadcasts (SSIDs)

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

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

🖥️ TUI

The unifly tui subcommand launches a real-time terminal dashboard for monitoring and managing your UniFi network. Eight screens cover everything from live bandwidth charts to firewall policy management.

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

Screens

Navigate with number keys 1–8 or Tab/Shift+Tab:

Key	Screen	Description
`1`	Dashboard	btop-style overview: area-fill WAN traffic chart, gateway info, connectivity health, CPU/MEM bars, networks with IPv6, WiFi AP experience, top clients, recent events
`2`	Devices	Adopted devices with model, IP, CPU/MEM, TX/RX, uptime. 5-tab detail panel (Overview, Performance, Radios, Clients, Ports)
`3`	Clients	Connected clients: hostname, IP, MAC, VLAN, signal bars, traffic. Filterable by type (All/Wireless/Wired/VPN/Guest)
`4`	Networks	VLAN topology: subnets, DHCP, IPv6, gateway type. Inline edit overlay for live config changes
`5`	Firewall	Policies, zones, and ACL rules across three sub-tabs with visual rule reordering
`6`	Topology	Zoomable network topology tree: gateway → switches → APs, color-coded by type and state
`7`	Events	Live event stream with 10K rolling buffer. Pause, scroll back, severity color-coding
`8`	Stats	Historical charts: WAN bandwidth area fills, client counts, DPI app/category breakdown (1h/24h/7d/30d)

Dashboard

The dashboard packs eight live panels into a dense, information-rich overview:

WAN Traffic · Area-fill chart with Braille line overlay, live TX/RX rates, peak tracking
Gateway · Model, firmware, WAN IP, IPv6, DNS, ISP, latency, uptime
Connectivity · Subsystem status dots (WAN/WWW/WLAN/LAN/VPN), aggregate traffic bars
Capacity · Color-coded CPU/MEM gauges, load averages, device/client fleet summary
Networks · VLANs sorted by ID with IPv6 prefix delegation and SLAAC mode
WiFi / APs · Client count, WiFi experience %, channel info per access point
Top Clients · Proportional traffic bars with fractional block characters
Recent Events · Two-column compact event display, color-coded by severity

Devices & Clients

Networks & Firewall

Stats

Historical statistics with selectable time windows and dual-API data sourcing:

WAN Bandwidth · TX/RX area fills with Braille line overlay, auto-scaling axes
Client Count · Braille line chart tracking connected clients over time
Top Applications · DPI application breakdown with proportional bars (Integration API names, Legacy fallback)
Traffic by Category · Percentage bars for streaming, gaming, social, etc.

Key Bindings

Global

Key	Action
`1`–`8`	Jump to screen
`Tab` / `Shift+Tab`	Next / previous screen
`j` / `k` / `↑` / `↓`	Navigate up / down
`g` / `G`	Jump to top / bottom
`Ctrl+d` / `Ctrl+u`	Page down / up
`Enter`	Select / expand detail
`Esc`	Close detail / go back
`/`	Search
`?`	Help overlay
`,`	Settings
`q`	Quit

Screen-Specific

Screen	Key	Action
Devices	`R`	Restart device
Devices	`L`	Locate (flash LED)
Devices (detail)	`h` / `l`	Previous / next detail tab
Clients	`Tab`	Cycle filter (All → Wireless → Wired → VPN → Guest)
Clients	`b` / `B`	Block / unblock client
Clients	`x`	Kick client
Networks	`e`	Edit selected network
Firewall	`h` / `l`	Cycle sub-tabs (Policies / Zones / ACL Rules)
Firewall	`K` / `J`	Reorder policy up / down
Topology	`←` `→` `↑` `↓`	Pan canvas
Topology	`+` / `-`	Zoom in / out
Topology	`f`	Fit to view
Events	`Space`	Pause / resume live stream
Stats	`h` `d` `w` `m`	Period: 1h / 24h / 7d / 30d
Stats	`r`	Refresh

🏗️ Architecture

Two crates, clean dependency chain:

  unifly (CLI + TUI binaries)
       │
       ▼
  unifly-api (library)
  ├── HTTP/WS transport
  ├── Controller lifecycle
  ├── Reactive DataStore
  └── Domain models

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, clap command routing, 8-screen ratatui dashboard with SilkCircuit theme

Data Flow

Controller URL ──▶ Integration API ──▶ REST (API key auth)
                   Legacy API ────────▶ REST (cookie + CSRF)
                   WebSocket ─────────▶ Push events

                         │
                         ▼
                    Controller
                   ┌──────────┐
                   │ DataStore │ ◀── DashMap + watch channels
                   │ Refresh   │ ◀── Background polling (30s)
                   │ Commands  │ ◀── Action channel (mpsc)
                   └──────────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
           CLI out    TUI render  Event stream

The Controller (in unifly-api) wraps Arc<ControllerInner> for cheap cloning across async tasks. EntityStream<T> wraps tokio::watch::Receiver for reactive subscriptions so the TUI receives updates without polling.

⚙️ Configuration

Config lives at ~/.config/unifly/config.toml:

default_profile = "home"

[defaults]
output = "table"
color = "auto"
insecure = false
timeout = 30

[profiles.home]
controller = "https://192.168.1.1"
site = "default"
auth_mode = "hybrid"
# API key + password stored in OS keyring

[profiles.office]
controller = "https://10.0.0.1"
site = "default"
auth_mode = "legacy"
username = "admin"
insecure = true

unifly config init             # Interactive setup
unifly config use office       # Switch active profile
unifly config profiles         # List profiles (* marks active)
unifly --profile home devices  # One-off override

📦 Library

The engine is published on crates.io. Use it to build your own UniFi tools, integrations, or automations in Rust.

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

Quick Start

Low-level API access · talk directly to the controller:

use unifly_api::{IntegrationClient, TransportConfig, TlsMode, ControllerPlatform};
use secrecy::SecretString;

let transport = TransportConfig::new(TlsMode::DangerAcceptInvalid);
let client = IntegrationClient::from_api_key(
    "https://192.168.1.1",
    &SecretString::from("your-api-key"),
    &transport,
    ControllerPlatform::UnifiOs,
)?;
let devices = client.list_devices("default").await?;

High-level Controller · reactive streams, automatic refresh, data merging:

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

let config = ControllerConfig {
    base_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().current();
println!("Found {} devices", devices.len());

Full API documentation on docs.rs/unifly-api.

🤖 AI Agent Skill

unifly ships an AI agent skill that teaches coding assistants how to manage UniFi infrastructure. It includes a comprehensive CLI reference, automation workflows, and an autonomous network manager agent.

Install via npx (Vercel Skills)

Works with Claude Code, Cursor, Copilot, Codex, Gemini, and more:

npx skills add hyperb1iss/unifly

Target a specific agent:

npx skills add hyperb1iss/unifly -a claude-code
npx skills add hyperb1iss/unifly -a cursor
npx skills add hyperb1iss/unifly -a copilot

Install via Claude Code Plugin

/plugin marketplace add hyperb1iss/unifly

Manual Installation

git clone https://github.com/hyperb1iss/unifly.git
ln -s $(pwd)/unifly ~/.claude/plugins/unifly

What's Included

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

The skill enables agents to create VLANs, manage firewall policies, provision WiFi, diagnose connectivity issues, generate guest vouchers, and more, all through the unifly CLI.

🦋 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 -- -D warnings

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 ✦}

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.cargo		.cargo
.claude-plugin		.claude-plugin
.github		.github
agents		agents
aur		aur
commands		commands
crates		crates
docs		docs
skills/unifly		skills/unifly
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
clippy.toml		clippy.toml
deny.toml		deny.toml
install.sh		install.sh
justfile		justfile
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Folders and files

Latest commit

History

Repository files navigation

🌐 unifly

💜 What is unifly?

✦ Features

⚡ Install

Other Methods

🔮 Quick Start

🔐 Authentication

API Key (recommended)

Username / Password

Hybrid Mode

Environment Variables

💻 CLI

Commands

Global Flags

Shell Completions

🖥️ TUI

Screens

Dashboard

Devices & Clients

Networks & Firewall

Stats

Key Bindings

Global

Screen-Specific

🏗️ Architecture

Data Flow

⚙️ Configuration

📦 Library

Quick Start

🤖 AI Agent Skill

Install via npx (Vercel Skills)

Install via Claude Code Plugin

Manual Installation

What's Included

🦋 Development

Prerequisites

Build

Test & Lint

Run

Workspace Layout

Lint Policy

⚖️ License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages