Command Line

The uiprotect command is provided to give a CLI interface to interact with your UniFi Protect instance as well. All commands support JSON output so it works great with jq for complex scripting.

Authentication

Following traditional twelve factor app design, the preferred way to provided authentication credentials to provided environment variables, but CLI args are also supported.

!!! warning “About Ubiquiti SSO accounts” Ubiquiti SSO accounts are not supported and actively discouraged from being used. There is no option to use MFA. You are expected to use local access user. uiprotect is not designed to allow you to use your owner account to access the your console or to be used over the public Internet as both pose a security risk.

Environment Variables

export UFP_USERNAME=YOUR_USERNAME_HERE
export UFP_PASSWORD=YOUR_PASSWORD_HERE
export UFP_ADDRESS=YOUR_IP_ADDRESS
export UFP_PORT=443
# change to false if you do not have a valid HTTPS Certificate for your instance
export UFP_SSL_VERIFY=True

uiprotect nvr

CLI Args

uiprotect -U YOUR_USERNAME_HERE -P YOUR_PASSWORD_HERE -a YOUR_IP_ADDRESS -p 443 --no-verify nvr

Timezones

A number of commands allow you to enter a datetime as an argument or output files with the datetime in the filename. As a result, it is very important for uiprotect to know your consoles local timezone. If you on a physical machine (not docker/VM), chances are this is already set up correctly for you (/etc/localtime), but otherwise you may need to set the TZ environment variable. TZ can also be used to override your system timezone as well if for whatever reason you need to. It should be the Olson timezone name for the timezone that your UniFi Protect Instance is in.

TZ=America/New_York uiprotect --help

Reference

$ uiprotect --help
Usage: uiprotect [OPTIONS] COMMAND [ARGS]...

UniFi Protect CLI

Options

Option

Required?

Env

Type

Default

Description

-U

--username

:white_check_mark:

UFP_USERNAME

text

UniFi Protect username

-P

--password

:white_check_mark:

UFP_PASSWORD

text

UniFi Protect password

-a

--address

:white_check_mark:

UFP_ADDRESS

text

UniFi Protect IP address or hostname

-p

--port

UFP_PORT

integer

443

UniFi Protect port

--no-verify

UFP_SSL_VERIFY

boolean

True

Verify SSL

--output-format

json,plain

plain

Preferred output format. Not all commands support both JSON and plain and may still output in one or the other.

-u

--include-unadopted

Include devices not adopted by this NVR.

--show-completion

Show completion for the current shell, to copy it or customize the installation.

--help

Show help message and exit.

Subcommands

For any subcommand you can use uiprotect COMMAND --help

Command

Description

backup

Backup CLI.

cameras

Camera device CLI.

chimes

Chime device CLI.

decode-ws-msg

Decodes a base64 encoded UniFi Protect Websocket binary message.

doorlocks

Doorlock device CLI.

events

Events CLI.

generate-sample-data

Generates sample data for UniFi Protect instance.

lights

Lights device CLI.

liveviews

Liveviews CLI.

nvr

NVR device CLI.

profile-ws

Profiles Websocket messages for UniFi Protect instance.

sensors

Sensors device CLI.

shell

Opens iPython shell with Protect client initialized.

viewers

Viewers device CLI.

Multiple Item CLI Commands

All adoptable device CLIs, event and liveview CLI work on the idea you have multiple cameras, multiple lights, multiple events or multiple liveviews. As such, they have four variations:

# list all devices (or events/liveviews)
uiprotect cameras

# list short list of all devices (or events/liveviews)
uiprotect cameras list-ids

# list a specific device (or event/liveview)
uiprotect cameras DEVICE_ID

# run a command against a specific device (or event/liveview)
uiprotect cameras DEVICE_ID COMMAND

!!! note The “list all devices” and “list a specific device” commands always return raw JSON. These commands can be paired with jq to parse and quick extra device data from them.

Command

Description

list-ids

Requires no device ID. Prints list of “id name” for each device.

set-person-track

Requires device ID. Sets person auto tracking on or off for PTZ cameras.

Examples
List All Cameras

=== “Plain”

```bash
$ uiprotect cameras list-ids

61b3f5c7033ea703e7000424: G4 Bullet
61f9824e004adc03e700132c: G4 PTZ
61be1d2f004bda03e700ab12: G4 Dome
```

=== “JSON”

```bash
$ uiprotect --output-format json cameras list-ids

[
  [
    "61b3f5c7033ea703e7000424",
    "G4 Bullet"
  ],
  [
    "61f9824e004adc03e700132c",
    "G4 PTZ"
  ],
  [
    "61be1d2f004bda03e700ab12",
    "G4 Done"
  ],
  ...
]
```
Check if a Light is Online
$ uiprotect cameras 61ddb66b018e2703e7008c19 | jq .isConnected
true
Take Snapshot of Camera
$ uiprotectcameras 61ddb66b018e2703e7008c19 save-snapshot output.jpg

Adoptable Devices CLI Commands

Adoptable devices (Cameras, Chimes, Doorlocks, Lights, Sensors, Viewers) all have some commands in common.

Command

Description

adopt

Adopts a device.

bridge

Returns bridge device if connected via Bluetooth.

is-bluetooth

Returns if the device has Bluetooth or not.

is-wifi

Returns if the device has WiFi or not.

is-wired

Returns if the device is wired or not.

protect-url

Gets UniFi Protect management URL.

reboot

Reboots the device.

unadopt

Unadopt/Unmanage adopted device.

update

Updates the device.

Backup CLI

$ uiprotect backup --help

 Usage: uiprotect backup [OPTIONS] COMMAND [ARGS]...

 Backup CLI.
 The backup CLI is still very WIP in progress and consider experimental and potentially unstable (interface may change in the future).
Backup Options

Option

Env

Type

Default

Description

-s

--start

UFP_BACKUP_START

datetime

Cutoff for start of backup. Defaults to start of recording for NVR.

-e

--end

UFP_BACKUP_END

datetime

Cutoff for end of backup. Defaults to now.

--output-folder

UFP_BACKUP_OUTPUT

path

$PWD

Base dir for creating files. Defaults to $PWD.

--thumb-format

text

{year}/{month}/{day}/{hour}/{datetime}{sep}{mac}{sep}{camera_slug}{event_type}{sep}thumb.jpg

Filename format to save event thumbnails to. Set to empty string (“”) to skip saving event thumbnails.

--gif-format

text

{year}/{month}/{day}/{hour}/{datetime}{sep}{mac}{sep}{camera_slug}{event_type}{sep}animated.gif]

Filename format to save event gifs to. Set to empty string (“”) to skip saving event gif.

--event-format

text

{year}/{month}/{day}/{hour}/{datetime}{sep}{mac}{sep}{camera_slug}{event_type}.mp4

Filename format to save event gifs to. Set to empty string (“”) to skip saving event videos.

--title-format

text

{time_sort_pretty_local} {sep} {camera_name} {sep} {event_type_pretty} {sep} {length_pretty}

Format to use to tag title for video metadata.

-v

--verbose

boolean

False

Debug logging.

-d

--max-download

integer

5

Max number of concurrent downloads. Adds additional loads to NVR.

--page-size

integer

1000

Number of events fetched at once from local database. Increases memory usage.

--length-cutoff

integer

3600

Event size cutoff for detecting abnormal events (in seconds).

--sep

boolean

-

Separator used for formatting.

--help

Show help message and exit.

File Name and Title Formatting

There are 5 options controlling output format for file names and metadata. This allows you to customize backups to your liking. All 5 options are a template string. Here are all of the available templating variables:

Variable

Description

year

UTC year of start of export.

month

UTC month of start of export.

day

UTC day of start of export.

hour

UTC hour of start of export.

minute

UTC minute of start of export.

datetime

ISO 8601 formatted UTC datetime of start of export. Uses sep between parts.

date

ISO 8601 formatted UTC date of start of export. Uses sep between parts.

time

UTC time of start of export. Uses sep between parts. 24 hour time.

time_sort_pretty

UTC time of start of export. Uses : between parts. 24 hour time.

time_pretty

UTC time of start of export. Uses : between parts. 12 hour time with AM/PM.

year_local

Local year of start of export.

month_local

Local month of start of export.

day_local

Local day of start of export.

hour_local

Local hour of start of export.

minute_local

Local minute of start of export.

datetime_local

ISO 8601 formatted Local datetime of start of export. Uses sep between parts.

date_local

ISO 8601 formatted Local date of start of export. Uses sep between parts.

time_local

Local time of start of export. Uses sep between parts. 24 hour time.

time_sort_pretty_local

Local time of start of export. Uses : between parts. 24 hour time.

time_pretty_local

Local time of start of export. Uses : between parts. 12 hour time with AM/PM.

mac

MAC address of camera.

camera_name

Name of camera.

camera_slug

Lowercased name of camera with spaces replaced with sep.

event_type

Lowercased name of the event exported.

event_type_pretty

More human readable name of event exported.

length_pretty

Human readable version of the length of the clip exported.

sep

Separator to use in many cases.

Datetimes

All datetimes for the Backup CLi can either be in ISO 8601 format or can be a human readable format that the Python library dateparse can understand. This will allow relative datetimes to be passed, such as "1 hour ago" which will make backing up incremental for cron jobs.

Formatting for Plex

You are able to export your Camera events and then access them in Plex relatively well. For setup in Plex, the following is recommended:

  • Enable the “Local Media Assets” Agent Source for the Movies Library Type (Settings -> Agents -> Movies). Plex docs.

  • Create a “Other Videos” library pointing to the same folder as your –output-folder folder.

    • Scanner: “Plex Video Files Scanner”

    • Agent: “Personal Media”

Recommended formats for the backup command:

Option

Format

--thumb-format

{year_local}/{month_local}/{day_local}/{hour_local}/{title}.jpg

--gif-format

{year_local}/{month_local}/{day_local}/{hour_local}/{title}.gif

--event-format

{year_local}/{month_local}/{day_local}/{hour_local}/{title}.mp4

--title-format

default or whatever you want the title to be in Plex.

Backing Up Camera Events
$ uiprotect backup events --help

 Usage: uiprotect backup events [OPTIONS]

 Backup thumbnails and video clips for camera events.

Option

Type

Default

Description

-t

--event-type

motion, ring, smartDetectZone

motion, ring, smartDetectZone

Events to export. Can be used multiple time.

-m

--smart-type

person, vehicle, package

person, vehicle, package

Smart Detection types to export. Can be used multiple time.

-p

--prune

boolean

False

Prune events older then start.

-f

--force

boolean

False

Force update all events and redownload all clips.

-v

--verify

boolean

False

Verifies files on disk.

--no-input

boolean

False

Disables confirmation prompt if -p and -f both passed.

--help

Show help message and exit.

The backup events command essentially mirrors all of the selected events from your UniFi Protect instance into a local sqlite database (events.db inside of the --output-folder). As a result, the initial run make take a really long time to run if your UniFi Protect instance has a lot of events inside of it.

As an example using a UniFi Protect instance with ~200k events and ~8 months of camera footage:

  • Building the database is in the range of hours

  • Doing the initial download of event thumbnails, gifs and video clips is in the range of tens of hours (potentially 1-2 days)

  • Incremental or targeted backups are much faster (<1 per event)

!!! note “Cron Usage”

For incremental backups in crons, it is recommended you run the command with an absolute start first to build your events database and do an initial download of files. This will significantly speed up the incremental backup commands.
Examples
Backup All Events
uiprotect backup events
Backup All Smart Detections for the Past Hour
uiprotect backup --start "1 hour ago" events -t smartDetectZone
Backup All Person Smart Detections from December 31st at 10PM to January 1st at 5AM
uiprotect backup --start "2021-12-31T22:00:00" --end "2022-1-1T05:00:00" events -t smartDetectZone -m person

Camera CLI

Inherits Multiple Item CLI Commands and Adoptable Devices CLI Commands.

Examples
Take Snapshot of Camera
$ uiprotect cameras 61ddb66b018e2703e7008c19 save-snapshot output.jpg
Export Video From Camera
$ uiprotect cameras 61ddb66b018e2703e7008c19 save-video export.mp4 2022-6-1T00:00:00 2022-6-1T00:00:30

!!! note “Timezones”

See the section on [Timezones](#timezone) for determined what timezone your datetimes are in.
Play Audio File to Cameras Speaker
$ uiprotect cameras 61ddb66b018e2703e7008c19 play-audio test.mp3
Include Unadopted Cameras in list
$ uiprotect -u cameras list-ids
Adopt an Unadopted Camera
$ uiprotect -u cameras 61ddb66b018e2703e7008c19 adopt
Enable SSH on Camera
$ uiprotect cameras 61ddb66b018e2703e7008c19 set-ssh true

# get current value to verify
$ uiprotect cameras 61ddb66b018e2703e7008c19 | jq .isSshEnabled
true
Reboot Camera
$ uiprotect lights 61b3f5c801f8a703e7000428 reboot
Reboot All Cameras
for id in $(uiprotect cameras list-ids | awk '{ print $1 }'); do
    uiprotect cameras $id reboot
done

Chime CLI

Inherits Multiple Item CLI Commands and Adoptable Devices CLI Commands.

Examples
Set Paired Cameras
$ uiprotect chimes 6275b22e00e3c403e702a019 cameras 61ddb66b018e2703e7008c19 61f9824e004adc03e700132c