Skip to main content
Bruno CLI lets you run API collections from the terminal — ideal for automation, CI/CD pipelines, and repeatable test runs. This guide walks you through installing the CLI, running collections, generating reports, and integrating with your workflow.

​
Prerequisites

  • A basic understanding of HTTP and REST
  • Node.js (v18 LTS or higher recommended)
  • Git (to clone the sample collection)

​
Getting started

Use the Bruno Starter Guide collection as the hands-on sample for this walkthrough. It contains example requests, tests, assertions, and a local environment — the same collection used in the Bruno Quick Start. Clone the repository: 
git clone https://github.com/bruno-collections/bruno-starter-guide.git
cd bruno-starter-guide
Use the Bruno Starter Guide as a reference while following this guide. If a step fails, open the collection in Bruno to compare your setup with the expected request configuration.
Work through the steps in order. Each step assumes the previous one.

​
1. Install Bruno CLI

Objective: Install Bruno CLI globally and verify it is available in your terminal. 
npm install -g @usebruno/cli
Verify the installation: 
bru --version
You should see the installed version number (for example, 3.4.2). Success Criteria:
  • bru command is available in your terminal.
  • bru --version prints a version number without errors.
More: Installation

​
2. Run the entire collection

Objective: Execute all requests in the Bruno Starter Guide collection from the command line. Make sure you are inside the cloned collection directory (the folder containing opencollection.yml): 
cd path/to/bruno-starter-guide
bru run
Bruno CLI runs each request sequentially and prints a summary table when finished: 
01-github-api (200 OK) - 471 ms
02-echo-bru (getaddrinfo ENOTFOUND {{baseurl}})
03-script-request (200 OK) - 1186 ms
...

📊 Execution Summary
┌───────────────┬────────────────────────┐
│ Metric        │         Result         │
├───────────────┼────────────────────────┤
│ Status        │         ✗ FAIL         │
├───────────────┼────────────────────────┤
│ Requests      │ 5 (4 Passed, 1 Failed) │
└───────────────┴────────────────────────┘
Some requests may fail without an environment — that is expected. You will fix this in the next step. Success Criteria:
  • bru run executes without installation errors.
  • CLI output lists all five requests in the collection.
  • An execution summary table is displayed at the end.
More: Command Examples

​
3. Run with an environment

Objective: Run the collection using the local environment so variable placeholders like {{baseURL}} resolve correctly. The Bruno Starter Guide includes a local environment at environments/local.yml with a baseURL variable. Activate it with the --env flag: 
bru run --env local
With the environment applied, requests that depend on {{baseURL}} resolve and their tests and assertions run: 
02-echo-bru (200 OK) - 1067 ms
Tests
   ✓ body has title
   ✓ 200 status code
Assertions
   ✓ res.status: eq 200
   ✓ res.body.title: eq Bruno
Success Criteria:
  • bru run --env local completes with ✓ PASS in the execution summary.
  • Tests and assertions for 02-echo-bru pass (green checkmarks).
  • All five requests show a successful status.
More: Environment Variables

​
4. Run a single request

Objective: Run one specific request instead of the entire collection. Specify the request file path after bru run: 
bru run 01-github-api.yml
Bruno CLI executes only that request: 
01-github-api (200 OK) - 148 ms

📊 Execution Summary
┌───────────────┬──────────────┐
│ Status        │    ✓ PASS    │
│ Requests      │ 1 (1 Passed) │
└───────────────┴──────────────┘
You can also run multiple files or folders in one command: 
bru run 01-github-api.yml 03-script-request.yml
Success Criteria:
  • Only the specified request runs.
  • Execution summary shows 1 (1 Passed).
  • Response status is 200 OK.

​
5. Run requests with tests only

Objective: Filter the collection run to requests that have tests or active assertions. Use the --tests-only flag to skip requests without tests: 
bru run --env local --tests-only
Only 02-echo-bru (which has tests and assertions) is executed: 
02-echo-bru (200 OK) - 1158 ms
Tests
   ✓ body has title
   ✓ 200 status code
Assertions
   ✓ res.status: eq 200
   ✓ res.body.title: eq Bruno

📊 Execution Summary
│ Requests      │ 1 (1 Passed) │
│ Tests         │     2/2      │
│ Assertions    │     2/2      │
Success Criteria:
  • Only requests with tests or assertions are executed.
  • Tests show 2/2 passed.
  • Assertions show 2/2 passed.
More: Command Options

​
6. Generate test reports

Objective: Export test results to HTML, JSON, and JUnit report files. Run the collection with reporter flags to write results to disk: 
bru run --env local \
  --reporter-html results.html \
  --reporter-json results.json \
  --reporter-junit results.xml
When the run completes, Bruno CLI writes the report files: 
Wrote html results to results.html
Wrote json results to results.json
Wrote junit results to results.xml
Open results.html in a browser for a visual summary. Use results.json for programmatic analysis or results.xml for CI tools that consume JUnit format. Success Criteria:
  • results.html, results.json, and results.xml are created in the current directory.
  • HTML report opens in a browser and shows request results.
  • JSON and XML files contain test execution data.
More: Generating Reports

​
7. Data-Driven Testing

Objective: Create a CSV or JSON data file, use row values in the 02-echo-bru request, and run it from the CLI with an HTML report. The Bruno Starter Guide includes 02-echo-bru, a POST request to the echo.usebruno.com endpoint. You will send a different JSON body on each iteration using data from a file.

​
Update the request in Bruno

  1. Open the Bruno Starter Guide collection in Bruno.
  2. Open the 02-echo-bru request.
  3. Select the local environment (top-right).
  4. Go to the Body tab and update the JSON to use placeholders that match your data file columns:
{
  "title": "{{title}}",
  "msg": "{{msg}}"
}
  1. Save the request.
The data file does not replace your request body automatically. Each column (CSV) or key (JSON) becomes an iteration variable. Use {{columnName}} in the body so Bruno sends that row’s values on each run.

​
Create a data file

Create one of the following files in your collection folder (bruno-starter-guide/):
Create users.csv:
title,msg
Bruno,Loved by developers. Built for developers.
Opensource,Git-friendly API client.
CLI,Run collections from the terminal.

​
Try it in the Bruno app (optional)

  1. Open the collection Runner (runner icon in the top right corner).
  2. Attach users.csv or users.json as the data file.
  3. Select the local environment and run 02-echo-bru.
  4. Review the Timeline to confirm each iteration sent a different title and msg.

​
Run from the CLI

From the collection directory, run 02-echo-bru once per data row and write an HTML report: 
bru run --env local 02-echo-bru.yml \
  --csv-file-path users.csv \
  --reporter-html results.html
Bruno CLI runs the request three times (once per row) and creates results.html: 
02-echo-bru (200 OK) - 1067 ms
02-echo-bru (200 OK) - 1042 ms
02-echo-bru (200 OK) - 1038 ms

📊 Execution Summary
│ Status        │    ✓ PASS    │
│ Requests      │ 3 (3 Passed) │

Wrote html results to results.html
Open results.html in your browser for a visual summary of all three iterations. See Generating Reports for JSON, JUnit, and other reporter options. Success Criteria:
  • users.csv or users.json exists in the collection folder with title and msg columns.
  • 02-echo-bru body uses {{title}} and {{msg}}.
  • CLI run completes with 3 (3 Passed) in the execution summary.
  • results.html is created and shows one result per data row.
More: Data Driven Testing · Command Examples · Generating Reports

​
8. Override environment variables

Objective: Pass or override environment variables at runtime without editing environment files. Use the --env-var flag to set variables on the command line. This is useful for secrets and CI-specific values: 
bru run --env local --env-var baseURL=https://echo.usebruno.com
You can chain multiple overrides: 
bru run --env local \
  --env-var baseURL=https://echo.usebruno.com \
  --env-var API_KEY=your-key-here
Variables marked as secrets in the Bruno app are not accessible via the CLI. Pass them directly with --env-var.
Success Criteria:
  • Collection runs successfully with overridden variables.
  • No changes are required to environment files on disk.
More: Command Examples

​
9. Import an OpenAPI specification

Objective: Create a Bruno collection from an OpenAPI spec using the CLI. Bruno CLI can import OpenAPI documents directly into a collection folder — useful for bootstrapping collections or CI pipelines that sync with API specs: 
bru import openapi \
  --source https://petstore3.swagger.io/api/v3/openapi.json \
  --output ./petstore-api \
  --collection-name "Petstore API"
Bruno CLI fetches the spec, converts it, and writes the collection: 
Reading OpenAPI specification from https://petstore3.swagger.io/api/v3/openapi.json...
Converting OpenAPI specification to Bruno format...
Bruno collection created at ./petstore-api
Navigate into the new collection and run it: 
cd petstore-api
bru run
Success Criteria:
  • petstore-api directory is created with opencollection.yml and request files.
  • bru run inside the imported collection executes without import errors.
More: Import Data

​
10. Automate with CI/CD

Objective: Understand how Bruno CLI fits into automated testing pipelines. Bruno CLI is designed for CI/CD. A typical GitHub Actions workflow:
  1. Checks out your repository
  2. Installs @usebruno/cli
  3. Runs bru run with environment and reporter flags
  4. Uploads the HTML report as a build artifact
Example workflow snippet: 
- name: Install Bruno CLI
  run: npm install -g @usebruno/cli

- name: Run Bruno collection
  working-directory: collections/my-api
  run: |
    bru run \
      --env ci \
      --reporter-html ../../reports/test-report.html \
      --reporter-junit ../../reports/test-results.xml
Success Criteria:
  • You understand the basic CI/CD pattern for Bruno CLI.
  • You know where to find a complete GitHub Actions example.
More: GitHub Actions Integration · Jenkins Integration · Docker
Congratulations on completing the Bruno CLI Quick Start! You have learned how to install the CLI, run collections, use environments, generate reports, run data-driven tests, import OpenAPI specs, and integrate with CI/CD. Next steps: