Skip to content
Download

Bruno CLI: Run and Test Your Collections from the Command Line

Picture of Ryan Reynolds

Bruno gives you a built-in Collection Runner with unlimited runs (unlike other API clients), but as you get your tests standardized often there's a need for more flexibility and automation.

The Bruno CLI allows you to skip the GUI and run your Bruno collections straight from the shell. At the time of this writing, our npm package is getting roughly 120,000 downloads a week - so you'll be in good company with other devs that have baked Bruno CLI into their workflows. 

This posts walks through how to get started with the CLI as well as some more advanced options for configuration and running. 

Key Benefits for Devs

  • Collections as Code
    Store collections alongside your repo—diffs, PR reviews, branches, everything code-centric.
  • Built-In Reporters
    Out-of-the-box JSON, JUnit & HTML outputs for CI dashboards or local debugging.
  • Env & Secrets Control
    Swap environments with `--env`, pass environment variables with `--env-var`
  • Data-Driven Tests
    Pipe in CSV or JSON to auto-iterate tests—no need to write loops in code.

Quickstart

  1. Install CLI
    npm install -g @usebruno/cli
  2. Run your suite
    bru run
  3. Check results
    Instant pass/fail summary, timings, and assertion errors right in your console.

Below I've run a collection that has contract tests using Zod, which can be found in a previous blog post.  We can see the total number of requests, tests, and assertions that were run, as well as any failure details. 

Advanced Usage

Easily switch between environments (e.g. test, staging, prod 😈) with:

  • Select env: 
    bru run --env Staging

Variables marked as secrets in the Bruno app aren’t exposed via CLI. Pass them explicitly:

  • Override secret: 
    bru run --env-var API_TOKEN=xxx

To data-drive your runs, point at a CSV or JSON file:

  • CSV data: 
    bru run users --csv-file-path data/users.csv
  • JSON data: 
    bru run orders --json-file-path data/orders.json

Generate HTML, JUnit, and/or JSON reports. Great for integration into an existing test suite or reporting engine. 

bru run request.bru --reporter-json results.json 
                    --reporter-junit results.xml 
                    --reporter-html results.html

CI Integration Snippet

name: API Tests

on: [push]

jobs:
  api-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @usebruno/cli
      - run: |
          bru run \
            --env CI \
            --reporter-json ci-report.json \
            --bail
            • --bail stops on first failure.
            • Add --reporter-html report.html for visual overviews.

Learn More

🛠️ Peek the code or open issues on GitHub. Happy testing!