bru run executes the requests in a collection and reports the results of their tests and assertions. It is the command you will use most: locally to check a collection before you commit, and in CI to run the same collection against every environment.
This page walks through the common ways to run a collection: whole collections, folders and files, data-driven runs from CSV and JSON files, environments, tag filters, and parallel execution. For the full reference of every flag used below, see Options. To write results to a file, see Reports.
Usage
bru run [files or folders...] [options]
Run the command from the collection root, the folder that contains opencollection.yml or bruno.json. File and folder paths are relative to that folder. To print the options for your installed version, run bru run -h.
--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 Specific Files and Folders
You can pass any mix of request files and folders. Bruno CLI runs them in the order given:
```bash copy
# Run a single file
bru run request.bru
# Run multiple files
bru run request1.bru request2.bru
# Run multiple folders
bru run <folder-1-name> <folder-2-name>
# Mix of files and folders
bru run <folder-1-name> request1.bru <folder-2-name> request2.bru
Add -r to run a folder recursively, including every nested folder inside it.
Running a Collection with a CSV File
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
<Info>
The environment file should be in Bruno's `.bru` format. Make sure the file
contains valid environment variables and their values.
</Info>
### 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
<Info>
Variables marked as secrets in the Bruno app are not persisted to disk for the
CLI. Pass them at runtime with `--env-var` (collection) or `--global-env-var`
(global).
</Info>
Use `--env-var` to override **collection-level** environment variables:
```bash copy
bru run --env Local --env-var JWT_TOKEN=1234
You can override multiple collection variables by repeating the flag:
```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 collection environment variable. Collection-level `--env-var` behavior is unchanged.
#### Passing Global Environment Variables
Use `--global-env-var` to override variables in the **active global environment**. This is required when scripts call `bru.getGlobalEnvVar()` or when you need to inject global secret values in CI/CD.
`--global-env-var` requires `--global-env`:
```bash copy
bru run --global-env Production --global-env-var apiKey=xyz789
Override multiple global variables, optionally with a collection environment:
```bash copy bru run --env Local --global-env Production \ --global-env-var apiKey=xyz789 \ --global-env-var JWT_TOKEN=1234
During the run:
- Overrides are merged into `globalEnvironmentVariables` before requests start.
- `bru.getGlobalEnvVar('apiKey')` returns the overridden value in scripts.
- `{{apiKey}}` interpolation also resolves to the overridden value.
- Overrides are not written back to the global environment file on disk.
| Flag | Scope | Seen by |
| ------------------ | -------------------------------------------- | -------------------------------------------------------- |
| `--env-var` | Collection environment | Collection env vars and `{{variable}}` interpolation |
| `--global-env-var` | Global environment (requires `--global-env`) | `bru.getGlobalEnvVar()` and `{{variable}}` interpolation |
## 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. Filters match each request's **effective tags**: tags set on the request plus tags [inherited from parent folders](/get-started/bruno-basics/create-a-folder#folder-tags).
### 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
To define tags once for every request in a folder, see Folder tags.
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
## Reduce CLI memory use on large runs
If you are seeing unbounded RSS (Resident Set Size) growth or OOM (Out of Memory) kills, you can use the `--experimental-cache-modules` flag to attempt to reduce the memory usage. It will share evaluated script modules across requests in a `bru run`.
If you are **not** seeing unbounded RSS growth or OOM kills, leave the default as-is.
### `--experimental-cache-modules`
Pass this flag on `bru run` when it runs out of memory:
```bash copy
bru run --experimental-cache-modules
The flag does two things:
- Shares
globalThisacross script VMs so module identity stays consistent. - Caches each evaluated module instead of rebuilding the module graph from scratch on every script.
That avoids the heap climb caused by re-creating the graph for every request. The flag is experimental because the approach can change script behavior in edge cases. Use it only when you hit the high-RSS issue.
This is still experimental. The name will become --cache-modules once the default CLI run is confirmed to stay unchanged with this caching on.
CI example
- run: bru run --env ci --experimental-cache-modules --reporter-junit results.xml
Next steps
- Options - the full reference for every
bru runflag - Reports - write JSON, JUnit, and HTML reports from a run
- Proxy & mTLS - route requests through a proxy and configure client certificates
- Secret Managers - fetch secrets from an external secret manager at runtime
- bru import - create a collection from an OpenAPI or WSDL specification
- bru docs - generate standalone HTML API documentation from the collection you just ran