This is the official Bruno quickstart tutorial, current as of Bruno v4, and designed to take you from download to a tested, Git-versioned, CI-ready API collection in about 15-ish minutes.
Bruno is an open-source, Git-friendly API client (MIT-licensed, 43k+ GitHub stars). If you've used Postman or Insomnia, the core ideas will feel familiar (collections, requests, environment) with one fundamental difference: your collections live as plain-text files on your machine, not in someone else's cloud. No forced account. No sync server. No leaked data. Your API workspace works offline and versions just like code.
Here's what we'll cover:
Plus a quick tour of what's new in v4 and where to go next.
Before the first click, it helps to understand the design decision everything else flows from:
| Cloud-first clients (Postman, Insomnia) | Bruno | |
|---|---|---|
| Where collections live | Vendor's cloud, tied to an account | Plain-text files in a folder on your machine |
| Offline use | Limited or login-gated | Offline by design |
| Collaboration | Primarily via proprietary sync + seats | Git-native with branches, PRs, code review |
| Data privacy | Requests/URLs may touch vendor servers | Request/URLs stay private |
| Format | Proprietary export JSON | Open, human-readable YAML (OpenCollection) |
Collections in Bruno use the OpenCollection YAML format which are readable, diffable files that make code review of API changes as natural as reviewing any other code. (Collections created in the older .bru format still work and can be converted.)
Grab Bruno from the downloads page — macOS, Windows, and Linux are all supported. Package managers work too:
# macOS
brew install bruno
# Windows
winget install Bruno.Bruno # or: choco install bruno / scoop install bruno
# Linux
sudo snap install bruno # or: flatpak install flathub com.usebruno.Bruno / apt repoOpen the app and you're in. There's no sign-up step — that's not an oversight, it's at the core of the design.
A collection is a folder of related API requests. In Bruno, it's literally a folder with yaml files on disk.
demo-api) and choose a location — pick a path inside a project repo if you have one.Everything you create from here, e.g., requests, environments, and scripts become files inside that folder. This design choice is what makes Git workflows, code review, and CI possible later in this tutorial.
That's a real collection on disk: each request is its own .yml file, environments live in their own folder, and opencollection.yml marks the collection root. Nothing proprietary, nothing hidden.
Let's hit a real API:
Get user, set the method to GET and the URL to https://api.github.com/users/usebruno, then click Create.You'll get a JSON response with status 200, timing, and size. Explore the response pane, and you'll see pretty-printed body, headers, cookies, and a timeline of what was sent.
Try a POST while you're here: create a request pointing at https://httpbingo.org/post, switch to a POST request by clicking the method type, switch to the Body tab, choose JSON, and send {"hello": "bruno"}. The echo response shows exactly what the server received.
Need auth? The Auth tab covers Basic, Bearer, Digest, NTLM, OAuth 1.0 and 2.0, AWS SigV4, and Akamai EdgeGrid (Beta) (settable per request or for the whole collection). When you're ready to go deeper, we have a full guide to API authentication in Bruno.
Hardcoding URLs gets old immediately. Environments hold values that differ between dev, staging, and prod; variables let requests reference them.
dev.baseUrl = https://api.github.com./users/usebruno.dev environment and send — same result, portable setup.Two things worth knowing:
JSON.parse gymnastics in scripts.For the full picture of variable scopes and precedence (runtime vs environment vs collection vs global), see How to Manage Variables in Bruno.
Every request has a Tests tab. Tests are JavaScript with Chai-style assertions:
test("returns 200", function () {
expect(res.getStatus()).to.equal(200);
});
test("returns the right user", function () {
const body = res.getBody();
expect(body.login).to.equal("usebruno");
expect(body).to.have.property("public_repos");
});Send the request and the test results appear alongside the response. To run every request in one go, open the collection Runner:
Green means your API contract holds; red means it broke — the Runner gives you the pass/fail breakdown per assertion, and in a minute you'll make CI fail on exactly the same checks.
Bruno also supports pre-request and post-response scripts for chaining requests, massaging data, and setting variables dynamically. The script execution flow guide explains the order everything runs in, and Testing JSON Properties in Bruno covers assertion patterns you'll reach for daily.
This is where Bruno stops being "another API client" and becomes part of your engineering workflow. Your collection is already plain text, so:
cd demo-api
git init
git add .
git commit -m "Add demo API collection with tests"Push it to GitHub/GitLab/Bitbucket and your team gets the collection with git clone, no sync service, no export/import dance. API changes go through branches and pull requests, where a reviewer can see exactly which header, assertion, or environment changed in a readable diff.
Team patterns, repo layout, and PR workflows are covered in Structuring Git for API Collection Collaboration and version control with Bruno and GitHub. Prefer a GUI? Bruno Pro adds native Git integration (commit, push, and pull without leaving the app) — but the plain-git workflow above is fully free forever, because your collection is just files.
The Bruno CLI runs your whole collection headlessly:
npm install -g @usebruno/cli # Node 18+ (also available as docker image: usebruno/cli)
cd demo-api
bru run --env devEvery request executes, every test runs, and the process exits non-zero on failure. Reports for your pipeline are one flag away:
bru run --env dev --reporter-junit results.xml --reporter-html results.htmlYou can run collections from any shell, your CI runner, or Bruno's built-in terminal (shown above). Note the run in the screenshot fails — two release-gate checks caught a broken header contract, the summary reports 16/18 tests, and the process exits non-zero. That failing exit code is the whole point: wire it into CI and broken APIs can't ship quietly.
From there, wiring it into CI is a few lines with the official GitHub Action or Docker image — see the Bruno CLI guide, API testing in CI/CD with GitHub Actions, and the official Docker image and GitHub Action announcement. Jenkins, GitLab CI, and Azure Pipelines all work the same way: clone repo → bru run.
If you're starting today, you're starting at a good time. Bruno v4 shipped:
You now have a tested, versioned, CI-ready collection. Branch out from here:
Yes. Bruno is MIT-licensed open source (43k+ stars on GitHub). The free edition includes the full API client (REST, GraphQL, gRPC), testing, scripting, secret management, code generation, and the CLI — everything in this tutorial. Paid editions add team features: pricing page.
Completely. Bruno is offline-first by design: no account, no login, no cloud sync required. Your collections and credentials never leave your machine unless you put them somewhere (like a Git remote you control).
As plain-text YAML files (the OpenCollection format) in a folder you choose on your own disk. That's why they diff cleanly, version in Git, and survive any app reinstall. Collections in the older .bru format remain supported and convertible.
Postman stores collections in its cloud, requires an account for most workflows, and monetizes seats and sync. Bruno stores collections as local files, works fully offline, and collaborates through Git. Migrating takes minutes with the Postman migration guide — or see the full Bruno vs Postman comparison.
Yes — Bruno imports Postman, Insomnia, and OpenAPI directly in the app, and the @usebruno/converters package (Postman, Insomnia, OpenAPI, WSDL) does it programmatically for bulk migrations.
Yes — that's Step 7 above. The Bruno CLI (bru run) exits non-zero on test failures and produces JUnit/HTML/JSON reports, with an official GitHub Action and Docker image for pipeline setups.
That's the whole tutorial: install, request, variables, tests, Git, CI. The entire loop in one sitting. Stored as plain files on your machine and without a cloud login.
Download Bruno and send your first request. When your team asks why the API workspace is suddenly in the repo, send them this guide.