Skip to content
Back to search

hyperb1iss

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hyperb1iss--unifly/badge.svg)](/listings/hyperb1iss--unifly)

HTML

<a href="/listings/hyperb1iss--unifly"><img src="/api/listings/hyperb1iss--unifly/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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 unifly` | | **Binary** | Download from [GitHub Releases](https://github.com/hyperb1iss/unifly/releases/latest) |

The install scripts also add the [agent skill](#-ai-agent-skill) to `~/.agents/skills` for your user (set `UNIFLY_NO_SKILL=1` to skip). Homebrew and AUR install unifly for every user and cannot write into your home directory, so after those, Cargo, or a manual download, run `unifly skill --install` yourself.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 33 lines
  1. {
  2. "name": "hyperb1iss",
  3. "owner": {
  4. "name": "Stefanie Jane",
  5. "url": "https://hyperbliss.tech"
  6. },
  7. "plugins": [
  8. {
  9. "name": "unifly",
  10. "source": "./",
  11. "description": "UniFi network management CLI, TUI, and AI agent skill for full infrastructure control",
  12. "version": "0.15.0",
  13. "author": {
  14. "name": "Stefanie Jane",
  15. "url": "https://hyperbliss.tech"
  16. },
  17. "homepage": "https://github.com/hyperb1iss/unifly",
  18. "repository": "https://github.com/hyperb1iss/unifly",
  19. "license": "Apache-2.0",
  20. "keywords": [
  21. "unifi",
  22. "unifly",
  23. "networking",
  24. "ubiquiti",
  25. "infrastructure",
  26. "automation",
  27. "firewall",
  28. "wifi"
  29. ],
  30. "category": "infrastructure"
  31. }
  32. ]
  33. }
README.md · README · 602 lines · 2 findings marked
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/static/brand/logo-stacked.svg">
  4. <img src="docs/static/brand/logo-stacked-light.svg" alt="unifly" width="360">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. Your UniFi network, at your fingertips.<br>
  9. <sub>CLI + TUI for humans and agents</sub>
  10. </p>
  11. <p align="center">
  12. <a href="https://www.rust-lang.org">
  13. <img src="https://img.shields.io/badge/Rust-1.94+-e135ff?style=for-the-badge&logo=rust&logoColor=white" alt="Rust 1.94+">
  14. </a>
  15. <a href="https://doc.rust-lang.org/edition-guide/rust-2024/index.html">
  16. <img src="https://img.shields.io/badge/Edition-2024-80ffea?style=for-the-badge&logo=rust&logoColor=0a0a0f" alt="Rust Edition 2024">
  17. </a>
  18. <a href="https://ratatui.rs">
  19. <img src="https://img.shields.io/badge/ratatui-TUI-ff6ac1?style=for-the-badge&logo=gnometerminal&logoColor=white" alt="Built with ratatui">
  20. </a>
  21. <a href="https://crates.io/crates/opaline">
  22. <img src="https://img.shields.io/badge/opaline-Theme-e135ff?style=for-the-badge&logo=rust&logoColor=white" alt="Themed with opaline">
  23. </a>
  24. <a href="https://tokio.rs">
  25. <img src="https://img.shields.io/badge/tokio-Async-f1fa8c?style=for-the-badge&logo=rust&logoColor=0a0a0f" alt="Powered by tokio">
  26. </a>
  27. <a href="LICENSE">
  28. <img src="https://img.shields.io/badge/License-Apache--2.0-50fa7b?style=for-the-badge&logo=apache&logoColor=0a0a0f" alt="License: Apache-2.0">
  29. </a>
  30. <a href="https://github.com/sponsors/hyperb1iss">
  31. <img src="https://img.shields.io/badge/Sponsor-ff6ac1?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor on GitHub">
  32. </a>
  33. </p>
  34. <p align="center">
  35. <a href="#-features">Features</a> •
  36. <a href="#-install">Install</a> •
  37. <a href="#-quick-start">Quick Start</a> •
  38. <a href="#-cli">CLI</a> •
  39. <a href="#-tui">TUI</a> •
  40. <a href="#-architecture">Architecture</a> •
  41. <a href="#-library">Library</a> •
  42. <a href="#-ai-agent-skill">AI Agent Skill</a> •
  43. <a href="#-development">Development</a>
  44. </p>
  45. https://github.com/user-attachments/assets/13042353-04f5-4934-a8dd-a516ab6a14d2
  46. ---
  47. ## 💜 What is unifly?
  48. A complete command-line toolkit for managing Ubiquiti UniFi network controllers. One binary with 29 top-level commands for scripting and a built-in TUI for real-time monitoring and hands-on management, powered by a shared async engine that speaks every UniFi API dialect, including Site Manager cloud fleet APIs and the cloud connector.
  49. > _Manage devices, monitor clients, inspect VLANs, stream events, and watch bandwidth charts, all without leaving your terminal._
  50. 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.
  51. ---
  52. > ### 🤖 AI Agent? 👤 Human? Both Welcome.
  53. >
  54. > unifly speaks fluent silicon _and_ carbon.
  55. >
  56. > **Coding agents** get a small [discovery skill](skills/unifly/SKILL.md) that loads version-matched guidance from `unifly skill`. The binary ships command discovery, automation workflows, and payload examples, all available offline. The [install scripts](#-install) add the skill to `~/.agents/skills` for you; after any other install method, one command does it:
  57. >
  58. > ```bash
  59. > unifly skill --install # --claude targets Claude Code's skills directory
  60. > ```
  61. >
  62. > `npx skills add hyperb1iss/unifly` installs the same skill without the binary, but agents still need the binary to load the guide. Older binaries without `unifly skill` need an update before they can serve it.
  63. >
  64. > **Humans** get a gorgeous 11-screen TUI, shell completions, pipe-friendly output, and the quiet satisfaction of never opening the UniFi web UI again. Keep scrolling to [Install](#-install).
  65. <p align="center">
  66. <img src="docs/images/agent-claude-code.png" alt="Claude Code diagnosing the Neon Harbor demo studio network with unifly and answering with a numbered list of five fixes" width="900">
  67. </p>
  68. <p align="center">
  69. <sub>Claude Code loads the unifly skill, works the <code>--demo-fleet</code> studio network with read-only commands and <code>jq</code>, and comes back with a punch list.</sub>
  70. </p>
  71. ---
  72. ## ✦ Features
  73. | Capability | What You Get |
  74. | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  75. | 🔮 **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 |
  76. | ⚡ **Real-Time TUI** | 11-screen dashboard and network client: SilkCircuit octant traffic charts, zoomable topology, graphics-protocol charts (Kitty/Sixel/iTerm2), plus device, client, network, firewall, and SSID management |
  77. | 🦋 **29 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`... |
  78. | 📡 **Wi-Fi Observability** | Neighboring APs, regulatory channels, per-client Wi-Fi experience scores, roam timelines |
  79. | 💎 **Flexible Output** | Table, JSON, compact JSON, YAML, and plain text. Pipe-friendly for scripting |
  80. | 🔒 **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. |
  81. | 🌐 **Multi-Profile** | Named profiles for multiple controllers. Switch with a single flag |
  82. | 🧠 **Smart Config** | Interactive wizard, environment variables, TOML config, CLI overrides |
  83. | 📡 **WebSocket Events** | Live event streaming with 10K rolling buffer, category filtering and search, pause/scroll-back, older history, and alarms |
  84. | 📊 **Historical Stats** | WAN bandwidth area fills, client counts, DPI app/category breakdown (1h to 30d) |
  85. | 🎨 **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 |
  86. ---
  87. ## ⚡ Install
  88. ### Linux / macOS
  89. ```bash
  90. curl -fsSL https://raw.githubusercontent.com/hyperb1iss/unifly/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 110 on GitHub
  91. ```
  92. ### Windows (PowerShell)
  93. ```powershell
  94. irm https://raw.githubusercontent.com/hyperb1iss/unifly/main/install.ps1 | iex
  95. ```
  96. ### Other Methods
  97. | Method | Command |
  98. | ------------ | ------------------------------------------------------------------------------------- |
  99. | **Homebrew** | `brew install hyperb1iss/tap/unifly` |
  100. | **AUR** | `yay -S unifly-bin` |
  101. | **Cargo** | `cargo install unifly` |
  102. | **Binary** | Download from [GitHub Releases](https://github.com/hyperb1iss/unifly/releases/latest) |
  103. The install scripts also add the [agent skill](#-ai-agent-skill) to `~/.agents/skills` for your user (set `UNIFLY_NO_SKILL=1` to skip). Homebrew and AUR install unifly for every user and cannot write into your home directory, so after those, Cargo, or a manual download, run `unifly skill --install` yourself.
  104. ---
  105. ## 🔮 Quick Start
  106. Run the interactive setup wizard:
  107. ```bash
  108. unifly config init # Local controller
  109. unifly config cloud-setup # Site Manager / cloud controller
  110. ```
  111. The local wizard walks you through controller URL, authentication method, and site selection, and asks whether the controller uses a self-signed certificate (defaulting yes for IPs and `.local`-style hostnames, no for public ones). 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.
  112. Once configured:
  113. ```bash
  114. unifly devices list # All adopted devices
  115. unifly devices ports my-switch # Live port states with connected clients
  116. unifly clients list # Connected clients
  117. unifly networks list # VLANs and subnets
  118. unifly firewall groups list # Port and address groups (Session API)
  119. unifly vpn servers # VPN server inventory
  120. unifly settings list # Site-level setting sections
  121. unifly wifi neighbors # Nearby APs your radios can see
  122. unifly clients wifi 10.0.0.42 # Per-client Wi-Fi experience score
  123. unifly events watch # Live event feed (requires Hybrid auth)
  124. unifly cloud hosts # Consoles visible through Site Manager
  125. unifly cloud switch default # Re-target the active cloud profile to another site
  126. ```
  127. ```
  128. ID | Name | Model | Status
  129. --------------------------------------+-----------------+-----------------+--------
  130. a1b2c3d4-e5f6-7890-abcd-ef1234567890 | Office Gateway | UDM-Pro | ONLINE
  131. b2c3d4e5-f6a7-8901-bcde-f12345678901 | Living Room AP | U6-LR | ONLINE
  132. c3d4e5f6-a7b8-9012-cdef-123456789012 | Garage Switch | USW-Lite-8-PoE | ONLINE
  133. ```
  134. Create commands print the created entity on stdout in the chosen `--output`
  135. format, so scripts capture IDs directly:
  136. ```bash
  137. NET_ID=$(unifly networks create --name lab --management switch --vlan 42 -o json | jq -r .id)
  138. ```
  139. ---
  140. ## 🔐 Authentication
  141. ### API Key (recommended)
  142. Generate a key on your controller under **Settings > Integrations**. On UniFi
  143. OS controllers, the same key also authenticates session HTTP endpoints, so API
  144. key mode covers most CLI automation: CRUD, device commands, stats, DHCP
  145. reservations, admin operations, Wi-Fi observability (`wifi neighbors`,
  146. `wifi channels`, `clients roams`, `clients wifi`), and `events list`.
  147. ```bash
  148. unifly config init # Select "API Key" during setup
  149. unifly --api-key <KEY> devices list # Or pass directly
  150. ```
  151. Live WebSocket features still need a session cookie, so `events watch`
  152. requires **Username/Password** or **Hybrid**.
  153. ### Username / Password
  154. Session-based auth with cookie and CSRF token handling. Use this when
  155. you need live WebSocket features (`events watch`) or when your controller does
  156. not accept API keys on session HTTP endpoints.
  157. ```bash
  158. unifly config init # Select "Username/Password" during setup
  159. ```
  160. ### Hybrid Mode
  161. Best of both worlds: API key for Integration API plus session HTTP, and
  162. username/password for the WebSocket cookie session. Choose this when you want
  163. full live monitoring plus maximum compatibility.
  164. ### Cloud / Site Manager
  165. Use `auth_mode = "cloud"` when the controller is only reachable through
  166. Site Manager. unifly will route Integration-backed commands through the cloud
  167. connector and can auto-resolve `host_id` when exactly one console, or one
  168. owner console, is visible to the API key.
  169. ```bash
  170. unifly config cloud-setup
  171. unifly cloud hosts
  172. unifly cloud sites
  173. unifly cloud switch default
  174. unifly --profile cloud-home networks list
  175. ```
  176. If the API key can see more than one console, `unifly cloud ...` still works
  177. without `host_id`, but controller-bound commands such as `devices list` need a
  178. saved `host_id` or a unique auto-resolution path. `unifly cloud switch <site>`
  179. updates the active cloud profile's controller-side site target using the
  180. connector's site names or internal references.
  181. ### Environment Variables
  182. | Variable | Description |
  183. | ---------------- | ---------------------------------------------------------- |
  184. | `UNIFI_API_KEY` | Integration API key |
  185. | `UNIFI_USERNAME` | Session auth username |
  186. | `UNIFI_PASSWORD` | Session auth password |
  187. | `UNIFI_HOST_ID` | Site Manager console/host ID for cloud connector mode |
  188. | `UNIFI_URL` | Controller URL |
  189. | `UNIFI_PROFILE` | Profile name |
  190. | `UNIFI_SITE` | Site name or UUID |
  191. | `UNIFI_OUTPUT` | Default output format |
  192. | `UNIFI_INSECURE` | Accept self-signed TLS certs (`false` forces verification) |
  193. | `UNIFI_TIMEOUT` | Request timeout (seconds) |
  194. | `UNIFI_TOTP` | TOTP code for MFA-enabled controllers |
  195. | `UNIFI_DEMO` | Sanitize PII in the TUI; controller CLI commands refuse it |
  196. Flags and environment variables override profile values, profiles override
  197. the `[defaults]` config section, and `[defaults]` overrides the built-in
  198. fallbacks (30-second timeout, system TLS verification). One exception:
  199. `UNIFI_USERNAME` and `UNIFI_PASSWORD` fill in only when the profile does
  200. not set its own `username`/`password`, so a profile's configured session
  201. credentials win over the environment.
  202. ---
  203. ## 💻 CLI
  204. Tables for people, JSON and plain IDs for scripts, and names that resolve wherever an ID would go:
  205. <p align="center">
  206. <img src="docs/images/cli-pipeline.png" alt="unifly CLI in a terminal: a devices table, clients per SSID from JSON piped through jq, enabled firewall policies, and a recent events table" width="900">
  207. </p>
  208. ### Commands
  209. | Command | Alias | Description |
  210. | --------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  211. | `acl` | | Manage ACL rules |
  212. | `admin` | | Administrator management |
  213. | `alarms` | | Manage alarms |
  214. | `clients` | `cl` | Manage clients and DHCP reservations |
  215. | `cloud` | | Query Site Manager hosts, sites, devices, ISP metrics, SD-WAN, and switch the active cloud site |
  216. | `completions` | | Generate shell completions |
  217. | `config` | | Manage CLI configuration |
  218. | `countries` | | List available country codes |
  219. | `devices` | `dev`, `d` | Manage adopted and pending devices, plus switch ports, LAGs, MC-LAG domains, and switch stacks |
  220. | `dns` | | Manage DNS policies (local records) |
  221. | `dpi` | | DPI reference data |
  222. | `events` | | View and stream events |
  223. | `firewall` | `fw` | Manage firewall policies, zones, and groups (port / address / ipv6-address) |
  224. | `nat` | | Manage NAT policies (masquerade, SNAT, DNAT) |
  225. | `hotspot` | | Manage hotspot vouchers |
  226. | `networks` | `net`, `n` | Manage networks and VLANs |
  227. | `radius` | | View RADIUS profiles |
  228. | `settings` | | View and modify site-level settings (Session API) |
  229. | `sites` | | Manage sites |
  230. | `stats` | | Query statistics and reports |
  231. | `system` | `sys` | System operations and info |
  232. | `topology` | `topo` | Show network topology tree |
  233. | `traffic-lists` | | Manage traffic matching lists |
  234. | `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 |
  235. | `wans` | | View WAN interfaces |
  236. | `wifi` | `w` | Manage WiFi broadcasts (SSIDs) |
  237. | `api` | | Raw API passthrough (GET/POST/PUT/PATCH/DELETE to any endpoint) |
  238. | `tui` | | Launch the real-time terminal dashboard |
  239. Most resource groups support `list` and `get`; some also expose `create`, `update`, `delete`, `patch`, or specialized actions. Run `unifly <command> --help` for details.
  240. Cloud note: `unifly cloud ...` talks directly to Site Manager and does not
  241. require a controller connection. Session-only commands such as `events watch`
  242. still need direct Session API access.
  243. ### Global Flags
  244. ```
  245. -p, --profile <NAME> Controller profile to use
  246. -c, --controller <URL> Controller URL (overrides profile)
  247. -s, --site <SITE> Site name or UUID
  248. --api-key <KEY> Integration API key
  249. -o, --output <FORMAT> Output: table, json, json-compact, yaml, plain
  250. -k, --insecure[=BOOL] Accept self-signed TLS certs (--insecure=false forces verification)
  251. --no-cache Disable session caching (forces fresh login)
  252. -v, --verbose Increase verbosity (-v, -vv, -vvv)
  253. -q, --quiet Suppress non-error output
  254. -y, --yes Skip confirmation prompts
  255. --timeout <SECS> Request timeout in seconds (default 30, profiles may override)
  256. --color <MODE> Color: auto, always, never
  257. ```
  258. ### Shell Completions
  259. ```bash
  260. # Bash
  261. unifly completions bash > ~/.local/share/bash-completion/completions/unifly
  262. # Zsh
  263. unifly completions zsh > ~/.zfunc/_unifly
  264. # Fish
  265. unifly completions fish > ~/.config/fish/completions/unifly.fish
  266. # PowerShell
  267. unifly completions powershell | Out-String | Invoke-Expression
  268. ```
  269. ---
  270. ## 🖥️ TUI
  271. `unifly tui` launches an 11-screen terminal client for monitoring and managing your network. The status bar on the last row shows the actions that work for the selected row right now, and `?` lists every key.
  272. ```bash
  273. unifly tui # Launch with default profile
  274. unifly tui -p office # Use a specific profile
  275. unifly tui -k # Accept self-signed TLS certs
  276. unifly tui --demo-fleet # Explore a synthetic studio network, no controller needed
  277. ```
  278. `--demo-fleet` (or `UNIFI_DEMO_FLEET=1`) runs the CLI and TUI against Neon Harbor Studios, an offline simulated network with 13 devices, about 140 clients, six VLANs, and live traffic, events, and a few problems to find. It never reads your config or keyring, which makes it a safe sandbox for trying the TUI or pointing an agent at unifly.
  279. Cloud profiles can launch the TUI for a single connector-backed console. Fleet
  280. aggregation, Site Manager host switching, and the screens that need a
  281. controller session (Events, Stats, WiFi observability, NAT) are still outside
  282. the TUI surface there, and each of those screens says so.
  283. <p align="center">
  284. <img src="docs/images/tui-dashboard.png" alt="unifly TUI Dashboard with a mirrored WAN traffic chart, gateway info, CPU and memory gauges, networks, Wi-Fi APs, top clients, and recent events" width="900">
  285. </p>
  286. | Screen | Highlights |
  287. | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  288. | **Dashboard** | btop-style overview: mirrored RX/TX WAN chart, gateway info, CPU/MEM gauges, top clients, events, alarm count. Keyboard focus across panels and a WAN speed test |
  289. | **Devices** | Model, firmware with update markers, clients, CPU/MEM. Filter and sort. Restart, locate, upgrade, adopt, provision, remove. Detail tabs with a switch port map, PoE control, and port rename |
  290. | **Clients** | Network, uplink AP or switch port, signal, traffic. Filter and sort. Block, kick, fixed IP, guest authorization, forget |
  291. | **Networks** | VLAN list with a detail panel. Create, edit, and delete, with a dependency check before a delete |
  292. | **Firewall** | Policies grouped by zone pair in evaluation order, plus zones, ACL, and NAT. Detail panels, enable/disable, logging, delete, and pick-up-and-move reordering |
  293. | **Topology** | Zoomable network tree with pan, zoom, fit-to-view, and a device cursor that opens the device |
  294. | **Events** | Live stream with an events-by-hour heatmap, 10K buffer, pause, category filter, search, event detail, older history, and an alarms view with archive |
  295. | **Stats** | WAN bandwidth, client counts, DPI breakdown (1h/24h/7d/30d) |
  296. | **WiFi** | AP health across 2.4/5/6 GHz, per-client experience, SSID management, channel map, neighboring APs, and roaming history |
  297. | **Settings** | Profile editing and switching with a tested connection, theme selector |
  298. | **Onboarding** | Setup wizard that tests the connection before it saves anything |
  299. Tabs, list rows, key hints, dialogs, and dashboard panels also take a click or a tap, so the TUI runs on a touchscreen kiosk without a keyboard: tap a switch twice to open it, tap Ports, then tap the next switch to see its ports. The wheel scrolls lists and zooms the topology, and a drag pans the map.
  300. Anything disruptive asks first and says what it costs. Every command shows a progress toast that becomes its result, and `n` opens the history of what happened.
  301. ### ✦ Gallery
  302. Every capture below is the built-in `--demo-fleet` network at 183x47 in Ghostty.
  303. **Devices**: model, firmware with update markers, client counts, and live CPU/MEM, plus the switch port map in the detail panel
  304. <p align="center">
  305. <img src="docs/images/tui-devices.png" alt="unifly TUI Devices screen with model, IP, firmware, client count, CPU, memory, traffic, and uptime columns" width="440">
  306. <img src="docs/images/tui-devices-ports.png" alt="unifly TUI device detail for sw-core on the Ports tab, showing a colored port map and per-port link speed" width="440">
  307. </p>
  308. **Clients and Networks**: every client with its network and uplink, and each VLAN with its gateway, subnet, and IPv6 mode
  309. <p align="center">
  310. <img src="docs/images/tui-clients.png" alt="unifly TUI Clients screen with type, IP, MAC, network, uplink, signal, traffic, and duration columns" width="440">
  311. <img src="docs/images/tui-networks.png" alt="unifly TUI Networks screen listing six VLANs with gateway, subnet, DHCP, and IPv6 mode" width="440">
  312. </p>
  313. **Wi-Fi observability**: AP health across every band, per-client experience, and the neighbors your APs can hear
  314. <p align="center">
  315. <img src="docs/images/tui-wifi.png" alt="unifly TUI Wi-Fi overview with AP health, client counts, and channel and width for the 2.4, 5, and 6 GHz radios" width="290">
  316. <img src="docs/images/tui-wifi-clients.png" alt="unifly TUI Wi-Fi Clients tab with AP, radio, signal, health, and link rates" width="290">
  317. <img src="docs/images/tui-wifi-neighbors.png" alt="unifly TUI Wi-Fi Neighbors tab listing nearby networks with channel, signal, band, and security" width="290">
  318. </p>
  319. **Firewall and Topology**: policies grouped by zone pair in the order they apply, and the uplink tree from the gateway out
  320. <p align="center">
  321. <img src="docs/images/tui-firewall.png" alt="unifly TUI Firewall policies grouped by source and destination zone in evaluation order" width="440">
  322. <img src="docs/images/tui-topology.png" alt="unifly TUI Topology screen showing the gateway, core switch, edge switches, and APs with uplink ports and a mesh link" width="440">
  323. </p>
  324. **Events**: the live stream with an events-by-hour heatmap
  325. <p align="center">
  326. <img src="docs/images/tui-events.png" alt="unifly TUI Events screen with an events-by-hour heatmap above a live event list" width="900">
  327. </p>
  328. **Stats**: WAN bandwidth, client counts, and DPI over 1 hour, 24 hours, 7 days, and 30 days
  329. <p align="center">
  330. <img src="docs/images/tui-stats-1h.png" alt="unifly TUI Stats screen, 1 hour window" width="440">
  331. <img src="docs/images/tui-stats-24h.png" alt="unifly TUI Stats screen, 24 hour window" width="440">
  332. <img src="docs/images/tui-stats-7d.png" alt="unifly TUI Stats screen, 7 day window" width="440">
  333. <img src="docs/images/tui-stats-30d.png" alt="unifly TUI Stats screen, 30 day window" width="440">
  334. </p>
  335. **Help overlay**: every keybinding at a glance
  336. <p align="center">
  337. <img src="docs/images/tui-help.png" alt="unifly TUI help overlay listing navigation and global keybindings over the dashboard" width="900">
  338. </p>
  339. Full keybinding reference and screen details in the [TUI documentation](https://hyperb1iss.github.io/unifly/reference/tui).
  340. ---
  341. ## 🏗️ Architecture
  342. Two crates, clean dependency chain:
  343. | Crate | Purpose |
  344. | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  345. | **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) |
  346. | **unifly** | Single binary: CLI commands + `unifly tui` via feature flags, profile/keyring config, 11-screen ratatui dashboard and network client with SilkCircuit theme |
  347. Deep dive: [Architecture documentation](https://hyperb1iss.github.io/unifly/architecture/)
  348. ---
  349. ## ⚙️ Configuration
  350. ```bash
  351. unifly config init # Local controller setup wizard
  352. unifly config cloud-setup # Site Manager cloud setup wizard
  353. unifly config profiles # List profiles (* marks active)
  354. unifly config use office # Switch default profile
  355. unifly -p home devices list # One-off override
  356. ```
  357. Named profiles for multiple controllers, OS keyring credential storage, environment variable overrides, and TOML config files. A `[defaults]` section supplies fallbacks for any profile that leaves a value unset:
  358. ```toml
  359. # ~/.config/unifly/config.toml
  360. [defaults]
  361. insecure = false # accept self-signed certificates when true
  362. timeout = 30 # request timeout in seconds
  363. ```
  364. CLI flags and environment variables win over profile values, which win over `[defaults]`. Full details: [Configuration guide](https://hyperb1iss.github.io/unifly/guide/configuration)
  365. ---
  366. ## 📦 Library
  367. [![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
  368. ```rust
  369. use unifly_api::{Controller, ControllerConfig, AuthCredentials, TlsVerification};
  370. use secrecy::SecretString;
  371. let config = ControllerConfig {
  372. url: "https://192.168.1.1".parse()?,
  373. auth: AuthCredentials::ApiKey(SecretString::from("your-api-key")),
  374. tls: TlsVerification::DangerAcceptInvalid,
  375. ..Default::default()
  376. };
  377. let controller = Controller::new(config);
  378. controller.connect().await?;
  379. let devices = controller.devices_snapshot();
  380. println!("Found {} devices", devices.len());
  381. ```
  382. 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)
  383. ---
  384. ## 🤖 AI Agent Skill
  385. ### Install Options
  386. ```bash
  387. unifly skill --install # ~/.agents/skills, from the installed binary
  388. unifly skill --install --claude # Claude Code's skills directory
  389. npx skills add hyperb1iss/unifly # Claude Code, Cursor, Copilot, Codex, Gemini, ...
  390. npx skills add hyperb1iss/unifly -a claude-code # Target a specific agent
  391. /plugin marketplace add hyperb1iss/unifly # As a Claude Code plugin
  392. ```
  393. `unifly skill --install` works offline, prints the installed path, and is safe to rerun. It upgrades a skill from `npx skills add` or an earlier release in place, and leaves any other `SKILL.md` alone unless you pass `--force`. Use `--dir <path>` for any other skills directory.
  394. ### What's Included
  395. | Component | Description |
  396. | ------------------------- | ----------------------------------------------------------------------------------------- |
  397. | **unifly skill** | Complete CLI reference, command patterns, output formats, automation tips |
  398. | **Network Manager agent** | Autonomous agent for provisioning, diagnostics, and security audits |
  399. | **Runtime guide** | `unifly skill core\|commands\|concepts\|workflows\|examples`, version-matched and offline |
  400. ---
  401. ## 💜 Sponsor unifly
  402. unifly is indy open source. No VC, no telemetry, no upsells. Built by [@hyperb1iss](https://github.com/hyperb1iss) on real UniFi hardware, with help from a [growing list of contributors](https://github.com/hyperb1iss/unifly/graphs/contributors). Polished until the TUI sings.
  403. 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.
  404. <p align="center">
  405. <a href="https://github.com/sponsors/hyperb1iss">
  406. <img src="https://img.shields.io/badge/Sponsor%20unifly%20on%20GitHub-e135ff?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor hyperb1iss on GitHub">
  407. </a>
  408. </p>
  409. ---
  410. ## 🦋 Development
  411. ### Prerequisites
  412. - Rust 1.94+ (edition 2024)
  413. - A UniFi Network controller (Cloud Key, Dream Machine, or self-hosted)
  414. ### Build
  415. ```bash
  416. git clone https://github.com/hyperb1iss/unifly.git
  417. cd unifly
  418. cargo build --workspace
  419. ```
  420. ### Test & Lint
  421. ```bash
  422. cargo test --workspace
  423. cargo clippy --workspace --all-targets
  424. ```
  425. ### Run
  426. ```bash
  427. cargo run -p unifly -- devices list
  428. cargo run -p unifly -- tui
  429. ```
  430. ### Workspace Layout
  431. ```
  432. crates/
  433. unifly-api/ # Library: HTTP/WS transport, Controller, DataStore, domain models
  434. unifly/ # Single binary: CLI commands + tui subcommand, config, profiles
  435. ```
  436. ### Lint Policy
  437. Pedantic clippy with `unsafe_code = "forbid"`. See `Cargo.toml` workspace lints for the full configuration. It's opinionated and we like it that way.
  438. ---
  439. ## ⚖️ License
  440. Apache-2.0. See [LICENSE](LICENSE)
  441. ---
  442. <p align="center">
  443. <a href="https://github.com/sponsors/hyperb1iss">
  444. <img src="https://img.shields.io/badge/Sponsor-hyperb1iss-e135ff?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor on GitHub">
  445. </a>
  446. &nbsp;
  447. <a href="https://github.com/hyperb1iss/unifly">
  448. <img src="https://img.shields.io/github/stars/hyperb1iss/unifly?style=for-the-badge&logo=github&logoColor=white&color=80ffea" alt="Star on GitHub">
  449. </a>
  450. </p>
  451. <p align="center">
  452. <sub>
  453. If unifly keeps your network running smooth, <a href="https://github.com/sponsors/hyperb1iss"><strong>sponsor the project</strong></a> or give it a ⭐
  454. <br><br>
  455. ✦ Built with obsession by <a href="https://hyperbliss.tech"><strong>Hyperbliss Technologies</strong></a> ✦
  456. </sub>
  457. </p>
install.sh · Bundled script · 149 lines · 1 finding marked
  1. #!/bin/sh
  2. # unifly installer
  3. # Usage: curl -fsSL https://raw.githubusercontent.com/hyperb1iss/unifly/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 3 on GitHub
  4. set -e
  5. REPO="hyperb1iss/unifly"
  6. BINARY="unifly"
  7. # Colors (if terminal supports them)
  8. if [ -t 1 ]; then
  9. PURPLE='\033[38;2;225;53;255m'
  10. CYAN='\033[38;2;128;255;234m'
  11. GREEN='\033[38;2;80;250;123m'
  12. RED='\033[38;2;255;99;99m'
  13. YELLOW='\033[38;2;241;250;140m'
  14. RESET='\033[0m'
  15. else
  16. PURPLE='' CYAN='' GREEN='' RED='' YELLOW='' RESET=''
  17. fi
  18. info() { printf "${CYAN}::${RESET} %s\n" "$1"; }
  19. ok() { printf "${GREEN}::${RESET} %s\n" "$1"; }
  20. warn() { printf "${YELLOW}::${RESET} %s\n" "$1"; }
  21. error() { printf "${RED}::${RESET} %s\n" "$1" >&2; exit 1; }
  22. # Detect platform
  23. detect_platform() {
  24. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  25. ARCH=$(uname -m)
  26. case "$OS" in
  27. linux) PLATFORM="linux" ;;
  28. darwin) PLATFORM="macos" ;;
  29. *) error "Unsupported OS: $OS (use cargo install unifly instead)" ;;
  30. esac
  31. case "$ARCH" in
  32. x86_64|amd64) ARCH_SUFFIX="amd64" ;;
  33. aarch64|arm64) ARCH_SUFFIX="arm64" ;;
  34. *) error "Unsupported architecture: $ARCH" ;;
  35. esac
  36. # macOS only ships arm64 builds
  37. if [ "$PLATFORM" = "macos" ] && [ "$ARCH_SUFFIX" = "amd64" ]; then
  38. error "macOS x86_64 builds are not available. Use Homebrew (brew install hyperb1iss/tap/unifly) or build from source."
  39. fi
  40. ASSET="${BINARY}-${PLATFORM}-${ARCH_SUFFIX}"
  41. }
  42. # Get latest version
  43. get_latest_version() {
  44. VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" \
  45. | grep '"tag_name"' | head -1 | sed 's/.*"tag_name": *"//;s/".*//')
  46. if [ -z "$VERSION" ]; then
  47. error "Failed to fetch latest version from GitHub"
  48. fi
  49. }
  50. # Choose install directory
  51. choose_install_dir() {
  52. if [ -n "$INSTALL_DIR" ]; then
  53. # User specified
  54. return
  55. elif [ -w /usr/local/bin ]; then
  56. INSTALL_DIR="/usr/local/bin"
  57. elif [ -d "$HOME/.local/bin" ]; then
  58. INSTALL_DIR="$HOME/.local/bin"
  59. else
  60. mkdir -p "$HOME/.local/bin"
  61. INSTALL_DIR="$HOME/.local/bin"
  62. fi
  63. }
  64. # Download and install
  65. install() {
  66. URL="https://github.com/${REPO}/releases/download/${VERSION}/${ASSET}"
  67. TMPDIR=$(mktemp -d)
  68. TMPFILE="${TMPDIR}/${BINARY}"
  69. info "Downloading ${ASSET} ${VERSION}..."
  70. if ! curl -fsSL -o "$TMPFILE" "$URL"; then
  71. rm -rf "$TMPDIR"
  72. error "Download failed. Check https://github.com/${REPO}/releases for available assets."
  73. fi
  74. chmod +x "$TMPFILE"
  75. info "Installing to ${INSTALL_DIR}/${BINARY}..."
  76. if [ -w "$INSTALL_DIR" ]; then
  77. mv "$TMPFILE" "${INSTALL_DIR}/${BINARY}"
  78. else
  79. sudo mv "$TMPFILE" "${INSTALL_DIR}/${BINARY}"
  80. fi
  81. rm -rf "$TMPDIR"
  82. }
  83. # Verify installation
  84. verify() {
  85. if command -v "$BINARY" >/dev/null 2>&1; then
  86. INSTALLED_VERSION=$("$BINARY" --version 2>/dev/null | head -1)
  87. ok "Installed ${INSTALLED_VERSION}"
  88. else
  89. warn "Installed to ${INSTALL_DIR}/${BINARY} but it's not in your PATH"
  90. warn "Add this to your shell profile:"
  91. printf " export PATH=\"%s:\$PATH\"\n" "$INSTALL_DIR"
  92. fi
  93. }
  94. # Install the agent skill for the current user. Package managers cannot
  95. # reach a home directory, but this script runs as the user. Set
  96. # UNIFLY_NO_SKILL=1 to skip it.
  97. install_skill() {
  98. BIN_PATH="${INSTALL_DIR}/${BINARY}"
  99. if [ -n "$UNIFLY_NO_SKILL" ]; then
  100. return
  101. fi
  102. # Releases before `unifly skill --install` cannot do this.
  103. if ! "$BIN_PATH" skill --help 2>/dev/null | grep -q -- '--install'; then
  104. return
  105. fi
  106. if [ "$(id -u)" = "0" ]; then
  107. warn "Skipped the agent skill while running as root"
  108. warn "Run 'unifly skill --install' as your own user to add it"
  109. return
  110. fi
  111. if SKILL_STATUS=$("$BIN_PATH" skill --install 2>&1 >/dev/null); then
  112. printf '%s\n' "$SKILL_STATUS" | while IFS= read -r line; do ok "$line"; done
  113. else
  114. warn "Could not install the agent skill; run 'unifly skill --install' to see why"
  115. fi
  116. }
  117. # Main
  118. printf "\n${PURPLE} unifly installer${RESET}\n\n"
  119. detect_platform
  120. get_latest_version
  121. choose_install_dir
  122. install
  123. verify
  124. install_skill
  125. printf "\n${CYAN} Get started:${RESET}\n"
  126. printf " unifly config init # Set up your controller\n"
  127. printf " unifly devices list # List network devices\n"
  128. printf " unifly tui # Launch the dashboard\n\n"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.