unifi-cli
CLI for UniFi Network controller with an interactive TUI dashboard. Designed for both human operators and AI agents.
Quick start
# Install (pick one)
# Configure
# Use
Generate an API key in your UniFi controller under Settings > API.
Installation
From crates.io
From PyPI
# or run without installing:
From GitHub releases
Pre-built binaries for Linux (x64, arm64), macOS (x64, arm64), and Windows (x64) on the releases page.
Configuration
Run unifi config init for interactive setup, or configure manually:
Environment variables
# Optional for lab controllers with self-signed or otherwise invalid TLS certs:
Config file
Linux: ~/.config/unifi/config.toml.
macOS: ~/Library/Application Support/unifi/config.toml.
Windows: %APPDATA%\unifi\config.toml.
unifi config init writes a new file and renames it over any existing config
instead of writing in place, so a failed write leaves the previous config
intact. On Linux and macOS the new file is created with mode 0600, since it
holds an API key and optionally a Protect password. Because the credentials go
straight into a file that is already 0600, they are never readable by another
local account, not even for the moment between the write and a chmod. On
Windows the file inherits its directory's ACL.
= "https://unifi.example.com"
= "YOUR_KEY"
# Optional; defaults to false.
= false
Multi-controller profiles
[]
= "https://home.example.com"
= "KEY_1"
[]
= "https://office.example.com"
= "KEY_2"
# or: UNIFI_PROFILE=office unifi clients list
CLI flags
Priority: CLI flags > environment variables > config file.
TLS certificates are verified by default. For a local controller with a
self-signed certificate, pass --accept-invalid-certs, set
UNIFI_ACCEPT_INVALID_CERTS=true, or set accept_invalid_certs = true in the
config file. Only use this on trusted networks because it weakens protection for
API keys, passwords, session cookies, and stream URLs.
When unifi config init cannot verify the controller's certificate, it offers
to trust the controller and saves accept_invalid_certs = true for you.
Destructive commands
clients block, clients unblock, clients kick, devices restart,
devices upgrade, ports cycle and protect rtsps delete all ask before they
act. On a terminal you get a yes/no question naming the target; declining exits
2 with kind: confirmation_required and sends nothing. When stdin is not a
terminal there is nobody to ask, so they refuse with the same error unless you
pass --yes, which skips the question everywhere.
unifi schema marks exactly these commands confirmation_required: true, so a
caller can tell them apart from mutating commands that act immediately
(devices locate, clients set-fixed-ip, protect rtsps create) without
hardcoding the list.
TUI dashboard
Real-time dashboard with:
- Client list with bandwidth, connection info, and signal strength
- Device overview with status and firmware versions
- Event feed from the controller
- Client actions: kick, block/unblock, lock/unlock AP
- Device actions: restart, upgrade firmware, locate LED
- Filter clients by name with
/
Live port monitor
Commands
Clients
Devices
Ports
Find which switch port a device is plugged into, then power-cycle just that port instead of rebooting the whole switch:
# Which port is my Pi on? Matches by name (case-insensitive substring),
# MAC, or IP.
# Inspect it: PoE mode, class, voltage, current, and what's attached
# Bounce PoE on that port only, leaving the rest of the switch untouched
ports find's output feeds directly into show and cycle: device_mac
and port_idx are the switch's MAC and port index, not the attached
device's. A name is ambiguous only when it matches more than one device
that's actually on a switch port; that returns kind: conflict (exit 6)
listing the candidates rather than guessing. Other client records sharing
the name (a device's WiFi interface reporting under the same name as its
wired one, say) don't cause a conflict if they're not themselves on a port.
A device that has moved between switch ports appears once per port it has
ever used, with a connected field distinguishing its current port from
stale history.
ports show exposes the port's PoE telemetry: poe_mode, poe_class,
poe_voltage, poe_current, poe_good, and the MAC of the attached device
(attached_mac). The controller keeps a port's last connection record after
the device is unplugged, so attached_mac is set only when the controller
affirms the record is live. The MAC is still reported as
attached_last_seen_mac and the controller's own flag as attached_connected
(true, false, or null when the firmware does not report it), so a caller can
tell "gone" from "not reported". The text output renders the three cases as
aa:bb:cc:dd:ee:ff, - (last seen aa:bb:cc:dd:ee:ff) and
unknown (last seen aa:bb:cc:dd:ee:ff). Nothing that has been unplugged is
ever presented as currently attached.
ports cycle is destructive. On a terminal it shows what is about to lose
power and asks for confirmation; when piped it requires --yes and
otherwise exits 2 with kind: confirmation_required. It reads the port
table first, then refuses without ever sending the power-cycle command
when:
- the port is not PoE-capable (an SFP+ port, say) →
kind: conflict, exit 6 - the port's PoE is administratively off →
kind: conflict, exit 6 - the port isn't currently delivering PoE (
poe_enable: false) →kind: conflict, exit 6 - the device has no such port index →
kind: not_found, exit 4
The off interval (how long the port stays unpowered) is chosen by the switch firmware, not by this CLI. The power-cycle command takes only the target port, with no duration parameter, on either the legacy endpoint or the Integration API, so the interval isn't configurable and varies by device model and firmware version. IEEE 802.3 PoE detection timing imposes a floor regardless: expect the port to sit dark for roughly 1-2 seconds at minimum before power returns.
List ports for one device, or across every device:
ports list returns the paginated {items, total, limit, offset} envelope
used by the other list commands. unifi devices ports <MAC> remains an
alias for unifi ports list <MAC>; it keeps its original bare-JSON-array
shape for backward compatibility, and both emit the same per-row fields,
including device_mac and device_name.
Events
Networks
System
Configuration
Shell completions
Agent-friendly design
unifi-cli is designed to work well with AI agents and automation scripts.
Automatic JSON output
When stdout is not a terminal (piped or redirected), output switches to JSON automatically:
# Human at terminal: formatted table
# Agent piping output: JSON automatically
data=
# Force JSON mode
Clean stdout/stderr separation
Data goes to stdout. Messages go to stderr. Piping always captures clean data:
Structured mutation responses
# {"action": "block", "mac": "AA:BB:CC:DD:EE:FF", "status": "ok"}
Runtime schema introspection
Distinct exit codes
| Code | kind |
Meaning |
|---|---|---|
| 0 | - | Success |
| 1 | general_error |
General error (including transport failures) |
| 2 | config_error |
Configuration or usage error |
| 2 | confirmation_required |
A destructive command ran without --yes and without a TTY |
| 3 | auth_error |
Authentication error (401/403) |
| 4 | not_found |
Not found (404) |
| 4 | unsupported |
The controller does not serve this API at all (it answered a JSON endpoint with HTML, which is how UniFi OS reports an application it does not have); unlike not_found there is no other identifier worth trying |
| 5 | client_error |
The controller rejected the request itself (4xx other than 401/403/404/408/429); retrying it unchanged cannot help |
| 5 | retry_later |
The controller invited a retry (429 rate limited, 408 request timeout); back off and send the same request again |
| 5 | api_error |
The controller failed to serve the request (5xx); may be transient |
| 6 | conflict |
The request cannot succeed against the resource's current state, refused locally before any API call |
unifi schema publishes the same table under errors, with a retryable flag
per kind, so an agent can branch on it without parsing prose.
Development
License
MIT