Skip to content

The terminal console (nvrctl)

nvrctl is Aperture’s admin tool for the terminal. Run it without arguments and it opens a full-screen console where you sign in and manage cameras, users, storage and a few integrations. Its subcommands (status, cameras, users, storage, events) print quick read-outs using a local token, without signing in. This page covers both, the token, and using nvrctl over SSH and in scripts.

The installer puts it at /usr/bin/nvrctl on the Aperture server.

Flag Default Purpose
--url $APERTURE_URL, else http://localhost:8971 The address of Aperture’s API.
--token read from cli.token The CLI token for the subcommands. See The CLI token.
--version Prints the version and exits.
-h, --help Help for nvrctl or any subcommand.

On the server itself the default URL is right for a standard install. To manage another Aperture, pass --url http://192.168.1.10:8971.

Start it with either command:

Terminal window
nvrctl
nvrctl tui

It takes over the terminal window and gives it back when you quit.

The console opens on a sign-in card. Enter your Email and Password and press Enter. Tab moves between the fields; Esc quits.

Sign in with an administrator account; most screens need administrator rights.

If the account has two-factor authentication turned on, the card then asks for the Code: “From your authenticator app, or one of your recovery codes.” Type it and press Enter; a wrong code clears the field so you can type it again. Esc goes back to email and password. The console never marks the terminal as a trusted device, so it asks for a code at every sign-in.

The console has no passkey or single sign-on step. An account that signs in only through single sign-on has no password and cannot use the console; use another administrator account, or the subcommands, which do not sign in.

After a successful sign-in, the console remembers the session for 7 days, so the next nvrctl opens straight on the menu. The session is saved to the first of these that applies:

  1. the file named by APERTURE_SESSION_FILE,
  2. $XDG_STATE_HOME/aperture/nvrctl-session.json,
  3. ~/.local/state/aperture/nvrctl-session.json.

The file is readable only by you (mode 0600, in a 0700 folder). A saved session is only used for the same --url it was made for. If the server no longer accepts it, the console quietly returns to the sign-in card. Log out in the menu ends the session on the server and deletes the file.

The menu lists:

Screen What you can do
Dashboard Cards for cameras (online of total), cameras recording, footage recorded, free disk space and events today, a camera list with a status dot and each recording mode, and the most recent events. r refreshes it; the old figures stay until the new ones arrive.
Cameras Every camera with a dot (● enabled, ○ disabled), its mode and its link, login masked. + Add camera at the top adds one.
Users & roles Every user with email, name and role. + Add user at the top adds one.
Storage Footage recorded and free disk space, footage per camera, and three delete actions.
System The Site name.
Home Assistant The MQTT connection: Publish to MQTT, Broker URL, Username, Password, Discovery prefix.
Single sign-on The OIDC settings: Enable SSO, Button label, Issuer URL, Client ID, Client secret, Restrict to email domain, Auto-create as viewers, and the Redirect URI to register with your provider. See Single sign-on.
Log out, Quit

The camera form has Name, Main RTSP URL, Sub-stream URL, Record mode (continuous, motion, scheduled, never), Enabled, Retention (days), Motion sensitivity (a number from 0 to 1; lower is more sensitive, default 0.02), Pre-roll (s), Post-roll (s), Cooldown (s), Ignore blips under (s) and Capture FPS (0 = the camera’s rate). Links show the login as dots and follow the same rules as in the web app: leave the dots to keep the saved login, type over them to change it. See Camera passwords stay on the server. Everything else (zones, schedules, groups, storage destinations, recording quality, detection details) is set in the web app.

The user form has Email, Name, Role (viewer or admin) and Password (at least 8 characters). When editing, the email cannot be changed, a blank password keeps the current one, and Disabled switches the account off. You cannot delete your own account. A viewer created here has access to no cameras until you grant some in the web app under Users.

The Home Assistant screen has no field for the Sensor state topic used by overlay sensors. Saving the screen keeps the topic that is set; change it in the web app.

Where Keys
Everywhere Ctrl+C quits.
Lists and the menu ↑/↓ or k/j move, g/Home and G/End jump to the top and bottom, Enter, l or Space open the selected row, d deletes the selected camera or user, Esc or Backspace go back to the menu, q goes back (and quits from the menu).
Forms Tab/↓ and Shift+Tab/↑ move between fields, ←/→ or Space change a choice or a switch, Enter moves to the next field and saves on the last one, Ctrl+S saves, Esc goes back without saving.
Dashboard r refreshes the figures.
Confirmations y or Enter confirms, n or Esc cancels.

The console also takes the mouse, if your terminal passes it on: click a row to open it, scroll the wheel to move the selection, and click a field in a form to focus it. On the sign-in card, clicking the upper half focuses Email and the lower half Password.

The subcommands print one read-out and exit. They authenticate with the CLI token, not with your account, so they need no sign-in and work for accounts with two-factor authentication too.

Command Shows
nvrctl status Version, cameras online and in total, cameras recording, footage recorded and disk space, events today.
nvrctl cameras Every camera: status dot, name, recording mode, main link with the login masked.
nvrctl users Every user: email, name, role, and camera access (all for administrators, otherwise the number of cameras).
nvrctl storage Footage recorded and disk space, then each camera’s footage size and number of clips, largest first.
nvrctl events The 30 most recent events of the last 7 days: time, camera, type (motion, audio, package).

Example output of nvrctl status:

Aperture NVR 1.4.0 (3f2a9c1)
Cameras 4 online / 4 total
Recording 3 cameras
Storage 812 GB recorded · 1.1 TB free of 3.6 TB
Events 27 today

The first number after Cameras counts the cameras video is arriving from, the same test the web app uses for “online” (see Camera status). A disabled camera never counts. Disk figures are for the disk that holds the local recordings folder. Sizes use 1024-based units.

nvrctl cameras looks like this:

NAME MODE SOURCE
● Front door continuous rtsp://•••••:•••••@192.168.1.21:554/stream1
● Driveway motion rtsp://•••••:•••••@192.168.1.22:554/Preview_01_main
○ Garage never rtsp://•••••:•••••@192.168.1.23:554/stream1

The dot is green while video arrives, red for an enabled camera that sends nothing, and hollow for a disabled camera. The console’s Dashboard uses the same dots; its Cameras screen shows only enabled (●) or disabled (○).

nvrctl events:

WHEN CAMERA TYPE
Nov 15 14:02:11 Driveway motion
Nov 15 13:58:40 Front door package
Nov 15 13:41:07 Garden audio

On error, nvrctl prints error: <message> to standard error and exits with status 1.

When Aperture starts for the first time, it generates a random CLI token, stores it with its other secrets and writes a copy to cli.token in its data folder. On a standard install that is /var/lib/aperture/data/cli.token, owned by the aperture service user with mode 0600, so only that user and root can read it. The token does not change on its own.

Unless you pass --token, nvrctl looks for the file in this order:

  1. $APERTURE_DATA_DIR/cli.token,
  2. /var/lib/aperture/data/cli.token, where the installer puts it,
  3. /data/cli.token,
  4. ./data/cli.token,
  5. ./deploy/data/cli.token.

On a standard install, run the subcommands as root on the server:

Terminal window
sudo nvrctl status

Without a token, a subcommand fails with “no CLI token found — pass –token or run where data/cli.token is readable”.

The CLI token carries full administrator authority. The server treats a request carrying it as a built-in administrator called nvrctl, with every permission, including the operations that API tokens are never allowed (users, backups and similar). Actions taken with it appear in the Activity Log as cli@local.

It is not tied to a user account, and some things need one. Creating API tokens with it fails with “could not create token”, because a token must belong to a real user. Use the web app, signed in as yourself, for anything that belongs to your own account. An extension installed with the CLI token is recorded as installed by the first administrator.

The usual way to use nvrctl from another computer is to run it on the server over SSH. The console needs a terminal, so ask SSH for one with -t:

Terminal window
ssh -t alex@192.168.1.10 nvrctl

The saved session then lives in that account’s home folder on the server. For the subcommands, use sudo:

Terminal window
ssh -t alex@192.168.1.10 'sudo nvrctl status'

You can also build nvrctl on your own Linux machine from a checkout of the repository with make install-cli, which puts it in ~/.local/bin, and point it at the server with --url http://192.168.1.10:8971. The console works that way. The subcommands would need the CLI token on your machine, which the warning above advises against; prefer SSH for them.

The subcommands print tables for people to read, not a stable format for programs. For scripts, call the API directly and read JSON. On the server, the CLI token works as a bearer token:

Terminal window
TOKEN=$(sudo cat /var/lib/aperture/data/cli.token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8971/api/v1/cameras \
| jq -r '.[] | "\(.name)\t\(.recordMode)\t\(.enabled)"'
Front door continuous true
Driveway motion true
Garage never false

A check you can run from cron, which prints every camera that should be recording but is not:

Terminal window
TOKEN=$(cat /var/lib/aperture/data/cli.token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8971/api/v1/system/status \
| jq -r '.cameras[] | select(.recordingState == "failed") | .name'

recordingState is recording, notScheduled, off or failed, the same states the Recording column in Devices shows. Run it as root, which can read the token.

For anything that runs off the server, or for long-lived automation, create a scoped API token in the web app instead: it can be limited to the actions and cameras the script needs, and revoked on its own.

Related: API · Configuration · Security · Troubleshooting