Command-line tool (CLI)

Install the brix CLI from npm. List screens, reboot or screenshot a display, upload media, cast content and send emergency alerts from your terminal.

View as Markdown · For AI agents: the full docs index is at /llms.txt

The brix command-line tool controls your Brix screens from a terminal or a script. It calls the REST API with your API key. It has commands for the common tasks and one generic command that calls any operation in the OpenAPI spec.

The npm package name is brixsignage. The command is brix.
It has no dependencies. It needs Node.js 18.17 or later.
It runs on macOS, Linux and Windows.

Install

npm install -g brixsignage
brix --help

To run one command without an install:

npx brixsignage screens

Log in

In the Brix console, go to Settings > AI, API & MCP and create an API key. Give it only the permissions the CLI needs. See Authentication and scopes.
Run brix login and paste the key. The CLI does not show the key while you paste it.
Run brix whoami to see the workspace, the key and its permissions.

The CLI checks the key with GET /v1/me, then saves it in ~/.config/brix/config.json. Only your user can read that file. brix logout removes it.

In CI or a script, set BRIX_API_KEY instead of brix login. The environment variable has priority over the saved key.

Screens

brix screens                                  # all screens, as a table
brix screens --search lobby
brix screens get scr_0123456789abcdef
brix screens diagnose scr_0123456789abcdef    # what the screen does now and why
brix screens reboot scr_0123456789abcdef
brix screens refresh scr_0123456789abcdef
brix screens screenshot scr_0123456789abcdef
brix screens command scr_0123456789abcdef set-volume --payload '{"level":40}'
brix screens assign scr_0123456789abcdef playlist pl_0123456789abcdef
brix screens assign scr_0123456789abcdef --clear

A device runs a command the next time it checks in. The CLI prints the command ID. To read the result, run brix call getScreenCommand --param id=<screen> --param commandId=<command>.

Content

brix media                                    # the media library
brix media --search menu --kind video
brix media upload ./spring-menu.mp4 --name "Spring menu"
brix media import https://example.com/promo.jpg
brix playlists
brix playlists get pl_0123456789abcdef
brix schedules
brix layouts

Casts and emergency alerts

A cast puts content on screens for a set time. Then the screens go back to their usual content.

brix cast playlist pl_0123456789abcdef --screens scr_a,scr_b --for 30m
brix cast media med_0123456789abcdef --node loc_0123456789abcdef --until 2026-12-24T18:00:00Z
brix casts
brix casts end cast_0123456789abcdef

An emergency alert shows above all other content until you clear it or it expires.

brix emergency "Please leave the building by the nearest exit" --all --severity critical
brix emergencies
brix emergencies clear emg_0123456789abcdef

cast and emergency need one target: --all, --node <locationId> or --screens <id,id>. Without a target, the CLI stops and sends nothing. The API sends an unscoped cast to every screen, so the CLI makes you choose.

Any API operation

brix ops                       # every operation, from the OpenAPI spec
brix ops webhook               # search by name, path or summary
brix call getScreen --param id=scr_0123456789abcdef
brix call createPlaylist --data '{"name":"Lobby loop"}'
brix call updateSchedule --param id=sch_0123456789abcdef --data @schedule.json
brix api GET /v1/me

--param (or -p) fills path parameters such as {id}. Other parameters go in the query string. --data takes JSON, or @file.json to read a file.

Output for scripts

Add --json to any command to get the raw API response:

brix screens --json | jq -r '.data[] | select(.status != "online") | .name'

Exit codes: 0 success, 1 the API refused the request, 2 a usage error, 3 no API key.

Options

Option	Environment variable	Default
`--api-key <key>`	`BRIX_API_KEY`	The key from `brix login`
`--api-url <url>`	`BRIX_API_URL`	`https://api.brixsignage.com`
	`BRIX_CONFIG_DIR`	`~/.config/brix`

Quickstart: the same tasks with curl.
TypeScript SDK: typed calls from your own code.
Connect an AI agent (MCP): let Claude or ChatGPT operate your screens.
Source: github.com/BenLoveitt/brix-stack/tree/main/packages/cli. Package: npmjs.com/package/brixsignage.