Running a Collection

Bruno CLI allows you to run your API collections with ease, either by directly executing requests or using external data sources.

This guide explains how to run entire collections, specific folders, and how to use data sources like CSV and JSON files to drive your API tests.

Basic Collection Execution

To run an entire collection, navigate to your collection directory and use the run command:

copy

bru run

Running a Folder within a Collection

You can run all the requests within a specific folder by specifying the folder name:

copy

bru run <folder-name>

For example, to run all requests in the users folder:

copy

bru run users

Running a Collection with a CSV File

This feature requires Bruno CLI ^↗ version 1.35.0 or higher.

If you need to run a collection using data from a CSV file, specify the path to the file with the --csv-file-path option:

copy

bru run --csv-file-path /path/to/csv/file.csv

This will execute the collection once for each row in the CSV file, with each row’s data available as variables in your requests.

Running a Collection with a JSON File

To run a collection using data from a JSON file, provide the file path using the --json-file-path option:

copy

bru run --json-file-path /path/to/json/file.json

Running a Collection Multiple Times

You can run a collection multiple times in a single command using the --iteration-count flag:

copy

bru run --iteration-count=2

This will execute the collection twice. This is useful for load testing or when you need to repeat the same set of requests multiple times.

Running a Collection with Environments

You can run a collection using environment variables from either a .bru file or a .json file. This allows you to attach environments via the CLI from anywhere in the filesystem.

Using Environment Files

To run a collection with an environment file, use the --env-file option:

copy

bru run --env-file /path/to/environment.bru

You can specify either a relative or absolute path to the environment file:

copy

# Using relative path
bru run --env-file ./environments/local.bru

# Using absolute path
bru run --env-file /Users/username/projects/api-testing/environments/prod.bru

The environment file should be in Bruno’s .bru format. Make sure the file contains valid environment variables and their values.

Using JSON Environment Files

This feature requires Bruno CLI ^↗ version 2.13.0 or higher.

Bruno CLI now supports JSON environment files, which is particularly useful for global environments created in the Bruno app. This bridges the gap between UI-only global environments and CLI-based workflows.

To use a JSON environment file:

copy

bru run --env-file /path/to/environment.json

JSON Environment File Format

The JSON environment file should follow Bruno’s environment schema:

copy

{
  "name": "My Environment",
  "variables": [
    { 
      "name": "host", 
      "value": "https://api.example.com", 
      "enabled": true 
    },
    { 
      "name": "api_key", 
      "value": "your-api-key-here", 
      "enabled": true 
    }
  ]
}

Using Environments Names

If you need to use a specific environment, you can pass it with the --env option:

copy

bru run --env Local

Passing Environment Variables

Variables marked as secrets in Bruno app are not accessible via the CLI. Pass them directly as command-line arguments.

copy

bru run --env Local --env-var JWT_TOKEN=1234

Multiple Environment Variables

You can override multiple environment variables by using additional --env-var flags:

copy

bru run --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234 

Each --env-var flag adds or overrides a single environment variable, and you can chain as many as needed.

Filtering Requests with Tags

Bruno CLI supports filtering requests by tags, allowing you to run only specific subsets of your collection based on tag criteria.

This feature requires Bruno CLI ^↗ version 2.8.0 or higher.

Include Tags

Run only requests that have at least one matching tag.

copy

bru run --tags=smoke,sanity

Exclude Tags

Skip requests that have ANY of the specified tags:

copy

bru run --exclude-tags=skip,draft

Combined Filtering

You can combine include and exclude filters:

copy

bru run --tags=smoke,sanity --exclude-tags=skip,draft

Parallel Execution and Progress Tracking

Bruno CLI supports running requests in parallel and displaying real-time progress during collection execution.

Parallel Execution

By default, Bruno CLI runs requests sequentially. You can enable parallel execution using the --parallel flag:

copy

bru run --iteration-count 2 --parallel