unifi-cli 0.3.0

CLI for UniFi Network controller

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)
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 UniFi controller under Settings > API.

Installation

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.

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

~/.config/unifi/config.toml:

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.

TUI dashboard

unifi tui                       # Launch interactive 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

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

Events

unifi events list                           # Recent controller events
unifi events list --limit 50                # Last 50 events

Networks

unifi networks list                         # List all networks
unifi networks                              # Same thing

System

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

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

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Authentication error (401/403)
4	Not found (404)
5	API error (server error)

Development

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

License

MIT