Collection Settings

Collection Settings in Bruno allow you to configure options that apply to all requests in a collection. Settings are managed through the CollectionSettings component and stored in the collection.bru file.

Accessing Collection Settings

Open Collection Actions

Click the three-dot menu next to your collection name in the sidebar.

Select 'Settings'

Choose “Settings” from the dropdown menu.

Navigate Between Tabs

Use the tabs to configure different aspects of your collection.

The CollectionSettings component provides multiple tabs, each managing specific configuration:

Overview

Collection metadata and documentation

Headers

Default HTTP headers for all requests

Vars

Collection-level variables

Auth

Collection-wide authentication

Script

Pre-request and post-response scripts

Tests

Collection-level test suite

Presets

URL and request presets

Proxy

HTTP/HTTPS proxy configuration

Client Certificates

SSL/TLS client certificates

Protobuf

Protocol Buffers for gRPC

Overview Tab

The Overview component displays collection metadata and documentation.

Collection Documentation

From the test suite (bruno-tests/collection/collection.bru):

docs {
  # bruno-testbench 🐶
  
  This is a test collection that I am using to test various functionalities around bruno
}

Use the docs section to provide an overview of your API collection, including purpose, authentication requirements, and usage guidelines.

Headers Tab

The Headers component allows you to configure HTTP headers that will be sent with all requests in the collection.

Configuration

key

string

Header name (e.g., “User-Agent”, “X-API-Version”)

value

string

Header value. Supports variable interpolation: {{variable}}

enabled

boolean

default:true

Toggle to enable/disable headers without deleting them

Example

From the test suite:

collection.bru

headers {
  check: again
  token: {{collection_pre_var_token}}
  collection-header: collection-header-value
}

Header Count Indicator

The Headers tab shows the number of active headers:

From CollectionSettings component

<div className={getTabClassname('headers')} role="tab" onClick={() => setTab('headers')}>
  Headers
  {activeHeadersCount > 0 && <sup className="ml-1 font-medium">{activeHeadersCount}</sup>}
</div>

Common collection-level headers include API version headers, custom user agents, or tracking headers that should be sent with every request.

Vars Tab

The Vars component manages collection-level variables that can be set and retrieved in scripts.

Variable Types

Pre-Request Variables
Post-Response Variables

Variables available before the request is sent.

vars:pre-request {
  collection_pre_var: collection_pre_var_value
  collection_pre_var_token: {{request_pre_var_token}}
  collection-var: collection-var-value
}

Variables set after receiving the response (typically set via scripts).

// In post-response script
bru.setVar('response_time', res.responseTime);
bru.setVar('last_user_id', res.body.id);

Variable Scope

Collection Variables

Accessible throughout the entire collection. Set with bru.setVar() and retrieved with bru.getVar().

Environment Variables

Environment-specific values. Set with bru.setEnvVar() and retrieved with bru.getEnvVar().

Request Variables

Request-specific variables that don’t persist beyond the request.

Active Vars Count

The Vars tab displays the count of enabled variables:

const activeVarsCount = requestVars.filter((v) => v.enabled).length + responseVars.filter((v) => v.enabled).length;

{activeVarsCount > 0 && <sup className="ml-1 font-medium">{activeVarsCount}</sup>}

Auth Tab

The Auth component configures authentication that applies to all requests set to “Inherit” mode.

Supported Auth Types

All authentication modes are available at the collection level:

AWS Sig v4 (awsv4)
Basic Auth (basic)
Bearer Token (bearer)
Digest Auth (digest)
NTLM Auth (ntlm)
OAuth 2.0 (oauth2)
WSSE Auth (wsse)
API Key (apikey)

Configuration Example

collection.bru

auth {
  mode: bearer
}

auth:bearer {
  token: {{bearer_auth_token}}
}

Inheritance Info

The Auth tab displays this helpful message:

Configures authentication for the entire collection. 
This applies to all requests using the 'Inherit' option 
in the Auth tab.

Individual requests can override collection auth by selecting a different auth mode instead of “Inherit”.

See the Authentication guide for detailed information on each auth type.

Script Tab

The Script component allows you to configure collection-level pre-request and post-response scripts.

Collection Scripts Example

From the test suite:

collection.bru

script:pre-request {
  // Collection-level pre-request script
  const shouldTestCollectionScripts = bru.getVar('should-test-collection-scripts');
  if(shouldTestCollectionScripts) {
   bru.setVar('collection-var-set-by-collection-script', 'collection-var-value-set-by-collection-script');
  }
}

Script Execution Order

When a request is sent:

Collection pre-request script runs first
Folder pre-request script runs next (if applicable)
Request pre-request script runs last
HTTP request is sent
Request post-response script runs first
Folder post-response script runs next
Collection post-response script runs last

Use Cases for Collection Scripts

Token Refresh

// Check and refresh expired tokens
const tokenExpiry = bru.getEnvVar('token_expiry');
if (!tokenExpiry || Date.now() >= tokenExpiry) {
  // Trigger token refresh
  bru.setVar('needs_refresh', true);
}

Global Headers

// Add dynamic headers to all requests
req.setHeader('X-Request-ID', crypto.randomUUID());
req.setHeader('X-Client-Version', '1.0.0');
req.setHeader('X-Timestamp', Date.now().toString());

Logging

// Log all requests
console.log('Request:', req.method, req.url);
console.log('Environment:', bru.getEnvVar('environment'));

See the Scripts guide for more information.

Tests Tab

The Test component allows you to write tests that run for every request in the collection.

Collection-Level Tests Example

collection.bru

tests {
  // Run for all requests
  test("Response time is acceptable", function() {
    expect(res.responseTime).to.be.below(2000);
  });
  
  test("Status code is successful", function() {
    expect(res.status).to.be.at.least(200);
    expect(res.status).to.be.below(300);
  });
  
  test("Content-Type is JSON", function() {
    const contentType = res.getHeader('content-type');
    if (contentType) {
      expect(contentType).to.include('application/json');
    }
  });
}

When to Use Collection Tests

Validate response time across all endpoints
Check for required headers (CORS, security headers)
Verify authentication is working collection-wide
Ensure consistent error response formats

See the Tests guide for detailed testing information.

Presets Tab

The Presets component allows you to configure default request settings.

requestUrl

string

Default base URL for all requests. Can be overridden per request.

Preset Indicator

const hasPresets = presets && presets.requestUrl !== '';

{hasPresets && <StatusDot />}

Proxy Tab

The ProxySettings component configures HTTP/HTTPS proxy settings.

Proxy Configuration

hostname

string

required

Proxy server hostname or IP address

port

number

required

Proxy server port (e.g., 8080, 3128)

protocol

enum

Proxy protocol: http or https

auth

object

Optional proxy authentication:

username: Proxy username
password: Proxy password

Proxy Status Indicator

const proxyEnabled = proxyConfig.hostname ? true : false;

{Object.keys(proxyConfig).length > 0 && proxyEnabled && <StatusDot />}

Proxy settings apply to all requests in the collection. Ensure your proxy is properly configured to avoid request failures.

Client Certificates Tab

The ClientCertSettings component manages SSL/TLS client certificates for mutual authentication.

Certificate Configuration

domain

string

required

Domain or host for which the certificate applies (e.g., “api.example.com”)

certFilePath

string

required

Path to the client certificate file (.crt, .pem)

keyFilePath

string

required

Path to the private key file (.key, .pem)

passphrase

string

Optional passphrase if the private key is encrypted

Multiple Certificates

You can configure multiple client certificates for different domains:

From CollectionSettings

const clientCertConfig = collection.draft?.brunoConfig
  ? get(collection, 'draft.brunoConfig.clientCertificates.certs', [])
  : get(collection, 'brunoConfig.clientCertificates.certs', []);

{clientCertConfig.length > 0 && <StatusDot />}

Client certificates are useful for enterprise APIs that require mutual TLS authentication.

Protobuf Tab

The Protobuf component manages Protocol Buffer definitions for gRPC requests.

Protobuf Configuration

protoFiles

array

Array of .proto file paths relative to the collection directory

Example

Directory Structure

my-grpc-collection/
├── bruno.json
├── collection.bru
├── proto/
│   ├── user.proto
│   ├── product.proto
│   └── order.proto
└── requests/
    ├── get-user.bru
    └── create-order.bru

In Collection Settings → Protobuf:

Proto Files:
- proto/user.proto
- proto/product.proto
- proto/order.proto

Protobuf Status

{protobufConfig.protoFiles && protobufConfig.protoFiles.length > 0 && <StatusDot />}

See the Request Types guide for more on gRPC requests.

Settings Storage

All collection settings are stored in the collection.bru file at the root of your collection folder:

Complete Example

headers {
  User-Agent: Bruno/1.0
  X-API-Version: 2.0
}

auth {
  mode: bearer
}

auth:bearer {
  token: {{access_token}}
}

vars:pre-request {
  api_version: v2
  client_id: {{client_id}}
}

script:pre-request {
  // Set request timestamp
  req.setHeader('X-Timestamp', Date.now().toString());
}

script:post-response {
  // Log response time
  console.log('Response time:', res.responseTime, 'ms');
}

tests {
  test("Response is successful", function() {
    expect(res.status).to.be.at.least(200);
    expect(res.status).to.be.below(300);
  });
}

docs {
  # My API Collection
  
  This collection contains all endpoints for the Example API.
  
  ## Authentication
  Uses Bearer token authentication. Set `access_token` in your environment.
  
  ## Rate Limiting
  Rate limit: 1000 requests per hour
}

Inheritance Hierarchy

Bruno follows this inheritance hierarchy:

Collection Level

Settings in collection.bru apply to all requests.

Folder Level

Folder settings override collection settings for requests in that folder.

Request Level

Request-specific settings override both folder and collection settings.

Inheritance Behavior by Setting Type

Headers
Auth
Scripts
Tests
Variables

Additive: Collection headers + Folder headers + Request headersDuplicate headers are overridden (request > folder > collection)

Best Practices

Use Collection Auth

Configure auth once at the collection level and use “Inherit” in requests to avoid duplication.

Set Common Headers

Put headers that apply to all requests (API version, user agent) at the collection level.

Leverage Collection Scripts

Use collection scripts for token refresh, request signing, or logging that applies globally.

Document Your Collection

Use the docs section to provide context, auth requirements, and usage guidelines.

Test Common Behavior

Use collection-level tests for response time, status codes, and header validations that apply everywhere.

Environment-Specific Settings

Use {{variables}} in collection settings and configure them per environment.

Next Steps

Authentication

Configure collection-level authentication

Scripts

Write collection-level scripts

Tests

Create collection-level tests

Environments

Manage environment variables

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

​Accessing Collection Settings

Overview

Headers

Vars

Auth

Script

Tests

Presets

Proxy

Client Certificates

Protobuf

​Overview Tab

​Collection Documentation

​Headers Tab

​Configuration

​Example

​Header Count Indicator

​Vars Tab

​Variable Types

​Variable Scope

​Active Vars Count

​Auth Tab

​Supported Auth Types

​Configuration Example

​Inheritance Info

​Script Tab

​Collection Scripts Example

​Script Execution Order

​Use Cases for Collection Scripts

​Tests Tab

​Collection-Level Tests Example

​When to Use Collection Tests

​Presets Tab

​Preset Indicator

​Proxy Tab

​Proxy Configuration

​Proxy Status Indicator

​Client Certificates Tab

​Certificate Configuration

​Multiple Certificates

​Protobuf Tab

​Protobuf Configuration

​Example

​Protobuf Status

​Settings Storage

​Inheritance Hierarchy

​Inheritance Behavior by Setting Type

​Best Practices

​Next Steps

Authentication

Scripts

Tests

Environments

Build docs developers (and LLMs) love

Accessing Collection Settings

Overview Tab

Collection Documentation

Headers Tab

Configuration

Example

Header Count Indicator

Vars Tab

Variable Types

Variable Scope

Active Vars Count

Auth Tab

Supported Auth Types

Configuration Example

Inheritance Info

Script Tab

Collection Scripts Example

Script Execution Order

Use Cases for Collection Scripts

Tests Tab

Collection-Level Tests Example

When to Use Collection Tests

Presets Tab

Preset Indicator

Proxy Tab

Proxy Configuration

Proxy Status Indicator

Client Certificates Tab

Certificate Configuration

Multiple Certificates

Protobuf Tab

Protobuf Configuration

Example

Protobuf Status

Settings Storage

Inheritance Hierarchy

Inheritance Behavior by Setting Type

Best Practices

Next Steps