# 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.

For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Source: https://brixsignage.com/developers/cli/

The `brix` command-line tool controls your Brix screens from a terminal or a script. It calls the [REST API](https://brixsignage.com/developers/api/) with your API key. It has commands for the common tasks and one generic command that calls any operation in the [OpenAPI spec](https://api.brixsignage.com/v1/openapi.json).

- 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

```bash
npm install -g brixsignage
brix --help
```

To run one command without an install:

```bash
npx brixsignage screens
```

## Log in

1. 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](https://brixsignage.com/developers/authentication/).
2. Run `brix login` and paste the key. The CLI does not show the key while you paste it.
3. 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

```bash
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

```bash
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.

```bash
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.

```bash
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

```bash
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:

```bash
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` |

## Related

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