> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebruno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bru run

> Run collections, folders, and individual requests from the command line.

`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](/bru-cli/run/options). To write results to a file, see [Reports](/bru-cli/run/reports).

## Usage

```bash theme={null}
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`.

<Warning>
  **v3.0.0 Breaking Change** 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`
</Warning>

## Basic Collection Execution

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

```bash copy theme={null}
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 theme={null}
bru run <folder-name>
```

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

```bash copy theme={null}
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 theme={null}
# 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
bru run --env-file /path/to/environment.bru
```

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

```bash copy theme={null}
# 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 theme={null}
bru run --env-file /path/to/environment.json
```

#### JSON Environment File Format

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

```json copy theme={null}
{
  "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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
bru run --env Local --env-var JWT_TOKEN=1234
```

You can override multiple collection variables by repeating the flag:

```bash copy theme={null}
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 theme={null}
bru run --global-env Production --global-env-var apiKey=xyz789
```

Override multiple global variables, optionally with a collection environment:

```bash copy theme={null}
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.

### Include Tags

Run only requests that have at least one matching tag.

```bash copy theme={null}
bru run --tags=smoke,sanity
```

### Exclude Tags

Skip requests that have ANY of the specified tags:

```bash copy theme={null}
bru run --exclude-tags=skip,draft
```

### Combined Filtering

You can combine include and exclude filters:

```bash copy theme={null}
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 theme={null}
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 theme={null}
bru run --experimental-cache-modules
```

The flag does two things:

* Shares `globalThis` across 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

```yaml theme={null}
- run: bru run --env ci --experimental-cache-modules --reporter-junit results.xml
```

## Next steps

* [Options](/bru-cli/run/options) - the full reference for every `bru run` flag
* [Reports](/bru-cli/run/reports) - write JSON, JUnit, and HTML reports from a run
* [Proxy & mTLS](/bru-cli/proxyConfiguration) - route requests through a proxy and configure client certificates
* [Secret Managers](/bru-cli/secret-managers) - fetch secrets from an external secret manager at runtime
* [bru import](/bru-cli/import/overview) - create a collection from an OpenAPI or WSDL specification
* [bru docs](/bru-cli/docs/overview) - generate standalone HTML API documentation from the collection you just ran