Environment Variables
Environment variables are variables that are scoped to an environment, such as local development or production. They are useful for storing variables that can be re-used across the collection that are different depending on the environment. An example would be the host url of the server you want to test.
Creating an Environment Variable
- Go to environments (top right) and press No environment.
- If there are no environments, you will be prompted to create one.
- Add your variable name, value, and an optional description for what the variable represents.
- Save your changes.
Using an Environment Variable
Just like other variables you can use the {{varName}} syntax to use an environment variable in a request. On the top-right, you can see which environment you are currently using and select a different one.
Inherit from a parent environment
Use inheritance when DEV, STG, PRD, or role-based environments share most values. Define the common variables once on a parent, then override only what differs on the child.
extends key is written only in 4.2.0 and later. Opening the same environment in an earlier version drops extends, so the parent link and inherited values disappear.
An environment can inherit from one parent of the same scope (collection environments inherit collection environments; global environments inherit global environments). Chains are allowed: STG-GW → STG → base. The child's own values always win.
Inside the environment tier, Bruno merges furthest ancestor → ancestors → direct parent → active environment. Other Bruno scopes are unchanged: global, collection, resolved environment, folder, request, runtime, prompt, process.env, secrets.
Set a parent
- Open the environment.
- In the header, open Inherits from and pick one parent.
- Save.
The picker does not let you choose more than one parent, the environment itself, or any environment that would create a cycle.
Inherited variables and secrets show as read-only rows (de-emphasized), with the source environment. Add a local variable with the same name to override; that name then leaves the inherited list and becomes editable on this environment.
If the parent file is missing, Bruno shows a non-blocking warning (for example Referenced parent environment(s) not found) and still uses the child's own variables.
How values are merged
Flattening happens before interpolation and merges raw values only. {{variable}} is then resolved once against the full scope. That means a parent value can reference a variable defined on the child.
The merged set is computed at read time. It is never written back to disk. The extends field on the environment file is the only persistence. Its value is the parent environment name.
```bru local.bru
extends: dev
vars {
url: https://echo.usebruno.com
}
vars:secret [
apikey
]
If a cycle is introduced by editing files by hand, Bruno still notifies you and resolves the chain without looping forever.
Searching environment variables
When working with a large number of environment variables, you can use the search feature to quickly find specific variables.
- Open your environment settings.
- Click the search icon in the environment details panel.
- Type your query to filter variables by name or value.
The search filters the variable list in real time. If you click on a variable row while searching, that row stays visible even if it no longer matches the query, so you can edit it without losing your place. The row unpins automatically after a short delay.
Default environment
You can set a default environment for a collection so teammates and new sessions start with the right environment selected, without picking it manually every time.
The default is stored in the collection > Presets and travels with the collection when you share, export, or import it.
Set a default environment
- Go to Collection > Presets tab.
- Select the collection environment you want as the default
- Click Save button.
Bruno marks that environment as the collection default and saves it to the collection config.
How the default is applied
| Situation | What Bruno uses |
|---|---|
| You open a collection and already have a recently selected environment saved in the UI snapshot | The saved selection (default does not override it) |
| You open or import a collection with no recent environment selected | The configured default environment |
| You run requests in the app with no environment selected | The default environment, if one is configured |
You run the collection with Bruno CLI and omit --env |
The collection's default environment, if one is configured |
bruno.json or OpenCollection YAML), not only your local UI state.
Persistence and export
The default environment is persisted in the collection configuration and included when you export the collection:
- Bruno native - stored in
bruno.json - OpenCollection YAML - stored in
opencollection.yml
On import or when opening a collection, if no recent environment is selected from the UI snapshot, Bruno falls back to this configured default.
Example config
After you set Local as the default, the collection config includes that choice. Exact field placement depends on format:
{
"version": "1",
"name": "my-api",
"defaultEnvironment": "Local"
}
opencollection: 1.0.0
info:
name: my-api
extensions:
bruno:
defaultEnvironment: Local
Using the ./environment directory
Environment variables are synced with the /environments directory inside your collection. You can also create and manage environments there.
Each environment is saved in a <environment-name>.bru file or a .yml file depending on the format in use.
BRU format (local.bru)
vars {
@description('''Base URL for the local server''')
host: http://localhost:8787
@description('''
JWT token obtained after login.
Expires in 24 hours.
''')
token: abc123
noDesc: plain-value
}
Use @description before a variable to document what it represents. Descriptions are optional, always go on the line immediately before the variable, and support multiline text using triple quotes (''').
YAML format (production.yml)
name: Production
variables:
- name: host
value: https://api.example.com
enabled: true
secret: false
description: Single-line description
- name: token
value: abc123
enabled: true
secret: false
description: |-
Multiline description.
Supports multiple lines.
Third line here.
- name: apiKey
value: ''
enabled: true
secret: true
description: Secret API key stored encrypted
- name: disabledVar
value: old-value
enabled: false
secret: false
description: This variable is disabled
- name: ''
value: ''
enabled: true
secret: false
description: Orphaned description becomes an empty-name row
The description field is optional. Use the block scalar |- for multiline descriptions to preserve line breaks. A variable with an empty name and value is treated as an orphaned description row in the UI.