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)
brew install rvben/tap/unifi-cli # macOS or Linux
cargo install unifi-cli        # From source
uvx unifi-cli --help           # Run without installing (via uv)
pip install unifi-cli           # Via pip

# Configure
unifi config init               # Interactive setup (prompts for host + API key)

# Use
unifi clients list              # List connected clients
unifi devices list              # List network devices
unifi tui                       # Interactive dashboard

Generate an API key in your controller under UniFi Network → Integrations. Ubiquiti documents the current flow in Getting Started with the Official UniFi API.

Installation

With Homebrew

brew install rvben/tap/unifi-cli

The tap provides pre-built binaries for Apple Silicon and Intel Macs, and ARM64 and x86_64 Linux. It installs both unifi and unifi-cli, with shell completions for Bash, Zsh, and Fish.

To update:

brew update
brew upgrade unifi-cli

From crates.io

cargo install unifi-cli

From PyPI

pip install unifi-cli
# or run without installing:
uvx unifi-cli clients list

From GitHub releases

Pre-built binaries for Linux (x64, arm64), macOS (x64, arm64), and Windows (x64) on the releases page.

With Nix

The flake supports Linux (x64, arm64) and macOS (Apple Silicon). For Intel Macs, use the pre-built release binaries above; current nixpkgs no longer supports that platform.

Run without installing:

nix run github:rvben/unifi-cli -- clients list

To install it from a flake-based NixOS or Home Manager setup, add the input and have it follow your nixpkgs:

# flake.nix
inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  unifi-cli = {
    url = "github:rvben/unifi-cli";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

Then add the package. As a Home Manager module:

{ inputs, pkgs, ... }:

{
  home.packages = [
    inputs.unifi-cli.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

Or as a NixOS module:

{ inputs, pkgs, ... }:

{
  environment.systemPackages = [
    inputs.unifi-cli.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

Pass inputs to your modules with extraSpecialArgs = { inherit inputs; }; in home-manager.lib.homeManagerConfiguration, or specialArgs = { inherit inputs; }; in nixpkgs.lib.nixosSystem. When using Home Manager as a NixOS module, set home-manager.extraSpecialArgs = { inherit inputs; }; as well.

The package installs both unifi and unifi-cli. An overlay is also exported as inputs.unifi-cli.overlays.default, which adds pkgs.unifi-cli.

The flake reads the version from Cargo.toml and Rust dependencies from Cargo.lock, so it needs no manual updates on release. The committed flake.lock pins nixpkgs and the Rust toolchain for standalone builds and development shells; update it deliberately with nix flake update.

For development, nix develop (or direnv allow with nix-direnv installed) provides the Rust toolchain, language server, nextest, and Nix formatter. nix flake check builds the package, runs the Rust tests, checks both installed commands and shell completions, and verifies that the overlay respects the consumer’s Rust toolchain. nix flake check --all-systems --no-build --option allow-import-from-derivation false evaluates every supported platform without building during evaluation. Run nix fmt -- --check flake.nix nix/*.nix to check Nix formatting.

Configuration

Run unifi config init for interactive setup, or configure manually:

Environment variables

export UNIFI_HOST=https://unifi.example.com
export UNIFI_API_KEY=YOUR_KEY
# Optional for lab controllers with self-signed or otherwise invalid TLS certs:
export UNIFI_ACCEPT_INVALID_CERTS=true

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.

host = "https://unifi.example.com"
api_key = "YOUR_KEY"
# Optional; defaults to false.
accept_invalid_certs = false

Multi-controller profiles

[profiles.home]
host = "https://home.example.com"
api_key = "KEY_1"

[profiles.office]
host = "https://office.example.com"
api_key = "KEY_2"

unifi --profile office clients list
# or: UNIFI_PROFILE=office unifi clients list

CLI flags

unifi --host https://unifi.example.com --api-key YOUR_KEY clients list

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, protect rtsps delete and dns 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, dns create, dns update) without hardcoding the list.

TUI dashboard

unifi tui                       # Launch interactive dashboard

If the controller is not configured or rejects the saved API key, the dashboard offers guided configuration in place. Press Enter or a, complete the secure prompt outside the alternate screen, and the dashboard resumes automatically.

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

unifi devices ports aa:bb:cc:dd:ee:ff --live   # Real-time port stats

Commands

Clients

unifi clients list                          # List connected clients
unifi clients list --wired                  # Wired clients only
unifi clients list --wireless --name tasmota  # Filter by type and name
unifi clients list --watch                  # Auto-refresh
unifi clients list --fields name,ssid,ip    # Project specific fields (see `unifi schema`)
unifi clients show aa:bb:cc:dd:ee:ff        # Show client details
unifi clients top                           # Top clients by bandwidth
unifi clients block aa:bb:cc:dd:ee:ff       # Block a client
unifi clients unblock aa:bb:cc:dd:ee:ff     # Unblock a client
unifi clients kick aa:bb:cc:dd:ee:ff        # Disconnect a client
unifi clients set-fixed-ip MAC IP [--name]  # Set DHCP reservation

Devices

unifi devices list                            # List network devices
unifi devices list --watch                    # Auto-refresh
unifi devices show aa:bb:cc:dd:ee:ff          # Show device details
unifi devices ports aa:bb:cc:dd:ee:ff         # Show switch/router ports
unifi devices restart aa:bb:cc:dd:ee:ff       # Restart a device
unifi devices upgrade aa:bb:cc:dd:ee:ff       # Upgrade firmware
unifi devices locate aa:bb:cc:dd:ee:ff        # Blink locate LED
unifi devices locate aa:bb:cc:dd:ee:ff --off  # Stop blinking

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.
unifi ports find garage-pi
unifi ports find aa:bb:cc:dd:ee:10

# Inspect it: PoE mode, class, voltage, current, and what's attached
unifi ports show aa:bb:cc:dd:ee:ff 5

# Bounce PoE on that port only, leaving the rest of the switch untouched
unifi ports cycle aa:bb:cc:dd:ee:ff 5

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:

unifi ports list aa:bb:cc:dd:ee:ff
unifi ports list --limit 20 --fields port_idx,poe_power

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.

Port forwards

unifi port-forwards list
unifi port-forwards show plex

DNS records

Static DNS records the controller answers locally. Network 10.1+ uses the official DNS-policies Integration API; older controllers fall back to the v2 static-dns API. Domain-forward policies are not listed.

unifi dns list
unifi dns list --type A
unifi dns show nas.example.com
unifi dns create nas.example.com 192.0.2.10
unifi dns create printer.example.com 2001:db8::10 --type AAAA
unifi dns create media.example.com nas.example.com --type CNAME
unifi dns update nas.example.com --value 192.0.2.11
unifi dns delete nas.example.com

dns delete is destructive and follows the same confirmation rules as clients block. Create and update act immediately.

The v2 API has no PUT, so dns update is refused on a controller that falls back to it. Editing a record there means dns delete followed by dns create, which keeps the delete explicit and confirmed instead of hiding it inside an update that cannot undo it when the create fails.

Events

unifi events list                           # Recent controller events
unifi events list --limit 50                # Last 50 events
unifi events list --limit 10 --offset 10    # Next 10 recent events

The command fetches enough recent events to cover both the offset and the requested page. JSON total counts the events retrieved for that window; it is not a count of the controller's complete event history.

Networks

unifi networks list                         # List all networks
unifi networks                              # Same thing
unifi networks show IoT                     # DHCP, DNS, mDNS, and cellular-backup details

System

unifi system health                         # Show subsystem health
unifi system info                           # Show controller info

WAN

unifi wan list                              # Show uplinks and failover state

Configuration

unifi config init                           # Interactive setup
unifi config check                          # Verify connectivity and API key

Shell completions

unifi completions zsh --install             # Install zsh completions
unifi completions bash --install            # Install bash completions
unifi completions fish --install            # Install fish 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
unifi clients list

# Agent piping output: JSON automatically
data=$(unifi clients list)

# Force JSON mode
unifi --json clients list

Clean stdout/stderr separation

Data goes to stdout. Messages go to stderr. Piping always captures clean data:

unifi clients list > clients.json     # stdout: JSON, stderr: "66 clients"
unifi --quiet clients list            # Suppress stderr messages

Structured mutation responses

unifi --json clients block aa:bb:cc:dd:ee:ff
# {"action": "block", "mac": "AA:BB:CC:DD:EE:FF", "status": "ok"}

Runtime schema introspection

unifi schema    # Dumps all commands, arguments, output fields as JSON

Distinct exit codes

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

make check      # Lint and test
make test       # Run tests
make install    # Build and install

License

MIT

Releasing

Vership owns versioning, changelog generation, release commits, and tags. See the release runbook for the verified workflow and recovery policy.