DotEnv File

Environment variables are used to store sensitive data such as API keys, tokens, and configuration settings outside the source code. This helps keep your code secure and makes it easier to manage different settings for various environments (e.g., local, staging, production).

DotEnv File for Secret Management

In Bruno, you can store your secrets (e.g., API keys, JWT tokens) in a .env file located at the root of your collection folder. This approach is inspired by how developers typically manage secrets in their codebase.

Folder Structure Example

Below is an example folder structure for your collection:

Creating and Using the .env File

1. Create a .env file manually in the root of your collection folder. This file will store your sensitive environment variables.

2. Define your secrets in the .env file. For example:

```bash filename=".env" showLineNumbers JWT_TOKEN=your_jwt_token_value API_KEY=your_api_key_value

These secrets will be accessible in your Bruno collection via the `process.env` object.

![dot env vars](/images/screenshots/v4/secret-variables/process-env.webp)

Bruno will automatically load the secrets from this file and make them available to your collection via `process.env.<secret-name>`.

Your environment file would look like this:

<CodeGroup>

```yaml local_environment.yml
name: local_environment
variables:
  - name: BASE_URL
    value: https://echo.usebruno.com
    description: Base URL for the API
  - name: JWT_TOKEN
    value: '{{process.env.JWT_TOKEN}}'
    description: JWT token for authentication
  - name: API_KEY
    value: '{{process.env.API_KEY}}'
    description: API key for authentication

```bru local_environment.bru vars { BASE_URL: https://echo.usebruno.com JWT_TOKEN: {{process.env.JWT_TOKEN}} API_KEY: {{process.env.API_KEY}} }

</CodeGroup>


In this example, the `JWT_TOKEN` secret from the `.env` file is referenced using `process.env.JWT_TOKEN`. This will be replaced with the actual value of `JWT_TOKEN` when the collection is executed.

## Managing Secrets

1. Always add the `.env` file to your `.gitignore` file to ensure secrets are not accidentally pushed to version control.

2. If you need to share the structure of your environment variables with other developers, create a `.env.sample` file without actual secret values.

### Handling Special Characters in Values

If you manage `.env` variables through Bruno's UI, values containing special characters are automatically quoted when saved. However, If you edit the file manually, wrap values in double quotes when they contain any of the following:

| Character | Why it needs quoting |
|---|---|
| `#` | The dotenv parser treats everything after `#` as a comment |
| `\n` / `\r` | Newlines break the line-based format |
| `"` | Must be escaped as `\"` inside a quoted value |
| `\` | Must be escaped as `\\` inside a quoted value |

```bash
# Simple values — no quoting needed
SIMPLE_KEY=mysecretvalue

# Values with # must be quoted — otherwise everything after # is ignored
DB_PASSWORD="P@ss#w0rd!123"

# Newlines and backslashes must be quoted and escaped
MULTILINE="line1\nline2"
WIN_PATH="C:\\Users\\name"

Example: PASSWORD=ABC#DEF is parsed as ABC, not ABC#DEF. Always quote values that contain #.

Handling Variables with Dots

When using environment variables that contain dots in their names, use square bracket notation:

# In .env file
example.test=mysecretvalue

// In your request
// Won't work
"secret": "{{process.env.demo.example.test}}"

// Works correctly
"secret": "{{process.env['example.test']}}"

This happens because Bruno interprets dots as object path separators. Square brackets tell Bruno to treat the entire string as a single variable name.

Manage Environment Credentials

Bruno v3.1.0: You can now create, view, and delete environment variables directly from Bruno at the workspace level without manually editing .env files.

Accessing Environment Variables

1. Navigate to Workspace → Global Environment section

1. Create or edit environment variables with your credentials

1. Use these variables across all collections in your workspace using {{process.env.<variable-name>}} syntax.

This feature provides a centralized UI to create, view, and delete environment credentials directly from Bruno, eliminating the need to manually edit .env files while maintaining the same security and accessibility benefits.