Command Examples
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.
Starting from Bruno CLI v3.0.0, the default runtime mode is Safe Mode. If your collection requires Developer Mode features (external npm packages, filesystem access), pass the --sandbox=developer flag: bru run --sandbox=developer
Basic Collection Execution
To run an entire collection, navigate to your collection directory and use the run command:
```bash copy bru run
## Running a Folder within a Collection
You can run all the requests within a specific folder by specifying the folder name:
```bash copy
bru run <folder-name>
For example, to run all requests in the users folder:
```bash copy bru run users
## Running a Collection with a CSV File
<Info>
This feature requires [Bruno CLI <strong><sup>↗</sup></strong>](https://www.npmjs.com/package/@usebruno/cli) version 1.35.0 or higher.
</Info>
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:
```bash 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:
```bash 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:
```bash 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:
```bash copy bru run --env-file /path/to/environment.bru
You can specify either a relative or absolute path to the environment file:
```bash 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
.bru format. Make sure the file contains valid environment variables and their values.
Using JSON Environment Files
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:
```bash copy bru run --env-file /path/to/environment.json
#### JSON Environment File Format
The JSON environment file should follow Bruno's environment schema:
```json 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:
```bash copy bru run --env Local
### Using Global/Workspace-Level Environments
Bruno CLI now supports referencing global/workspace-level environments when running a collection. This feature allows you to use environment variables defined at the workspace level rather than at the collection level.
#### Using Global Environments
Use the `--global-env` flag to reference a global/workspace-level environment:
```bash copy
bru run --global-env Beta
Specifying Workspace Path
When your collection is not located at the workspace root, use the --workspace-path flag to specify the workspace path:
```bash copy bru run --global-env Beta --workspace-path path/to/workspace/from/collection/root
#### Combined Usage
You can combine global environments with collection-level environments:
```bash copy
bru run --env Local --global-env Production
Passing Environment Variables
```bash 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:
```bash 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.
Include Tags
Run only requests that have at least one matching tag.
```bash copy bru run --tags=smoke,sanity
### Exclude Tags
Skip requests that have ANY of the specified tags:
```bash copy
bru run --exclude-tags=skip,draft
Combined Filtering
You can combine include and exclude filters:
```bash 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:
```bash copy
bru run --iteration-count 2 --parallel