bru run

The bru run command executes API requests from your Bruno collection, allowing you to test APIs in different environments, automate testing, and integrate with CI/CD workflows.

Synopsis

bru run [paths...] [options]

Arguments

paths

string[]

One or more paths to request files (.bru) or folders to execute. If not specified, runs all requests in the current collection recursively.Examples:

request.bru - Run a single request
folder - Run all requests in a folder
request.bru folder - Run a request and all requests in a folder

Options

Execution Control

-r

boolean

default:"false"

Indicates a recursive run. When enabled, runs all requests in subdirectories.

--bail

boolean

Stop execution after a failure of a request, test, or assertion.

--tests-only

boolean

Only run requests that have a test or active assertion. Filters out requests without tests, pre-request tests, post-response tests, or active assertions.

--delay

number

Delay between each request in milliseconds. Useful for rate limiting or throttling requests.

Environment

--env

string

Specify the environment to run with. This should match an environment name in your collection’s environments folder.Example: --env local

--env-file

string

Path to environment file (.bru, .json, or .yml) - absolute or relative. This allows loading environment variables from a custom file.Example: --env-file env.bru

--global-env

string

Global environment name (requires collection to be in a workspace). Global environments are shared across multiple collections in a workspace.Example: --global-env production

--workspace-path

string

Path to workspace directory. Auto-detected if not provided when using --global-env.

--env-var

string

Overwrite a single environment variable. Can be used multiple times to override multiple variables.Format: name=valueExample: --env-var secret=xxx --env-var apiKey=abc123

Output & Reporting

-o, --output

string

Path to write file results to. Works in combination with --format.Example: --output results.json

-f, --format

string

default:"json"

Format of the file results. Available formats:

json - JSON format (default)
junit - JUnit XML format
html - HTML report

Example: --format junit

--reporter-json

string

Path to write JSON file results to. Allows outputting multiple report formats simultaneously.Example: --reporter-json results.json

--reporter-junit

string

Path to write JUnit XML file results to.Example: --reporter-junit results.xml

--reporter-html

string

Path to write HTML file results to.Example: --reporter-html results.html

Reporter Filtering

--reporter-skip-all-headers

boolean

default:"false"

Omit all headers from the reporter output. Useful for reducing file size or removing sensitive header information.

--reporter-skip-headers

array

default:"[]"

Skip specific headers from the reporter output. Provide header names to exclude.Example: --reporter-skip-headers "Authorization" "Cookie"

--reporter-skip-request-body

boolean

default:"false"

Omit request body from the reporter output.

--reporter-skip-response-body

boolean

default:"false"

Omit response body from the reporter output.

--reporter-skip-body

boolean

default:"false"

Omit both request and response bodies from the reporter output. Shorthand for enabling both --reporter-skip-request-body and --reporter-skip-response-body.

Security & SSL

--insecure

boolean

Allow insecure server connections. Disables SSL certificate verification.

Use with caution. Only use this option when connecting to trusted servers.

--cacert

string

CA certificate to verify peer against. By default, this certificate is used in addition to the default truststore.Example: --cacert myCustomCA.pem

--ignore-truststore

boolean

default:"false"

The specified custom CA certificate (--cacert) will be used exclusively and the default truststore is ignored. Only evaluated in combination with --cacert.Example: --cacert myCustomCA.pem --ignore-truststore

--client-cert-config

string

Path to the client certificate config file (JSON format) used for securing the connection in the request.The JSON file should have the following structure:

{
  "enabled": true,
  "certs": [
    {
      "domain": "example.com",
      "certFilePath": "/path/to/cert.pem",
      "keyFilePath": "/path/to/key.pem"
    }
  ]
}

JavaScript Sandbox

--sandbox

string

default:"safe"

JavaScript sandbox to use for executing scripts. Available sandboxes:

safe - QuickJS runtime (default, more secure but limited)
developer - Node.js VM runtime (more features but less isolated)

Network

--disable-cookies

boolean

default:"false"

Disable automatically saving and sending cookies with requests.

--noproxy

boolean

default:"false"

Disable all proxy settings (both collection-defined and system proxies).

Tag Filtering

--tags

string

Tags to include in the run. Comma-separated list. Only requests with at least one of these tags will be executed.Example: --tags hello,world

--exclude-tags

string

Tags to exclude from the run. Comma-separated list. Requests with any of these tags will be skipped.Example: --exclude-tags skip,wip

Debugging

--verbose

boolean

Allow verbose output for debugging purposes. Provides detailed information about request execution.

Exit Codes

The bru run command returns the following exit status codes:

Success

Execution successful - all requests, tests, and assertions passed

ERROR_FAILED_COLLECTION

One or more assertions, tests, or requests failed during execution

ERROR_MISSING_OUTPUT_DIR

The specified output directory does not exist

ERROR_INFINITE_LOOP

The request chain caused an endless loop (more than 10,000 jumps detected)

ERROR_NOT_IN_COLLECTION

Command was called outside of a collection root directory

ERROR_FILE_NOT_FOUND

The specified file or path was not found

ERROR_ENV_NOT_FOUND

The specified environment was not found

ERROR_MALFORMED_ENV_OVERRIDE

Environment override not presented as string or object

ERROR_INCORRECT_ENV_OVERRIDE

Environment override format incorrect (should be name=value)

ERROR_INCORRECT_OUTPUT_FORMAT

Invalid output format requested (must be json, junit, or html)

ERROR_INVALID_FILE

The specified file has an invalid format or cannot be parsed

ERROR_WORKSPACE_NOT_FOUND

The specified workspace was not found or workspace.yml is missing

ERROR_GLOBAL_ENV_REQUIRES_WORKSPACE

Global environment requires the collection to be in a workspace

ERROR_GLOBAL_ENV_NOT_FOUND

The specified global environment was not found in the workspace

255

ERROR_GENERIC

A generic error occurred during execution

Examples

Basic Usage

Run a single request:

bru run request.bru

Run all requests in a folder:

bru run folder

Run all requests in a folder recursively:

bru run folder -r

Run multiple paths:

bru run request.bru folder

Environment Usage

Run with a specific environment:

bru run request.bru --env local

Run with a custom environment file:

bru run request.bru --env-file env.bru

Run with global environment:

bru run request.bru --global-env production

Run with global environment from specific workspace:

bru run request.bru --global-env production --workspace-path /path/to/workspace

Override environment variables:

bru run request.bru --env local --env-var secret=xxx

Output & Reporting

Save results to JSON:

bru run request.bru --output results.json

Generate JUnit XML report:

bru run request.bru --output results.xml --format junit

Generate HTML report:

bru run request.bru --output results.html --format html

Generate multiple report formats:

bru run request.bru --reporter-junit results.xml --reporter-html results.html

Reporter Filtering

Omit all headers from output:

bru run --reporter-skip-all-headers

Skip specific headers:

bru run --reporter-skip-headers "Authorization"

Omit request bodies:

bru run --reporter-skip-request-body

Omit response bodies:

bru run --reporter-skip-response-body

Omit both request and response bodies:

bru run --reporter-skip-body

Security & SSL

Use custom CA certificate (in addition to default truststore):

bru run request.bru --cacert myCustomCA.pem

Use custom CA certificate exclusively:

bru run folder --cacert myCustomCA.pem --ignore-truststore

Run with client certificates:

bru run --client-cert-config client-cert-config.json

Filtering & Control

Run only requests with tests:

bru run request.bru --tests-only

Stop on first failure:

bru run folder --bail

Run requests with specific tags:

bru run folder --tags=hello,world --exclude-tags=skip

Network Options

Add delay between requests:

bru run folder --delay 1000

Disable system proxy:

bru run --noproxy

Debugging

Run with verbose output:

bru run request.bru --verbose

Run Summary Output

After execution, bru run displays a summary with the following information:

Requests: Total, passed, failed, errors, and skipped
Pre-Request Tests: Total, passed, and failed (if any)
Post-Response Tests: Total, passed, and failed (if any)
Tests: Total, passed, and failed
Assertions: Total, passed, and failed
Total Time: Cumulative response time for all requests

Example output:

Requests:     5 passed, 0 failed, 0 error, 0 skipped, 5 total
Tests:        12 passed, 0 failed, 12 total
Assertions:   15 passed, 0 failed, 15 total

Ran all requests - 2345 ms
Wrote json results to results.json

Bru Language

Scripting API

CLI Reference

Synopsis

Arguments

Options

Execution Control

Environment

Output & Reporting

Reporter Filtering

Security & SSL

JavaScript Sandbox

Network

Tag Filtering

Debugging

Exit Codes

Examples

Basic Usage

Environment Usage

Output & Reporting

Reporter Filtering

Security & SSL

Filtering & Control

Network Options

Debugging

Run Summary Output

Build docs developers (and LLMs) love

Bru Language

Scripting API

CLI Reference

​Synopsis

​Arguments

​Options

​Execution Control

​Environment

​Output & Reporting

​Reporter Filtering

​Security & SSL

​JavaScript Sandbox

​Network

​Tag Filtering

​Debugging

​Exit Codes

​Examples

​Basic Usage

​Environment Usage

​Output & Reporting

​Reporter Filtering

​Security & SSL

​Filtering & Control

​Network Options

​Debugging

​Run Summary Output

Build docs developers (and LLMs) love

Synopsis

Arguments

Options

Execution Control

Environment

Output & Reporting

Reporter Filtering

Security & SSL

JavaScript Sandbox

Network

Tag Filtering

Debugging

Exit Codes

Examples

Basic Usage

Environment Usage

Output & Reporting

Reporter Filtering

Security & SSL

Filtering & Control

Network Options

Debugging

Run Summary Output