Skip to main content
Hey there, fellow developers and API lovers! If you’re tired of clunky, cloud-dependent tools like Postman that make team collaboration a headache, you’re in for a treat. Bruno has always been the refreshing open-source alternative—offline-first, lightweight, and truly git-friendly. Now, with the Bruno v3 early preview live as of early 2026, it’s evolving into something even more powerful and exciting. In this guide, we’ll chat about why Bruno v3 is worth jumping into right now, explore its game-changing YAML support, and walk you through creating collections, requests, scripts, environments, and more—all in a super approachable way. Whether you’re a solo coder or on a big team, Bruno v3 makes API testing feel effortless and fun. Let’s dive in!

​
Why Choose Bruno v3? The Features That Make It Special (And Why You Should Start Using It Today)

Bruno isn’t just another API client—it’s built for real-world workflows. The v3 release brings a fresh modern interface with better colors, spacing, and responsiveness that feels polished and intuitive. Standout upgrades include:
  • Workspaces: Easily organize multiple API collections by project or team—no more scrolling through endless lists!
  • Inbuilt Terminal: Run commands right inside Bruno for quicker debugging and scripting.
  • Enhanced Git Tools: View commit history, graphs, stash changes, and handle merges smoothly.
  • YAML Support (Beta): The big one we’ll cover in depth below—ditching proprietary formats for clean, standard YAML.
What makes v3 special? It’s all about freedom and collaboration. No vendor lock-in, no forced cloud sync. Everything lives as plain files on your machine, perfect for version control with Git. Diffs are clean, merges are painless, and you can edit requests in your favorite IDE. Why switch now? The Bruno v3 is stable for everyday use, and YAML is set to become the default in February 2026 (with full support for older formats continuing). Starting early means your collections are future-proof, CI/CD-ready, and optimized for team workflows. If you value open-source tools that respect your data and workflow, Bruno v3 is a no-brainer.

​
Unlock the Magic of OpenCollection: YAML Format and Seamless CI/CD Integration

One of Bruno v3’s biggest wins is adopting the OpenCollection format—an open standard for API collections stored as simple YAML files. Why is this a game-changer?
  • Truly Open-Source: No proprietary magic. Anyone can build tools around it.
  • Git-Optimized: Human-readable files mean beautiful, meaningful diffs (goodbye, noisy changes!).
  • Editor-Friendly: Tweak requests in VS Code, Vim, or any text editor.
  • Perfect for Automation: Use Bruno’s CLI to run collections headless in pipelines like GitHub Actions or GitLab CI.
Imagine generating API tests programmatically or running automated checks on every pull request—YAML makes it effortless. It’s the foundation for a more extensible, team-friendly future.

​
How to Create YAML Collections and Requests in Bruno v3 (With Practical Examples)

Getting started is easy:
  1. Download the v3 and create a new collection.
  2. Select YAML as the format.
  3. Bruno sets up a folder with .yml files—you can build via the UI or edit directly.

​
Simple GET Request Example

Here’s a basic get-users.yml: 
uid: get-users
name: Get All Users
type: http-request

request:
  method: GET
  url: https://api.example.com/users

docs: |
  # Fetch User List

  Retrieves all users from the system.

  **Success Response**:
  - 200 OK
  - JSON array of users

​
Advanced POST Request with Headers, Body, and Params

Try this create-user.yml: 
uid: create-user
name: Create New User
type: http-request

request:
  method: POST
  url: https://api.example.com/users
  headers:
    - key: Content-Type
      value: application/json
    - key: Authorization
      value: Bearer {{auth_token}}
  params:
    - key: source
      value: bruno
      enabled: true
  body:
    mode: json
    json: |
      {
        "name": "{{user_name}}",
        "email": "{{user_email}}"
      }

docs: |
  # Add a User

  Creates a new account with the given details.

​
Adding Pre-Request and Post-Request Scripts

Scripts run JavaScript with Bruno’s handy bru API for dynamic logic and tests. 
script:
  prerequest: |
    // Set a timestamp variable
    bru.setVar('timestamp', new Date().toISOString());

    // Generate and pass a value to the next request
    const randomId = Math.floor(Math.random() * 10000);
    bru.setNextRequestVar('generated_id', randomId);

    console.log('Running pre-request setup!');

  postrequest: |
    // Basic assertions (these act as tests)
    bru.assert(response.status === 201);
    bru.assertJsonPath('$.id', response.body.json);

    // Extract data for later use
    const newUserId = response.body.json.id;
    bru.setVar('created_user_id', newUserId);

    console.log('Post-request checks complete!');
Failed assertions mark the request as failed—perfect for collection runners.

​
Mastering Environments in Bruno v3

Environments let you swap variables effortlessly between dev, staging, and production. In the v3 you can store environment files as YAML (or JSON) — YAML is recommended for readability and consistency with OpenCollection. Create files like environments/dev.env.yml in your collection folder: 
# environments/dev.env.yml
base_url: https://dev.api.example.com
auth_token: dev-secret-token
Use them in requests the same way: url: {{base_url}}/users. Switch environments in the UI or via CLI (bru run --env dev). Environment variables override collection- and folder-level variables, keeping your tests flexible and secure. Using a local .env file If you prefer to keep secrets out of collection files, you can add a local .env file at the collection root (not the same as the YAML env files). This file is loaded into the process environment at runtime and is useful for developer-local secrets or CI runners that read environment files. Example .env (collection root): 
# .env
KEY1=supersecretvalue
API_KEY=abcdef123456
How to reference process env vars
  • In YAML requests and templates, reference process env variables with Bruno’s process interpolation syntax, for example: {{$processEnv.KEY1}}.
  • In request scripts (pre/post request) you can also access them via process.env.KEY1 (the script runtime exposes the process env).
Examples: Request header using a process env value: 
headers:
  - key: Authorization
    value: Bearer {{$processEnv.API_KEY}}
Pre-request script example using process.env: 
script:
  prerequest: |
    // read process env directly in the script
    const apiKey = process.env.API_KEY || bru.getProcessEnv('API_KEY');
    bru.setVar('api_key', apiKey);
Security and .gitignore Never commit your .env files to the repo. Add a simple .gitignore entry at the collection root: 
# ignore local environment secrets
.env
If you need private environment files checked into a secure store, prefer encrypted secrets or your CI provider’s secret storage instead of committing plaintext files.

​
Understanding Folder Structure, Settings, and Configurations

YAML collections are beautifully simple directories: 
my-awesome-api/
├── bruno.json              # Collection metadata, variables, auth
├── collection.yml          # Upcoming: Collection-level config
├── environments/
│   ├── dev.env.yml
│   └── prod.env.yml
├── users/
│   ├── get-users.yml
│   ├── create-user.yml
│   └── folders.yml  # Folder-specific vars (optional)
└── posts/
    └── list-posts.yml
Sample folders.yml (folder-level variables) 
# users/folders.yml
# Variables and small settings applied to all requests in the `users` folder
base_path: /users
default_role: tester
folder_auth_token: folder-specific-token
Usage example in a request inside users/: 
request:
  method: GET
  url: {{base_url}}{{base_path}}
  headers:
    - key: Authorization
      value: Bearer {{folder_auth_token}}
Place a local .env file at the collection root (the same directory that contains bruno.json or collection.yml) so Bruno loads those values into the process environment at runtime. Do not place .env inside the environments/ folder — keep it at the collection root and add it to .gitignore to avoid committing secrets. Settings flow down: collection → folder → request. This mirrors your API structure and makes organization intuitive.

​
Variables Demystified: How to Use Them in Requests and Scripts

Variables make your requests dynamic and reusable. Scopes prioritize: request > folder > collection > environment > system env.
  • In Requests: Just wrap with {{}}, e.g., {{base_url}} or {{auth_token}}.
  • In Scripts: 
    bru.getVar('my_var');           // Read
bru.setVar('new_var', 'hello'); // Set for current run
bru.setEnvVar('api_key', 'abc'); // Environment-specific
Built-ins like {{timestamp}} or {{randomId}} add quick magic. Process env vars? Use {{$processEnv.SECRET_KEY}}.

​
Ready to Level Up Your API Game? Download Bruno v3 Now!

Bruno v3 is your ticket to a smoother, more collaborative API testing experience. With YAML beta shining bright and full release on the horizon, there’s never been a better time to try it. Download the v3 here: Bruno v3 Release (Windows, macOS, Linux available). Have questions or feedback? Join the community on GitHub or check the official docs. Thanks for reading—happy testing, and let’s make 2026 the year of better API tools! 🚀

​
Sources

  1. Bruno - Fast, Git-Friendly Open Source API Client https://www.usebruno.com
  2. Running a Collection https://docs.usebruno.com/bru-cli/runCollection
  3. Environment Variables | Bruno Docs https://docs.usebruno.com/variables/environment-variables
  4. Download Bruno - Free Open Source API Client https://www.usebruno.com/downloads
  5. Process Environment Variables - Bruno Docs https://docs.usebruno.com/variables/process-env
Last modified on March 3, 2026