CLI Reference

Complete reference for the Be Right Back command model, built-in commands, and runtime behaviour.

If you're looking for installation and first-run setup, start with Quick Start.

Running

brb <command> [args...]

Place brb directly before any command you want to monitor:

brb cargo test
brb pnpm build
brb python script.py

Runtime Behaviour

When you run a wrapped command, brb:

Loads and validates the global config.
Resolves channels from default_channels or any --channel flags.
Runs the wrapped command with inherited terminal I/O.
Builds a completion event after the command exits.
Attempts delivery to each selected channel.
Exits with the wrapped command's exit code.

Exit Codes

Notification delivery failures never replace the wrapped command result. If the wrapped command exits with 17, brb exits with 17. If the wrapped command cannot be started, brb exits with 127.

Global Option

Channel Override

Use --channel to override default_channels for a single run.

brb --channel desktop --channel ci-webhook cargo test

Rules

If one or more --channel flags are provided, only those channels are used.
If no --channel flags are provided, default_channels is used.
If any selected channel ID does not exist in config, brb exits with an error before running the command.

Pass Through Command Flags

brb [--channel <channel-id> ...] -- <command> [args...]

If the wrapped command itself begins with flags, use -- to separate brb flags from wrapped-command flags.

Example:

brb --channel desktop -- --version

In this example, --version is passed to the wrapped command, not to brb.

Built-In Commands

Command	Description
`brb init`	Creates the default global config file if it does not already exist. If it already exists, prints the existing path and exits successfully.
`brb channels`	Lists configured channels, their types, and which ones are included in `default_channels`.
`brb channels list`	Same as `brb channels`.
`brb channels validate`	Loads and validates the config, then exits. Useful after editing config files.
`brb channels test <channel-id>`	Sends a synthetic success event to one configured channel so you can verify delivery without waiting for a real command.
`brb config`	Prints the active global config path.
`brb config path`	Same as `brb config`.