https://github.com/hyperb1iss/unifly

Elegant UniFi network management CLI & TUI — built with Rust
https://github.com/hyperb1iss/unifly

cli networking ratatui rust terminal tui ubiquiti unifi

Last synced: 3 months ago
JSON representation

Elegant UniFi network management CLI & TUI — built with Rust

Host: GitHub
URL: https://github.com/hyperb1iss/unifly
Owner: hyperb1iss
License: apache-2.0
Created: 2026-02-13T17:33:45.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-04-01T00:02:32.000Z (3 months ago)
Last Synced: 2026-04-03T06:29:42.338Z (3 months ago)
Topics: cli, networking, ratatui, rust, terminal, tui, ubiquiti, unifi
Language: Rust
Homepage: https://hyperb1iss.github.io/unifly/
Size: 2.56 MB
Stars: 12
Watchers: 0
Forks: 5
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md

Awesome Lists containing this project

fucking-awesome-rust - hyperb1iss/unifly - CLI and TUI for managing Ubiquiti UniFi network controllers with dual-API coverage and a 10-screen Ratatui dashboard [![CI](https://github.com/hyperb1iss/unifly/actions/workflows/cicd.yml/badge.svg)](https://github.com/hyperb1iss/unifly/actions/workflows/cicd.yml) (Applications / System tools)
awesome-unifi - hyperb1iss/unifly - Rust CLI and TUI for managing UniFi controllers via dual Integration and Legacy APIs with real-time WebSocket events. (Controller & Management / Ruby)
awesome-rust - hyperb1iss/unifly - CLI and TUI for managing Ubiquiti UniFi network controllers with dual-API coverage and a 10-screen Ratatui dashboard [![CI](https://github.com/hyperb1iss/unifly/actions/workflows/cicd.yml/badge.svg)](https://github.com/hyperb1iss/unifly/actions/workflows/cicd.yml) (Applications / System tools)
awesome-rust-with-stars - hyperb1iss/unifly - API coverage and a 10-screen Ratatui dashboard | 2026-04-14 | (Applications / System tools)
awesome-ratatui - unifly - CLI and TUI for managing Ubiquiti UniFi network controllers with an 8-screen dashboard, live traffic charts, and dual-API coverage. (💻 Apps / 🌐 Networking and Internet)

README

          


  


  🌐 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 26 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.

> _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](skills/unifly/SKILL.md): 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:

>

> ```bash

> 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](#-install).

---

## ✦ Features

| Capability | What You Get |

| --- | --- |

| 🔮 **Dual API Engine** | Integration API (REST, API key) + Session API (session, cookie/CSRF) with automatic Hybrid negotiation |

| ⚡ **Real-Time TUI** | 10-screen dashboard with area-fill traffic charts, CPU/MEM gauges, live client counts, zoomable topology |

| 🦋 **26 Top-Level Commands** | Devices, clients, networks, WiFi, firewall policies, zones, ACLs, NAT, DNS, VPN, DPI, RADIUS, topology, raw API passthrough, `tui`... |

| 💎 **Flexible Output** | Table, JSON, compact JSON, YAML, and plain text. Pipe-friendly for scripting |

| 🔒 **Secure Credentials** | OS keyring storage for API keys and passwords, with plaintext config support when you choose it |

| 🌐 **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](https://crates.io/crates/opaline). Token-based theming across CLI and TUI with ANSI fallback |

---

## ⚡ Install

### Linux / macOS

```bash

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

```

### Windows (PowerShell)

```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](https://github.com/hyperb1iss/unifly/releases/latest) |

---

## 🔮 Quick Start

Run the interactive setup wizard:

```bash

unifly config init

```

The wizard walks you through controller URL, authentication method, and site selection. Credentials can be stored in your OS keyring or saved in plaintext config, depending on the option you choose.

Once configured:

```bash

unifly devices list          # All adopted devices

unifly clients list          # Connected clients

unifly networks list         # VLANs and subnets

unifly events watch          # Live event feed (requires session auth or Hybrid)

```

```

 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, and `events list`.

```bash

unifly config init                     # Select "API Key" during setup

unifly --api-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.

```bash

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.

### 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 clients and DHCP reservations |

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

| `nat` | | Manage NAT policies (masquerade, SNAT, DNAT) |

| `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 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  --help` for details.

### Global Flags

```

-p, --profile      Controller profile to use

-c, --controller    Controller URL (overrides profile)

-s, --site         Site name or UUID

-o, --output     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      Request timeout (default: 30)

    --color        Color: auto, always, never

```

### Shell Completions

```bash

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

```bash

unifly tui                   # Launch with default profile

unifly tui -p office         # Use a specific profile

unifly tui -k                # Accept self-signed TLS certs

```



  



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



  

  



Full keybinding reference and screen details in the [TUI documentation](https://hyperb1iss.github.io/unifly/reference/tui).

---

## 🏗️ 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](https://crates.io/crates/unifly-api) |

| **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](https://hyperb1iss.github.io/unifly/architecture/)

---

## ⚙️ Configuration

```bash

unifly config init             # Interactive 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](https://hyperb1iss.github.io/unifly/guide/configuration)

---

## 📦 Library

[![unifly-api](https://img.shields.io/crates/v/unifly-api.svg)](https://crates.io/crates/unifly-api) · Async HTTP/WebSocket transport, high-level Controller, reactive DataStore, domain models

```rust

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](https://docs.rs/unifly-api). Usage guide with more examples: [Library documentation](https://hyperb1iss.github.io/unifly/reference/library)

---

## 🤖 AI Agent Skill

### Install Options

```bash

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 |

---

## 🦋 Development

### Prerequisites

- Rust 1.94+ (edition 2024)

- A UniFi Network controller (Cloud Key, Dream Machine, or self-hosted)

### Build

```bash

git clone https://github.com/hyperb1iss/unifly.git

cd unifly

cargo build --workspace

```

### Test & Lint

```bash

cargo test --workspace

cargo clippy --workspace --all-targets

```

### Run

```bash

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](LICENSE)

---



  

    

  

   

  

    

  





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

    



    ✦ Built with obsession by Hyperbliss Technologies ✦}

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/hyperb1iss/unifly

Awesome Lists containing this project

README

🌐 unifly