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. For the full reference of every flag used below, see Command Options.

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

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

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

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

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:

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:

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:

copy

bru run --env Local --global-env Production

Passing Environment Variables

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).

Use --env-var to override collection-level environment variables:

copy

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

You can override multiple collection variables by repeating the flag:

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:

copy

bru run --global-env Production --global-env-var apiKey=xyz789

Override multiple global variables, optionally with a collection environment:

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.

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

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:

copy

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

- run: bru run --env ci --experimental-cache-modules --reporter-junit results.xml

Generate API Documentation

Bruno CLI can generate the same standalone HTML API documentation as Collection → Generate Documentation in the desktop app. This lets teams keep generated docs in Git, review changes alongside the collection, and regenerate or deploy the artifact from release and CI pipelines. Run the command from the collection root:

copy

bru docs generate

Without additional options, Bruno writes:

<sanitized-collection-name>-documentation.html

to the current directory. The CLI creates parent directories when needed and overwrites an existing output file without prompting. A successful command prints the output path. See Generate API Documentation options for the complete flag reference.

Choose the output file

Use --output or -o to write the HTML file somewhere other than the current directory:

copy

bru docs generate --output docs/api.html

The short form:

copy

bru docs generate -o docs/api.html

Select environments

Use --all-envs to embed every environment in the collection:

copy

bru docs generate --all-envs

Use --envs to embed only selected collection environments. Separate names with commas and quote the value when an environment name contains a space:

copy

bru docs generate --envs Production,Development

bru docs generate --envs "Production,QA Env,Staging" -o docs/api.html

Use --exclude-envs to leave environments out. Combine it with --all-envs to start from the full set, or with --envs to start from a named list:

copy

bru docs generate --all-envs --exclude-envs Local,Development

bru docs generate --envs "Production,Staging,Local" --exclude-envs Local

--exclude-envs takes precedence. If the same environment name appears in both --envs and --exclude-envs, that environment is left out. The command exits with an error if a requested environment does not exist.

Filter requests by tags

Use --tags to include requests carrying any matching tag:

copy

bru docs generate --tags "Prod Ready,local"

Use --exclude-tags to remove requests carrying any matching tag:

copy

bru docs generate --envs Prod --exclude-tags local

You can combine both filters. --exclude-tags takes precedence, the same way --exclude-envs does. If the same tag name appears in both --tags and --exclude-tags, requests with that tag are left out:

copy

bru docs generate --tags "Prod Ready,v2,WIP" --exclude-tags "WIP,Internal"

Excluded requests do not remain in the embedded collection data, navigation, or search index of the generated documentation.

Include or omit the Git repository link

For Git backed collections, the repository URL (gitCollectionUrl) is embedded by default, so readers can clone the collection from the generated documentation through Open in Bruno. You can make the default explicit with --git-link:

copy

bru docs generate --git-link

Use --no-git-link to leave the repository URL out. Readers still get the full documentation, but without the clone link. This matters most when the repository is private and the documentation is published somewhere public, where a URL to a repo most readers cannot access is not useful:

copy

bru docs generate --tags "Prod Ready,v2" --no-git-link

CI example

This command embeds every environment except Local, drops requests tagged WIP or Internal, leaves the repository URL out, and writes the file to a build directory you can publish or commit:

copy

bru docs generate \
  --all-envs \
  --exclude-envs Local \
  --exclude-tags "WIP,Internal" \
  --no-git-link \
  --output dist/docs/api.html

The CLI and desktop app use the same HTML generation and filtering implementation. For the same collection and options, they produce the same documentation.

For details about the generated site and deployment options, see Generated HTML Documentation.

CLI

Run Collections

Configuration

CI/CD

Basic Collection Execution

Running a Folder within a Collection

Running a Collection with a CSV File

Running a Collection with a JSON File

Running a Collection Multiple Times

Running a Collection with Environments

Using Environment Files

Using JSON Environment Files

JSON Environment File Format

Using Environments Names

Using Global/Workspace-Level Environments

Using Global Environments

Specifying Workspace Path

Combined Usage

Passing Environment Variables

Passing Global Environment Variables

Filtering Requests with Tags

Include Tags

Exclude Tags

Combined Filtering

Parallel Execution and Progress Tracking

Parallel Execution

Reduce CLI memory use on large runs

`--experimental-cache-modules`

CI example

Generate API Documentation

Choose the output file

Select environments

Filter requests by tags

Include or omit the Git repository link

CI example

​Basic Collection Execution

​Running a Folder within a Collection

​Running a Collection with a CSV File

​Running a Collection with a JSON File

​Running a Collection Multiple Times

​Running a Collection with Environments

​Using Environment Files

​Using JSON Environment Files

​JSON Environment File Format

​Using Environments Names

​Using Global/Workspace-Level Environments

​Using Global Environments

​Specifying Workspace Path

​Combined Usage

​Passing Environment Variables

​Passing Global Environment Variables

​Filtering Requests with Tags

​Include Tags

​Exclude Tags

​Combined Filtering

​Parallel Execution and Progress Tracking

​Parallel Execution

​Reduce CLI memory use on large runs

​--experimental-cache-modules

​CI example

​Generate API Documentation

​Choose the output file

​Select environments

​Filter requests by tags

​Include or omit the Git repository link

​CI example

Basic Collection Execution

Running a Folder within a Collection

Running a Collection with a CSV File

Running a Collection with a JSON File

Running a Collection Multiple Times

Running a Collection with Environments

Using Environment Files

Using JSON Environment Files

JSON Environment File Format

Using Environments Names

Using Global/Workspace-Level Environments

Using Global Environments

Specifying Workspace Path

Combined Usage

Passing Environment Variables

Passing Global Environment Variables

Filtering Requests with Tags

Include Tags

Exclude Tags

Combined Filtering

Parallel Execution and Progress Tracking

Parallel Execution

Reduce CLI memory use on large runs

`--experimental-cache-modules`

CI example

Generate API Documentation

Choose the output file

Select environments

Filter requests by tags

Include or omit the Git repository link

CI example