unifi-cli

A small, zero-dependency Bun CLI for the UniFi Network Integrations API on UniFi gateways (Cloud Gateway Ultra, UDM, UDR, etc.), plus an optional Claude Code skill so an AI session can answer questions about your network by running it.

$ unifi devices
NAME                 MODEL      IP             STATE   FIRMWARE
Cloud Gateway Ultra  UCG Ultra  203.0.113.10   ONLINE  5.1.19
U7 Lite              U7 Lite    192.168.1.252  ONLINE  8.6.11

• unifi info — Network application version
• unifi sites — list sites
• unifi devices — all UniFi hardware (gateway, switches, APs) with model/IP/state/firmware
• unifi device <name|id> — device detail plus live stats (uptime, CPU, memory)
• unifi clients [--wired|--wireless] [--all] — every client on the network; --all adds known clients that are offline, with when they were last seen
• unifi client <name|ip|mac> — one client plus its DHCP reservation; if nothing connected matches, it searches every client the gateway has ever seen and shows each match as offline with first/last seen
• unifi client fixed-ip <client> <ip|off> [--name label] — set or clear a DHCP reservation (asks for confirmation; uses the legacy Network API, see docs/api-notes.md)
• unifi radios [<device>] — every AP radio: band, channel and width (configured vs. what it's using now), tx power mode, client count, channel busy % and retransmit % (--json gives one normalized object per radio)
• unifi radio set <device> <2.4|5|6> [--width N] [--channel N|auto] [--tx-power low|medium|high|auto] — change a radio (shows a before→after diff and asks for confirmation; briefly drops that radio's clients; uses the legacy Network API)
• unifi neighbors [--band 2.4|5|6] [--hours N] — neighboring Wi-Fi networks per channel as the APs hear them (count, strongest signal, how many are loud); an AP only hears its own channel, so it's a picture of where you are and where you've been
• unifi smartq / unifi smartq set <down Mbps> <up Mbps> / unifi smartq off — Smart Queues (SQM, the bufferbloat fix) per WAN (--wan for a non-primary WAN; asks for confirmation)
• unifi portforwards — port-forward rules: name, enabled, protocol, WAN port, LAN target, allowed source, id
• unifi portforward enable|disable <name|id> — turn a rule on or off (asks for confirmation, then re-reads the rule to report its actual state; uses the legacy Network API). There is deliberately no delete.
• unifi upnp — UPnP / NAT-PMP state on the gateway (read-only)
• unifi networks — networks: VLAN, subnet, isolated, internet access, id
• unifi network create <name> --vlan N --subnet 192.168.20.1/24 [--isolate] — create a gateway-managed VLAN with DHCP from .6 to the last address; refuses a duplicate name, VLAN or overlapping subnet, asks for confirmation, then re-reads it to check isolation stuck (Integration API)
• unifi wifis — SSIDs: enabled, network, security, bands
• unifi wifi create <ssid> --network <name> [--band 2.4|5|6|both] [--passphrase P] — create a WPA2 SSID on a network (default 2.4 GHz, which most IoT devices need; without --passphrase it generates one and prints it once). There is deliberately no delete for networks or SSIDs.
• unifi wifi passphrase <ssid> [--passphrase P] — change an SSID's passphrase (asks for confirmation; every device on it has to rejoin)
• unifi device restart <name|id> — restart a device (asks for confirmation)
• unifi device power-cycle <name|id> <port> — power-cycle a PoE port (asks for confirmation)
• --json on any read command for the raw API response, --site to pick a site, --yes to skip confirmations in scripts

Zero runtime npm dependencies. Self-signed gateway certificates are accepted (it's a LAN device). Paginated endpoints are fetched fully and transparently.

Requires Bun.

git clone https://github.com/baileywickham/unifi-cli && cd unifi-cli
bun install
bun link          # links `unifi` into Bun's global bin dir, ~/.bun/bin

bun link only creates ~/.bun/bin/unifi. Bun's install script adds ~/.bun/bin to your PATH, but a Homebrew-installed Bun does not, so which unifi comes up empty. In that case add it to your shell config:

export PATH="$HOME/.bun/bin:$PATH"   # e.g. in ~/.zshrc

or run it as ~/.bun/bin/unifi.

The Integrations API only accepts console-local API keys. Keys created at unifi.ui.com → API Keys are cloud keys: they work against api.ui.com, but the gateway's local API will return 401 Unauthorized for them.

Create a local key in the gateway's local web UI:

• Network 10.x: https://<gateway-ip>/network/default/integrations → Create New API Key
• Network 9.x: Settings → Control Plane → Integrations → Create API Key

Note: the cloud-proxied UI at unifi.ui.com hides this page — you must be on the gateway's own UI. If your browser blocks the gateway's self-signed certificate, use the console's https://<id>.id.ui.direct hostname shown on its login screen, which carries a valid certificate and resolves to the LAN IP.

Environment variables win over the config file:

export UNIFI_API_KEY=<your key>
export UNIFI_GATEWAY=https://192.168.1.1    # optional, defaults to https://192.168.0.1

or ~/.config/unifi-cli/config.json:

{ "gateway": "https://192.168.1.1", "apiKey": "<your key>", "defaultSite": "default" }

The config file holds a credential — chmod 600 it.

unifi devices                        # which APs/switches do I have, are they up?
unifi device living-room             # one device: detail + uptime/cpu/memory
unifi clients --wireless             # who's on WiFi right now
unifi clients --json                 # full client objects (incl. uplink AP id)
unifi client 192.168.0.134           # who is that, and does it have a fixed IP?
unifi client avery-laptop            # not connected? shows when it was last seen
unifi clients --all                  # connected clients, then known offline ones
unifi client fixed-ip 192.168.0.134 192.168.0.50 --name macnode   # DHCP reservation
unifi radios                         # channel/width/tx power of every AP radio
unifi radio set "U7 Lite" 5 --width 80   # widen 5 GHz to 80 MHz (prompts y/N)
unifi neighbors --band 5 --hours 24 # how crowded is each 5 GHz channel?
unifi smartq set 210 36             # Smart Queues at ~90% of measured down/up (prompts y/N)
unifi portforwards                   # what's exposed to the internet?
unifi portforward disable ubnt       # turn a rule off (prompts y/N)
unifi upnp                           # is UPnP on?
unifi device restart living-room     # prompts y/N before acting
unifi --help

Exit code is non-zero on any error, and errors are printed as unifi: <message>, so it composes well in scripts. A 404 from the gateway is reported as possibly unsupported firmware — the Integrations API surface varies by Network application version (developed against Network 10.4 on a Cloud Gateway Ultra).

See docs/api-notes.md for field notes on the API itself (auth gotchas, pagination, observed payload shapes).

The easiest way is the plugin marketplace:

/plugin marketplace add baileywickham/claude-plugins
/plugin install unifi-cli@baileywickham

Or, from a clone of this repo:

bun run install-skill   # copies skills/unifi-cli/ → ~/.claude/skills/unifi-cli

Either way, any Claude Code session on your machine knows how to answer "what APs do I have?" or "is my iPhone on WiFi?" by running the CLI. The skill hard-codes a safety rule: it never runs restart/power-cycle/fixed-ip/radio set/smartq set|off/portforward enable|disable/network create/wifi create|passphrase (and never passes --yes) unless you explicitly asked for that action in the conversation.

bun test          # 77 tests, no network needed (injectable fetch)

src/api.ts is the only file that talks HTTP; commands are pure functions over an injected client, which is what makes the suite fast and offline.

MIT