bru run

Run one or more requests or folders in your Bruno collection

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=value

Example: --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:

0 · Success

Execution successful - all requests, tests, and assertions passed

1 · ERROR_FAILED_COLLECTION

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

2 · ERROR_MISSING_OUTPUT_DIR

The specified output directory does not exist

3 · ERROR_INFINITE_LOOP

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

4 · ERROR_NOT_IN_COLLECTION

Command was called outside of a collection root directory

5 · ERROR_FILE_NOT_FOUND

The specified file or path was not found

6 · ERROR_ENV_NOT_FOUND

The specified environment was not found

7 · ERROR_MALFORMED_ENV_OVERRIDE

Environment override not presented as string or object

8 · ERROR_INCORRECT_ENV_OVERRIDE

Environment override format incorrect (should be name=value)

9 · ERROR_INCORRECT_OUTPUT_FORMAT

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

10 · ERROR_INVALID_FILE

The specified file has an invalid format or cannot be parsed

11 · ERROR_WORKSPACE_NOT_FOUND

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

12 · ERROR_GLOBAL_ENV_REQUIRES_WORKSPACE

Global environment requires the collection to be in a workspace

13 · 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