API testing tools have splintered into two camps: cloud-synced platforms that gate advanced features behind tiers, and lightweight clients that treat collections as code. Bruno occupies the second camp with a git-native API client that stores requests as plain text files on disk. For teams already using version control for application code, Bruno eliminates the friction of exporting, importing, and reconciling collection changes across environments.

This guide walks through installation, the .bru file format, CLI execution, and team workflow patterns. All Bruno-specific instructions follow the v3.5.0 release documented in the official repository.

---

Installation Paths

Bruno distributes three installation channels. The vendor’s documentation lists the following exact package names and commands:

Method	Command / Package	Notes
Desktop app	Direct download from vendor’s downloads page	macOS, Windows, Linux supported
Homebrew (macOS)	brew install bruno	Also installs the CLI binary
npm (CLI only)	npm i -g @usebruno/cli	Node.js-based; runs headless
Docker	docker pull usebruno/bruno	Containerized CI/CD use
Windows Package Manager	winget install bruno	Vendor documentation confirms availability

The vendor’s official documentation states that Bruno CLI is released in lockstep with the desktop application: “Going forward, we will release a new version of CLI for every new release of Bruno.” This versioning parity matters when pinning CI environments to specific CLI behavior.

Doc-vs-reality drift to flag: The vendor’s tutorial mentions brew install bruno for macOS, but the CLI-specific documentation also lists npm i -g @usebruno/cli as a separate path. The npm package installs only the CLI; Homebrew installs both the desktop app and CLI binary. Verify which binary your PATH resolves when running bru --version.

---

The .bru File Format and Collection Structure

Bruno’s core architectural decision is storing collections as a folder tree of plain text files rather than a monolithic JSON export. Each collection is a directory containing:

• .bru files: Individual request definitions with metadata, HTTP method, URL, headers, body, and assertions
• bruno.json: Collection-level configuration
• environments/ subdirectory: Named environment files with variable key-value pairs

The vendor’s Version 3 release notes document a format expansion: “Bruno now supports YAML as a format for saving collection files.” This is built on the open-source OpenCollection specification. Collections created in the older .bru format still work and can be converted.

A typical collection structure on disk:

my-api-collection/
├── bruno.json
├── environments/
│ ├── local.bru
│ └── production.bru
├── users/
│ ├── get-user.bru
│ └── create-user.bru
└── health/
└── check.bru

This filesystem-native structure means standard git diff shows exactly which request changed, which header was added, or which assertion was modified. No proprietary export format, no opaque binary blobs.

---

CLI Commands: Running Collections, Environments, and Reports

The Bruno CLI entry point is bru run. The vendor’s documentation for v4 (which the v3.5.0 CLI follows) documents these patterns:

Run an entire collection:
bru run /path/to/collection

Run with a specified environment:
bru run /path/to/collection –env production

Run a specific folder within a collection:
bru run /path/to/collection/users –env local

Run a single request:
bru run /path/to/collection/users/get-user.bru –env local

Generate an HTML report:
bru run /path/to/collection –env local –output results.html –format html

The vendor’s CLI documentation lists additional flags for data files, tag filtering, and security configuration. The bru run command accepts options for “environments, data files, request filtering, security, and reporting.”

Back up first: Before migrating existing collections from another tool or rewriting environment files, commit your current state to Git or archive the directory. Bruno provides Postman import functionality, but the conversion is one-way without a manual revert path. The vendor notes: “Collections created in the older .bru format still work and can be converted” — implying conversion is irreversible.

---

Team Workflow: Git Structure, Merge Conflicts, and CI/CD

Repository Layout

Because collections are folders, teams have two structural options documented by the vendor:

Pattern	Structure	Best For
Collection-per-repo	api-collections/ at repository root	Tight coupling with service code
Monorepo collections	collections/service-name/ paths	Centralized API governance
Hybrid workspace	Bruno workspace file references multiple collection paths	Cross-service integration testing

The vendor’s Git collaboration documentation describes a “Collection, Workspace, and Hybrid Setup” model. The workspace file (bruno.json at workspace root) can reference collections at relative or absolute paths.

Merge Conflicts

The .bru format is line-oriented text, which Git handles natively. The vendor’s V3 release notes highlight: “Built-in merge conflict resolution” in the desktop app. For CLI-only workflows, standard Git merge strategies apply.

One doc-vs-reality drift to monitor: GitHub issue #6889 documents that “when a request is open in Bruno and a Git operation is performed… the open request can disappear from the UI.” This occurs when the underlying .bru file is renamed or changed during merge. The issue remains open, suggesting teams should close active requests before pulling or rebasing.

Git Feature Availability by Edition

The vendor’s collaboration documentation specifies tier boundaries for Git UI features:

Feature	Free	Pro / Ultimate
Init, view diffs, check for updates, pull, clone	✓	✓
Commit, push, branching, merge conflict resolution	—	✓

The vendor’s official pricing page lists Pro and Ultimate tiers with per-user pricing billed annually. Core CLI functionality — running collections, generating reports, integrating with CI/CD — requires no subscription. Pricing for enterprise support arrangements with dedicated account managers and SLAs varies; check the vendor’s current pricing page for exact figures.

CI/CD Integration Patterns

The vendor’s CLI documentation confirms compatibility with “GitHub Actions, GitLab CI, Jenkins, CircleCI, and any platform that runs a shell command.” A minimal pipeline stage:

Example pattern (framework-agnostic)

• name: Run API tests
  run: |
  npm i -g @usebruno/cli
  bru run ./collections –env ci –output report.html –format html
  env:
  API_BASE_URL: ${{ secrets.API_BASE_URL }}

Environment secrets inject via shell environment variables or --env-var flags. The vendor notes CLI capabilities include “Works with GitHub Actions, GitLab CI, Jenkins, CircleCI.”

---

Who Bruno Is Wrong For

Bruno makes explicit tradeoffs. The vendor’s comparison documentation and third-party reviews identify these mismatches:

• Teams requiring cloud-native collaboration workspaces: Bruno has no hosted collection sharing outside Git. Real-time team sync without Git is not available.
• Teams needing managed mock server infrastructure: The vendor’s comparison with Postman notes that “Bruno does not provide hosted mock servers or persistent shared mock environments.” Frontend, mobile, QA, and partner teams must stand up separate mocking infrastructure or wait for backend availability.
• Teams dependent on extensive plugin ecosystems: Bruno’s scope is intentionally narrow. The vendor states it “does one thing exceptionally well — helping developers quickly validate and test API calls.”
• Organizations requiring air-gapped cloud platforms: While Bruno itself runs offline, it does not replicate Postman’s cloud workspace model for teams that need it.

Third-party benchmarks describe Bruno as faster for local, offline work specifically because it skips the cloud sync handshake that Postman and (optionally) Insomnia perform on launch. This speed comes from the absence of that sync layer.

---

Comparison Context: Postman as Category Incumbent

Postman began as a Chrome extension for firing HTTP requests and, per third-party reviews, has grown into a full API platform. The vendor’s reference list acknowledges Postman’s market position while positioning Bruno as a focused alternative.

Postman offers two paths that overlap with Bruno’s territory: git-native workspaces (available in paid tiers) and an air-gapped client option for enterprise deployments. Teams evaluating both should map their requirements against:

Factor	Bruno	Postman
Collection storage	Filesystem / Git	Cloud (default) or Git (paid)
CLI execution	Free, open source	Newman (free) or CLI (paid tiers)
Mock servers	Not provided	Hosted and local options
Plugin ecosystem	Minimal	Extensive marketplace

The vendor’s official documentation emphasizes: “No cloud accounts. No per-user licensing fees. Your entire team can use it.” This is accurate for core functionality; the Pro and Ultimate tiers unlock advanced Git UI features and support SLAs, not basic CLI execution.

Visit Postman’s official site

Note that Postman is the category incumbent for API testing content — reference alongside git-native alternatives, never as unqualified default. Teams trading Bruno’s filesystem-native workflow for Postman’s broader platform gain hosted mock servers, an extensive plugin marketplace, and cloud-native collaboration workspaces, but lose the ability to treat collections as plain text files in standard Git workflows without paid-tier configuration.

---

Version Anchor Summary

• CLI release pattern: Lockstep with desktop app, per vendor changelog
• Current documented release: v3.5.0 (v3.4.2…v3.5.0 changelog referenced)
• Format version: OpenCollection spec with .bru and YAML support (V3+)
• Git UI tier split: Documented for Bruno 3.0.0+
• Pricing figures: Check the vendor’s official pricing page for current Pro and Ultimate tier rates

---

Next Steps

1. Install via your preferred channel (brew install bruno, npm i -g @usebruno/cli, or direct download)
2. Initialize or import a collection, verifying the bru --version matches your documented environment
3. Commit the collection folder to Git before making structural changes
4. Configure bru run in your CI pipeline with --env and --output flags
5. Evaluate Pro/Ultimate tiers only if your team requires the advanced Git UI features or enterprise support SLAs