Bro

Appearance

Getting Started with Bro in 5 Minutes ​

This tutorial takes you from zero to a cached task run. No prior knowledge of Bro — or of any build tool — is required. Every command is meant to be copied and pasted as-is.

You will:

  1. Install Bro.
  2. Write a one-task bro.yaml.
  3. Run it twice and see the second run served from cache.
  4. Change an input and watch Bro re-run exactly what changed.
  5. Clean up.

1. Install Bro ​

Pick one of the following.

Linux / macOS:

bash
curl -fsSL https://hypervapor.org/bro/install.sh | sh

The script detects your OS/architecture, downloads the latest release archive, verifies its checksum, and installs bro into /usr/local/bin (falling back to ~/.local/bin without sudo).

Windows (PowerShell):

powershell
irm https://hypervapor.org/bro/install.ps1 | iex

The script detects the architecture, verifies the checksum, installs to %LOCALAPPDATA%\Programs\bro, and adds it to your PATH.

Verify the install:

bash
bro version
bro version v0.1.0

2. Create a project ​

Bro has no init command — a project is just a directory with a bro.yaml. Create one:

bash
mkdir line-counter && cd line-counter

cat > bro.yaml <<'EOF'
version: "1"

tasks:
  count:
    cmd: "wc -l < lines.txt > count.txt && cat count.txt"
    inputs: ["lines.txt"]
    outputs: ["count.txt"]
EOF

printf 'one\ntwo\nthree\n' > lines.txt

What the task says: run wc -l over lines.txt, write the result to count.txt, and print it. The inputs/outputs declarations are what make the task cacheable: Bro hashes the inputs, and stores/restores the outputs.

Commands run in an embedded POSIX shell, so the same bro.yaml behaves identically on Linux, macOS, and Windows.

3. Run it ​

bash
bro list
count
bash
bro run count
[count] $ wc -l < lines.txt > count.txt && cat count.txt
3
[count] done (2ms)

1 tasks, 0 cached, 1 executed, 4ms total

count.txt now exists and contains 3.

4. Run it again — cache hit ​

bash
bro run count
[count] cached (0ms)
3

1 tasks, 1 cached, 0 executed, 0ms total

Nothing was re-executed: Bro hashed lines.txt, found a cache entry for that exact fingerprint, restored count.txt from it, and replayed the recorded output (the 3 you see). On a real project this is where seconds or minutes of build time turn into milliseconds.

5. Change an input — automatic invalidation ​

bash
printf 'four\n' >> lines.txt
bro run count
[count] $ wc -l < lines.txt > count.txt && cat count.txt
4
[count] done (2ms)

1 tasks, 0 cached, 1 executed, 4ms total

Changing a declared input changed the fingerprint, so the task re-ran. Files not listed in inputs never trigger a re-run — declare your inputs completely and Bro never serves you a stale result.

6. Clean up ​

bash
bro clean --outputs
cleared cache /path/to/line-counter/.bro/cache
removed 1 declared output path(s)

bro clean empties the local cache (.bro/cache); --outputs additionally deletes every declared output path (count.txt here).

Where to go next ​

  • examples/ in the repository — a shell-only pipeline and a Go project (test → build) you can run immediately.
  • docs/best-practices.md — how to declare inputs correctly (the part that determines whether your cache is hit or silently missed).
  • docs/technical-specification.md — full bro.yaml field reference (Section 3), remote cache setup (Section 9), and the CLI (Section 13).
  • bro run <task> --verbose shows fingerprint computation and cache lookups; bro watch <task> re-runs automatically when inputs change.

MIT License