Quick Start

Set up your first controller profile and run your first commands

🔗Prerequisites

  • A UniFi Network controller (Dream Machine, Cloud Key, UCG, or self-hosted)
  • An API key (Settings > Integrations) and/or admin credentials
  • unifly installed

🔗Interactive Setup

Run the setup wizard to configure your first controller profile:

unifly config init

The wizard walks you through:

  1. Controller URL: your controller’s address (e.g., https://192.168.1.1)
  2. TLS: whether the controller uses a self-signed certificate (the default on UniFi hardware; the wizard pre-selects the right answer for LAN addresses)
  3. Authentication: API key, username/password, or hybrid mode
  4. Site selection: choose which site to manage

Credentials are stored in your OS keyring by default. A plaintext config fallback is available if the keyring isn’t accessible.

For a cloud profile that reaches your controllers through Ubiquiti’s Site Manager instead of a direct connection, run the guided cloud wizard (see Cloud & Site Manager):

unifly config cloud-setup

🔗First Commands

Once configured, explore your network:

# List all adopted devices
unifly devices list

# See connected clients
unifly clients list

# View networks and VLANs
unifly networks list

# Stream live events
unifly events watch

Example output:

 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

🔗Output Formats

Every command supports multiple output formats:

unifly devices list                  # Default table (human-readable)
unifly devices list -o json          # Full JSON (for scripting)
unifly devices list -o json-compact  # Single-line JSON (pipe-friendly)
unifly devices list -o yaml          # YAML
unifly devices list -o plain         # IDs only, one per line (for xargs)

Use -o json for automation and -o plain | xargs for batch operations:

unifly clients list -o plain | xargs -n1 unifly clients get

Create commands print the created entity on stdout in the requested format (the human confirmation goes to stderr), so capturing a new ID for the next step is a one-liner:

NET_ID=$(unifly networks create --name "IoT" --vlan 30 \
  --management gateway --ipv4-host "10.0.30.1/24" -o json | jq -r '.id')

🔗Launch the TUI

For real-time monitoring, launch the terminal dashboard:

unifly tui                   # Default profile
unifly tui -p office         # Specific profile

graph LR
1["1 Dashboard
Health overview"] --> 2["2 Devices
Hardware status"]
2 --> 3["3 Clients
Connected users"]
3 --> 4["4 Networks
VLANs & DHCP"]
4 --> 5["5 Firewall
Policies & zones"]
5 --> 6["6 Topology
Network map"]
6 --> 7["7 Events
Live feed"]
7 --> 8["8 Stats
Historical data"]
8 --> 9["9 WiFi
RF health & roaming"]

Eleven screens in total: the nine above on number keys 1-9, a Settings screen on , (profiles, themes, display options), and an Onboarding wizard that appears automatically on first launch. Press ? for help, q to quit.

Heads Up
  • events watch requires Session or Hybrid auth (WebSocket needs a cookie session)
  • List commands default to 25 rows. Pass --all or --limit 200 for full results
  • Use Hybrid only when you need live event streaming (events watch). API Key mode covers most commands on UniFi OS

🔗Multiple Controllers

Add more profiles for different controllers:

unifly config init                    # Add another profile
unifly config profiles                # List all profiles
unifly config use office              # Switch default profile
unifly -p home devices list           # One-off override

🔗Next Steps