Managing Postman became painful so I tried migrating to Bruno — VSCode integration, Git management, and secret management

Introduction

Postman is the standard tool for API testing, but using it for a long time causes subtle frustration.

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

I recently tried an open-source API client called Bruno, and it solved all these problems cleanly, so I'll summarize the setup steps here.

What's Good About Bruno

API collections are self-contained per project

In Bruno, collections are placed as .bru files inside the project folder. Unlike Postman, where all project collections get mixed into a single app, a natural 1:1 correspondence of project = collection is achieved.

Can be managed and shared with Git

.bru files are plain text, so Git diffs are easy to read and can be reviewed in PRs. When a new member does git clone, they immediately have an API testing environment ready. There's no need for Postman account invitations or the hassle of exporting/importing.

No account required, works offline

Bruno has no cloud sync. No login or subscription is needed. It runs entirely locally even in unstable network environments.

Prerequisites & Environment

Setup Steps

Step 1: Install the Bruno Desktop App

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

On macOS, you can also install it 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 a collection folder and select "Open with Bruno" to launch the desktop app.

Step 3: Create a Collection

Create a .bruno/ directory in the project root and place the collection configuration file inside. The final directory structure will look like this:

my-project/
├── .bruno/
│   ├── bruno.json              ← Collection settings
│   ├── collection.bru          ← Variables/secrets (.gitignore)
│   ├── collection.example.bru  ← Template (managed with Git)
│   ├── list-users.bru          ← GET request
│   └── create-user.bru         ← POST request
├── src/
│   └── ...
└── .gitignore

Now let's create each file one by one.

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 such as API tokens, add it to .gitignore:

.bruno/collection.bru

It's helpful for team members to have an empty template ready under a different name:

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

Step 4: Create Request Files

Inside the .bruno/ directory, create .bru files with one file per request.

Example GET Request

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

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

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

Example POST Request

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
• Set up token authentication with the auth:bearer block
• Write the JSON body in the body:json block
• Control the display order in Bruno with seq

Step 5: Run Requests

Right-click the .bruno folder in VSCode and select "Open with Bruno" to open the collection in the Bruno desktop app. Click 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, which contains actual token values, to .gitignore. Instead, commit collection.example.bru and provide setup instructions in the README or similar:

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

Bonus: Auto-generate .bru files with Claude Code

Through this setup process, I also created a custom Claude Code skill called /bruno. It's a skill that reads API calls in source code and automatically generates the corresponding .bru files.

How to use:

/bruno scripts/contentful.py

With just this, it analyzes HTTP requests in the specified Python file and generates all the appropriate .bru files. It eliminates the need to manually copy URLs, headers, and bodies one by one.

The skill definition is available at generate-bruno-files, so you can customize it to fit your own project.

Install with gh

gh skill install oharu121/skills generate-bruno-files

Honest Impressions

Bruno is not a complete replacement for Postman. Advanced test automation, mocking, and monitoring features available in Postman are not in Bruno. Postman also has an edge in UI polish.

However, for my use case — wanting to quickly hit project-specific APIs to check things and share that with the team — Bruno was clearly the better fit. Being file-based and Git-managed is genuinely convenient. Being able to review "add the .bru file for this endpoint too" in a PR is a surprisingly welcome feature.

I never want to go back to the days of staring at Postman's left sidebar thinking "wait, which project does this belong to?"

Summary

• Bruno solves Postman's problem of "collections being tied to the app"
• .bru files are plain text, making Git management easy
• Secrets can be managed safely with the collection.bru + .gitignore + collection.example.bru pattern
• Bruno can be launched with a right-click via the VSCode extension
• .bru file generation can be automated with a Claude Code custom skill