brb

brb wraps a command, waits for it to finish, then sends a completion event to your configured channels.

Useful for long builds, test suites, data jobs, and deploys you do not want to watch in real time.

See documentation here.

Install

cargo install brb-cli

Quick Start

Create the global config:

brb init

Check where it lives:

brb config path

Start with a minimal config:

version: 1
default_channels:
  - desktop
channels:
  desktop:
    type: desktop

Validate it:

brb channels validate

Send a test notification:

brb channels test desktop

Run something:

brb cargo test

Override channels for one run:

brb --channel desktop --channel ci-webhook pnpm test

How It Works

When you run brb, it:

1. Loads your global config.
2. Resolves channels from default_channels or repeated --channel flags.
3. Runs the wrapped command with inherited stdin, stdout, and stderr.
4. Builds a completion event.
5. Delivers that event to each selected channel independently.
6. Exits with the same code as the wrapped command.

If the wrapped command exits with 17, brb exits with 17. If the command cannot be started, brb exits with 127.

Platform Support

Channel	Linux	macOS	Windows
desktop	notify-send	osascript	Not implemented yet
webhook	Supported	Supported	Supported
custom	Supported	Supported	Supported

A full example config is included at assets/examples/config.yml.

Config

brb uses one global YAML config file.

Minimal config:

version: 1
default_channels:
  - desktop
channels:
  desktop:
    type: desktop

Rules:

• version must be 1
• channels must contain at least one channel
• default_channels must contain at least one channel ID
• every ID in default_channels must exist under channels

Channel Types

Type	Purpose	Required	Optional
desktop	Local desktop notification	type	none
webhook	HTTP JSON delivery	type, url	method, headers
custom	Run your own notifier process	type, exec	args, env

Environment Variables

webhook and custom string values support ${env:VAR_NAME} interpolation.

Example:

channels:
  ci-webhook:
    type: webhook
    url: ${env:BRB_WEBHOOK_URL}
    headers:
      Authorization: Bearer ${env:BRB_WEBHOOK_TOKEN}

Event Payload

webhook and custom channels receive a completion payload like this:

{
  "tool": "brb",
  "status": "success",
  "command": ["pnpm", "test"],
  "cwd": "/path/to/project",
  "started_at": "2026-02-22T12:00:00.000Z",
  "finished_at": "2026-02-22T12:00:03.250Z",
  "duration_ms": 3250,
  "exit_code": 0,
  "host": "my-machine"
}

brb channels test sends a synthetic success event with this same shape.