Skip to content

Secret Managers

Bruno CLI supports pulling secrets at runtime from external secret managers so that credentials never need to be stored in your collection files or passed as plain-text arguments.

Supported providers (v4.0.0+):

  • HashiCorp Vault (Vault Server and HCP Vault)
  • AWS Secrets Manager
  • Azure Key Vault
  • Google Cloud Secret Manager

Breaking change in v4.0.0

  • Secret Manager configuration has moved out of secrets.json and into your environment files (.bru / environment.yml) under an externalSecrets block. Secret Manager is now configured from the Environment UI, not from Collection Settings.

  • Migration is automatic in the app. When you open a collection that still has a secrets.json, Bruno migrates it to the environment file in the background. No manual step is needed.

  • The CLI does not auto-migrate. If the CLI finds a secrets.json but no externalSecrets block in the environment file, it prints a warning and asks you to open the collection in the app first to complete the migration.

See the Secret Managers migration guide for full details.

Variable syntax

After migration, secrets are referenced with the new syntax:

{{name.keyname}}

The legacy syntax {{$secrets.name.keyname}} still resolves in v4 and will continue to work until the next major release. It is shown with a deprecation underline and hover tooltip in the app pointing to the new syntax. An in-app tool to automatically rewrite all {{$secrets.*}} references to the new syntax will be available in v4.2.0.

How it works

  1. Configure a secret manager on an environment in the app (Environment UI → External Secrets).
  2. Commit the updated environment file to your repository.
  3. Run the CLI with --env <EnvironmentName> and pass credentials via --secrets-env-file.
bru run collection/ --env Production --secrets-env-file ./secrets.env

The --secrets-env-file flag accepts a dotenv-style file containing the credentials for your secret provider. Secrets are fetched at runtime, injected into the variable resolution chain, and are never written to disk or printed in logs.

You can export a .env credential file directly from Bruno's UI without manually writing one. Go to Preferences > Secrets Manager, hover over any configured account, and click the Export as .env icon.

The exported file is ready to pass straight to --secrets-env-file. Keep it out of version control. Learn more about exporting as .env file.

Variable precedence

External secrets
    ↓
Secret env vars (--secrets-env-file)
    ↓
Environment variables (--env)
    ↓
Collection / Workspace / Global env

HashiCorp Vault

Supported authentication methods: Token, AppRole, Client Credentials (HCP Vault).

Vault Server — Token authentication

Configure in the app and then run:

bru run collection/ --env Prod --env-var authToken=your-vault-token

Legacy secrets.json equivalent (pre-v4, for reference):

{
  "type": "vault",
  "cli": {
    "type": "vault-server",
    "vaultServerConfig": {
      "url": "http://localhost:8200",
      "namespace": "bruno",
      "auth": {
        "method": "token",
        "token": "{{authToken}}"
      }
    }
  },
  "data": [
    {
      "environment": "Prod",
      "secrets": [{ "name": "db", "path": "secret/db", "enabled": true }]
    }
  ]
}

Vault Server — AppRole authentication

bru run collection/ --env Prod \
  --env-var roleId=your-role-id \
  --env-var secretId=your-secret-id

Legacy secrets.json equivalent:

{
  "type": "vault",
  "cli": {
    "type": "vault-server",
    "vaultServerConfig": {
      "url": "http://localhost:8200",
      "namespace": "bruno",
      "auth": {
        "method": "app_role",
        "appRole": {
          "role": "bruno",
          "roleId": "{{roleId}}",
          "secretId": "{{secretId}}"
        }
      }
    }
  },
  "data": [
    {
      "environment": "Prod",
      "secrets": [{ "name": "db", "path": "secret/db", "enabled": true }]
    }
  ]
}

HCP Vault — Client credentials authentication

bru run collection/ --env Prod \
  --env-var tokenEndpoint=your-token-endpoint \
  --env-var secretsEndpoint=your-secrets-endpoint \
  --env-var clientId=your-client-id \
  --env-var clientSecret=your-client-secret \
  --env-var projectName=your-project-name \
  --env-var projectId=your-project-id \
  --env-var organizationId=your-organization-id

AWS Secrets Manager

Available from v4.0.0. Requires the externalSecrets block in the environment file — configure it from the Environment UI in the app first.

Credential file

Create a dotenv file (e.g. secrets.env) with your AWS credentials:

BRUNO_AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
BRUNO_AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
BRUNO_AWS_SESSION_TOKEN=FwoGZXIvYXdzEBYaDH...   # optional, for temporary credentials
BRUNO_AWS_REGION=us-east-1

BRUNO_AWS_SESSION_TOKEN is only required when using temporary credentials or an assumed IAM role.

If BRUNO_AWS_* variables are not present, the CLI falls back to the standard AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION).

CLI command

bru run collection/ --env Production --secrets-env-file ./secrets.env

Referencing secrets

After configuring the aws-secrets-manager provider in the Environment UI, reference secrets in your requests with:

{{secretName.keyName}}

For example, if your AWS secret is named prod/db and contains { "password": "s3cr3t" }, reference it as {{prod/db.password}}.

Both syntaxes resolve:

Syntax Status
{{name.keyname}} Recommended (v4+)
{{$secrets.name.keyname}} Deprecated — still works in v4, removal planned for next major release

Azure Key Vault

Available from v4.0.0. Requires the externalSecrets block in the environment file — configure it from the Environment UI in the app first.

Two authentication methods are supported: Service Principal and Azure CLI.

Service Principal — credential file

Create a dotenv file with your Service Principal credentials:

BRUNO_AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BRUNO_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BRUNO_AZURE_CLIENT_SECRET=your-client-secret

Azure CLI auth

If you are already logged in with az login, set the auth method to cli in the credential file — no other Azure credentials are needed:

BRUNO_AZURE_AUTH_METHOD=cli

The CLI uses your active az login session to authenticate against Key Vault.

If BRUNO_AZURE_* variables are not present, the CLI falls back to the standard Azure environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET).

CLI command

bru run collection/ --env Production --secrets-env-file ./secrets.env

Referencing secrets

After configuring the azure-key-vault provider in the Environment UI, reference secrets in your requests with:

{{vaultName.secretName}}

Both syntaxes resolve:

Syntax Status
{{name.keyname}} Recommended (v4+)
{{$secrets.name.keyname}} Deprecated — still works in v4, removal planned for next major release

Google Cloud Secret Manager

Configure a GCP Secrets Manager account in the app (Preferences → Secrets Manager), attach it under Environment → External Secrets, then pass credentials to the CLI with --secrets-env-file.

Authentication uses a GCP service account key

Service account - credential file

Create a dotenv file with your service account credentials (or export one from Preferences → Secrets Manager → Export as .env):

BRUNO_GCP_SECRETS_MANAGER_PROJECT_ID=my-project
BRUNO_GCP_SECRETS_MANAGER_CLIENT_EMAIL=service-account@my-project.iam.gserviceaccount.com
BRUNO_GCP_SECRETS_MANAGER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

BRUNO_GCP_SECRETS_MANAGER_PROJECT_ID is the account default. Projects to fetch from are defined on the environment’s external secrets rows; override the project ID there when one service account should read multiple projects.

CLI command

bru run collection/ --env Production --secrets-env-file ./secrets.env

Referencing secrets

After configuring the gcp-secrets-manager provider in the Environment UI and fetching secrets, reference them as:

{{rowName.secretId}}
{{rowName.secretId.jsonKey}}

For example, if the environment row is named staging and GCP has a secret ID db with JSON { "password": "…" }, use {{staging.db.password}}.

Both syntaxes resolve:

Syntax Status
{{name.keyname}} Recommended (v4+)
{{$secrets.name.keyname}} Deprecated — still works in v4, removal planned for next major release

For the full desktop workflow, see Google Cloud Secret Manager.

Security notes

  • Secret values are never written to disk and never printed in logs or CLI output.
  • The --secrets-env-file path should point to a file that is in .gitignore and not committed to version control.
  • Use environment-specific credential files when running across multiple environments in CI/CD pipelines.