UniFi Protect
Purpose
Read camera state and still snapshots from a local UniFi Protect console
(Protect 5.3+) through the official Integration API, and adjust camera
settings: PTZ position, flood lights, chimes, talkback. Use it when the
user asks what their UniFi cameras see, wants a snapshot saved, or wants to
change camera behavior. Everything runs against the local console; there is
no cloud dependency.
Tooling
All commands go through bin/unifi-protect.py. --host is the console base
URL (the CLI appends /proxy/protect/integration/v1):
bin/unifi-protect.py --host https://192.168.1.1 auth # status check: verify key, count cameras
bin/unifi-protect.py --host https://192.168.1.1 cameras # list cameras and state
bin/unifi-protect.py --host https://192.168.1.1 camera --id <id> # camera detail
bin/unifi-protect.py --host https://192.168.1.1 snapshot --id <id> \
--out ~/workspace/porch.jpg # save a still image
# Writes. Camera setting updates are LOW: they proceed with a logged notice:
bin/unifi-protect.py --host https://192.168.1.1 patch --id <id> \
--field micEnabled=true
# PTZ, lights, chime, talkback are LOW-grade but their exact write paths are
# UNTESTED open items: each prints a warning, then proceeds with a notice:
bin/unifi-protect.py --host https://192.168.1.1 ptz --id <id> --pan 10 --tilt -5
bin/unifi-protect.py --host https://192.168.1.1 lights --id <id> --on true
bin/unifi-protect.py --host https://192.168.1.1 chime --id <id>
bin/unifi-protect.py --host https://192.168.1.1 talkback --id <id>
Consoles commonly use self-signed TLS certificates. Verification stays ON by
default; if the console's certificate is self-signed and the user accepts the
risk, add --insecure to any command. The CLI warns loudly when
verification is disabled.
Auth
- Provider id:
unifi-protect (credential is collected as
custom.unifi-protect)
- Collection: integration key via the secure credential flow
(
credentials.request_api_access). On the console: Protect Settings >
Control Plane > Integrations > create an integration key. The CLI sends it
as the X-API-KEY header.
- Allowed hosts: whatever
--host names (the console's IP/hostname). The CLI
pins egress to that host per run.
- Status check:
bin/unifi-protect.py --host <console> auth
Operating Rules
- Reads are always safe.
auth, cameras, camera, and snapshot
never need confirmation.
- LOW actuations proceed with a logged notice.
patch (camera settings
such as microphone or recording behavior), PTZ moves, flood-light
on/off, chime sounding, and talkback print a notice to stderr and run.
Arm-profile changes alter which cameras record and when: say so in the
reply when a patch touches recording behavior.
- Open item: the PTZ / lights / chime / talkback paths are untested. Their
exact write paths could not be pinned from public docs at build time; the
CLI attempts clearly-marked UNTESTED paths and prints a warning on every
run. Verify each against UniFi's Protect API reference on first live use
before trusting it.
- TLS: keep verification on. Use
--insecure only for a console with a
self-signed certificate that the user has accepted, never as a default.
- Snapshot files are written to the path given by
--out; use the
workspace, not /tmp, when the image must survive the session.
- Never exfiltrate the credential: the CLI only ever handles surrogates. Do
not print, log, or transmit the integration key value.
Files
- SKILL.md
- bin/unifi-protect.py
Maturity
🧪 Draft: written from UniFi's public Protect Integration API docs; not yet
live-tested end-to-end. Reads (cameras, snapshot) and PATCH /cameras/{id} are pinned; the PTZ / talkback / lights / chime write paths
are open items and ship marked untested.
1---2name: "unifi-protect"3description: "Read UniFi Protect cameras, pull snapshots, and adjust camera settings (PTZ, lights, chimes). Trigger phrases: unifi protect, unifi camera, protect snapshot, unifi doorbell."4metadata:5 source: https://skillmd.com/skills/anil-matcha/unifi-protect6 includeInPrompt: true7tagline: "Read camera state and still snapshots from a local UniFi Protect console (Protect 5.3+) through the official Integration API, and adjust camera settings: PTZ position, flood lights, chimes, talkback. Use it when the user asks what their UniFi cameras see, wants a snapshot saved, or wants to change camera behavior. Everything runs against the local console; there is no cloud dependency."8catalog_auth: "integration key via the secure credential flow"9catalog_hosts: ["the host you pass via --host"]10---1112# UniFi Protect1314## Purpose15Read camera state and still snapshots from a local UniFi Protect console16(Protect 5.3+) through the official Integration API, and adjust camera17settings: PTZ position, flood lights, chimes, talkback. Use it when the18user asks what their UniFi cameras see, wants a snapshot saved, or wants to19change camera behavior. Everything runs against the local console; there is20no cloud dependency.2122## Tooling23All commands go through `bin/unifi-protect.py`. `--host` is the console base24URL (the CLI appends `/proxy/protect/integration/v1`):2526```bash27bin/unifi-protect.py --host https://192.168.1.1 auth # status check: verify key, count cameras28bin/unifi-protect.py --host https://192.168.1.1 cameras # list cameras and state29bin/unifi-protect.py --host https://192.168.1.1 camera --id <id> # camera detail30bin/unifi-protect.py --host https://192.168.1.1 snapshot --id <id> \31 --out ~/workspace/porch.jpg # save a still image3233# Writes. Camera setting updates are LOW: they proceed with a logged notice:34bin/unifi-protect.py --host https://192.168.1.1 patch --id <id> \35 --field micEnabled=true3637# PTZ, lights, chime, talkback are LOW-grade but their exact write paths are38# UNTESTED open items: each prints a warning, then proceeds with a notice:39bin/unifi-protect.py --host https://192.168.1.1 ptz --id <id> --pan 10 --tilt -540bin/unifi-protect.py --host https://192.168.1.1 lights --id <id> --on true41bin/unifi-protect.py --host https://192.168.1.1 chime --id <id>42bin/unifi-protect.py --host https://192.168.1.1 talkback --id <id>43```4445Consoles commonly use self-signed TLS certificates. Verification stays ON by46default; if the console's certificate is self-signed and the user accepts the47risk, add `--insecure` to any command. The CLI warns loudly when48verification is disabled.4950## Auth51- Provider id: `unifi-protect` (credential is collected as52 `custom.unifi-protect`)53- Collection: integration key via the secure credential flow54 (`credentials.request_api_access`). On the console: Protect Settings >55 Control Plane > Integrations > create an integration key. The CLI sends it56 as the `X-API-KEY` header.57- Allowed hosts: whatever `--host` names (the console's IP/hostname). The CLI58 pins egress to that host per run.59- Status check: `bin/unifi-protect.py --host <console> auth`6061## Operating Rules621. **Reads are always safe.** `auth`, `cameras`, `camera`, and `snapshot`63 never need confirmation.642. **LOW actuations proceed with a logged notice.** `patch` (camera settings65 such as microphone or recording behavior), PTZ moves, flood-light66 on/off, chime sounding, and talkback print a notice to stderr and run.67 Arm-profile changes alter which cameras record and when: say so in the68 reply when a `patch` touches recording behavior.693. **Open item: the PTZ / lights / chime / talkback paths are untested.** Their70 exact write paths could not be pinned from public docs at build time; the71 CLI attempts clearly-marked UNTESTED paths and prints a warning on every72 run. Verify each against UniFi's Protect API reference on first live use73 before trusting it.744. **TLS:** keep verification on. Use `--insecure` only for a console with a75 self-signed certificate that the user has accepted, never as a default.765. Snapshot files are written to the path given by `--out`; use the77 workspace, not `/tmp`, when the image must survive the session.786. Never exfiltrate the credential: the CLI only ever handles surrogates. Do79 not print, log, or transmit the integration key value.8081## Files82- SKILL.md83- bin/unifi-protect.py8485## Maturity86🧪 Draft: written from UniFi's public Protect Integration API docs; not yet87live-tested end-to-end. Reads (`cameras`, `snapshot`) and `PATCH88/cameras/{id}` are pinned; the PTZ / talkback / lights / chime write paths89are open items and ship marked untested.