bru-run

Generic shell CLI for running Bruno collections from any project — not tied to one API.

Requirements

• bash 4.0+ — the CLI is written in bash, not POSIX sh. Linux ships bash 4+ by default on essentially every mainstream distro. macOS does not — Apple has frozen macOS's system bash at 3.2 since 2007 (licensing, not neglect), so macOS users need brew install bash first. Check your version with bash --version; anything below 4.0 will fail with a clear error pointing back here.
• jq — used to patch and read JSON payloads.
• fzf — optional, only needed for the interactive request/environment pickers.
• The Bruno CLI (bru) — runs the actual request.

What it does

Point it at a project's Bruno collection with a .bru-run.yml file, and run requests by search term or path, from any directory:

Run bru-run --help (or -h) any time for a quick reference of every flag.

bru-run item list --env dev --show
bru-run --list
bru-run --docs item create

Secrets for each environment live outside any repo, in ~/.bru-run/<namespace>/<env>.bru — never committed, never gitignored (a gitignored secret is still one git add -A away from a leak; a secret that physically isn't in the tree can't leak through git at all).

Setup

Run this at the root of the project the Bruno collection belongs to. The collection does not have to exist yet — init is also how you start a fresh one:

bru-run init

It writes a .bru-run.yml at the project root and registers the project, so -p my-project works from anywhere right away:

namespace: my-project
collection: ./bruno
env_helper: ~/.bru-run/my-project

bru-run also finds this config by walking up from wherever it's run, the same way git finds .git.

First run

bru-run init prints the four steps from a fresh config to a real request. Two of them are easy to miss:

bru-run init                     # writes .bru-run.yml, registers the project

# 1. create ./bruno/ and ./bruno/environments/dev.bru
bru-run <request> --env dev      # 2. creates ~/.bru-run/my-project/dev.bru with one
                                 #    empty slot per secret, then stops
# 3. fill in the values in that file
bru-run <request> --env dev      # 4. run the same command again for the real request

Secrets live under env_helper (~/.bru-run/<namespace>/ by default), never in the repo. Step 2 only creates the file when the environment declares secrets; an environment with none runs straight away.

Running against a git worktree

A worktree can have its own in-progress collection. --branch (-b) uses it without cd-ing there, looking under .claude/worktrees/<branch-slug>/ at the main checkout's root, where <branch-slug> is the branch name with every / replaced by -:

bru-run -p my-project -b my-branch --list

To see which worktrees exist and which ones are ready, use --branches (-B):

$ bru-run -p my-project -B
👩‍💻 worktrees for my-project
  my-branch        ✓ has .bru-run.yml
  another-branch   ✗ missing

A worktree needs its own .bru-run.yml before -b can use it. bru-run never creates it — both -B and a failed -b print the cp command to run.

Protecting an environment

Add protected_envs to guard sensitive environments like prod:

protected_envs: [prod]

bru-run --env prod ... then fails unless --confirm is also passed. This is the only environment-safety check the code enforces — a project with no protected_envs key has none, and it is the project's own choice which names go in the list.

Chaining values between requests

Every bru run is its own process, so a value one request returns is gone before the next one starts. Point chained_vars at a file and bru-run writes those values back into the env file, where the next request can read them:

chained_vars: ./bruno/chained-vars.tsv

The file holds one pair per line — the variable name, a run of whitespace, then a jq expression run against the response body. Blank lines and # comments are ignored:

itemId	.result.item.id // .result.items[0].id
itemName	.result.item.name

After each run, bru-run prints the names it saved, never the values. What the expressions match is specific to one API's response shapes, so bru-run ships no map of its own — see examples/pompom-time/bruno/chained-vars.tsv.

Install

Homebrew — also pulls in jq and a modern bash:

brew install nathpaiva/tap/bru-run

Or npm:

npm install -g bru-run

Either way, the Bruno CLI (bru) still has to be on your PATH — it is not a Homebrew formula:

npm install -g @usebruno/cli

fzf is optional, only for the interactive pickers. With npm you also need bash 4+ and jq yourself (see Requirements).

To hack on bru-run itself, clone the repo and run npm link instead.

Example

examples/pompom-time/ is a small fake collection used to prove the design end to end — invented endpoints, no real data.

cd examples/pompom-time
bru-run --list

Claude skill

skill/SKILL.md teaches an agent to use bru-run safely: never print a secret, never edit a saved .bru, discover requests via --list/--docs instead of grep. It carries no project-specific rules (like which environment is production) — that's for whoever configures a project's own skill instance to add.

Status

Released, 1.0.0. See issue #1 for the original design notes.