Migrating from Postman to Bruno as management became painful — from VSCode integration to Git management to secrets management

Introduction

When it comes to API testing tools, Postman is the standard, but using it for a long time can gradually build up stress.

• Project A collections and Project B collections get mixed together in Postman's UI
• Sharing collections with team members requires Postman accounts
• Even when managing exported JSON with Git, the diffs are hard to read

Recently, I tried an open-source API client called Bruno, which elegantly solved these problems, so I'll summarize the setup process.

What's Good About Bruno

API Collections Are Self-Contained by Project

In Bruno, collections are placed as .bru files within the project folder. Unlike Postman, where collections from all projects are mixed in a single app, Bruno naturally achieves a 1:1 correspondence of project = collection.

Can Be Managed and Shared with Git

.bru files are plain text, so Git diffs are easy to read and you can review them in PRs. New members can just git clone and immediately have access to the API testing environment. There's no need for Postman account invitations or export/import hassles.

No Account Required - Works Offline

Bruno doesn't have cloud synchronization. No login or subscription is required. It works completely locally even in environments with unstable networks.

Prerequisites/Environment

Setup Process

Step 1: Install Bruno Desktop App

Download and install the desktop app from the Bruno official site.

For macOS, you can also install via Homebrew:

brew install bruno

Step 2: Install the VSCode Extension

Search for Bruno in the VSCode extension marketplace and install it.

This extension enables syntax highlighting for .bru files in VSCode, and allows you to right-click on a collection folder to "Open with Bruno" to launch the desktop app.

Step 3: Create a Collection

Create a .bruno/ directory at the project root and place the collection configuration files.

mkdir .bruno

bruno.json (Collection Settings)

{
  "version": "1",
  "name": "My API Collection",
  "type": "collection",
  "ignore": ["node_modules", ".git"]
}

collection.bru (Collection Variables)

vars:pre-request {
  base_url: https://api.example.com
  api_token: your-token-here
}

Since collection.bru may contain sensitive information like API tokens, add it to .gitignore:

.bruno/collection.bru

It's helpful to prepare an empty template with a different name for team members:

# collection.example.bru
vars:pre-request {
  base_url: https://api.example.com
  api_token:
}

Step 4: Create Request Files

Create .bru files inside the .bruno/ directory with 1 request = 1 file.

GET Request Example

meta {
  name: list-users
  type: http
  seq: 1
}

get {
  url: {{base_url}}/users
  body: none
  auth: bearer
}

auth:bearer {
  token: {{api_token}}
}

POST Request Example

meta {
  name: create-user
  type: http
  seq: 2
}

post {
  url: {{base_url}}/users
  body: json
  auth: bearer
}

auth:bearer {
  token: {{api_token}}
}

body:json {
  {
    "name": "Test User",
    "email": "test@example.com"
  }
}

Key points:

• Use {{variable_name}} to reference variables from collection.bru
• Configure token authentication in the auth:bearer block
• Write JSON body in the body:json block
• Control display order in Bruno with seq

Step 5: Execute Requests

Right-click on the .bruno folder in VSCode and select "Open with Bruno" to open the collection in the Bruno desktop app. Click on each request and hit "Send" to execute it.

Tips for Managing Secrets and Variables

Exclude collection.bru from Git

As mentioned earlier, add collection.bru containing actual token values to .gitignore. Instead, commit collection.example.bru and provide setup instructions in the README:

cp .bruno/collection.example.bru .bruno/collection.bru
# Open collection.bru and fill in your token

Bonus: Automatically Generate .bru Files with Claude Code

Through this setup, I also created a Claude Code custom skill /bruno that automatically generates .bru files by reading API calls in source code.

Usage:

/bruno scripts/contentful.py

This analyzes HTTP requests in the specified Python file and generates appropriate .bru files for all of them. No more manually copying request URLs, headers, and bodies one by one.

The skill definition is in .claude/commands/bruno.md, so you can customize it for your own projects.

Honest Thoughts

Bruno is not a complete replacement for Postman. It lacks Postman's advanced test automation, mocking, and monitoring features. Postman's UI is also more polished.

However, for my use case — wanting to quickly test project-specific APIs and share them with the team — Bruno was clearly a better fit. Being able to manage collections with Git is truly convenient. Being able to review and say "please add a .bru file for this endpoint" in PRs is a subtle but pleasing point.

I don't want to go back to the days of wondering "which project does this belong to?" in Postman's left sidebar.

Summary

• Bruno solves Postman's problem of "collections being tied to the app"
• .bru files are plain text, making them easy to manage with Git
• Use the collection.bru + .gitignore + collection.example.bru pattern to safely manage secrets
• Launch Bruno from VSCode with the extension's right-click functionality
• Automate .bru file generation with Claude Code custom skills