Quick Start

Introduction

This guide will walk you through creating your first API collection and making your first request with Bruno. You’ll learn the basics of Bruno’s interface and workflow.

Make sure you have installed Bruno before proceeding with this guide.

Creating Your First Collection

Launch Bruno

Open Bruno from your applications menu or by running bruno in your terminal.

Create a new collection

Click “Create Collection” on the welcome screen
Choose a name for your collection (e.g., “My API Tests”)
Select a location on your filesystem to store the collection
Click “Create”

Choose a location within a Git repository to automatically version control your API collections.

Verify collection creation

Your collection will appear in the left sidebar. Bruno created a folder at your chosen location with a collection.bru file.

Making Your First Request

Let’s make a simple GET request to test Bruno.

Create a new request

Right-click on your collection name in the sidebar
Select “New Request”
Name it “Get Users”
Click “Create”

Configure the request

In the request editor:

Select GET as the HTTP method (default)
Enter the URL: https://jsonplaceholder.typicode.com/users
Click the “Send” button

GET https://jsonplaceholder.typicode.com/users

View the response

You’ll see the response in the right panel:

Status: 200 OK
Response Time: ~100-500ms
Body: JSON array of user objects

The response will be formatted and syntax-highlighted automatically.

Congratulations! You’ve made your first API request with Bruno.

Understanding the Request File

Bruno saved your request as a .bru file. Let’s look at what it contains:

meta {
  name: Get Users
  type: http
  seq: 1
}

get {
  url: https://jsonplaceholder.typicode.com/users
  body: none
  auth: none
}

This plain text format makes it easy to:

Version control with Git
Review changes in pull requests
Share with team members
Edit directly in your code editor

Making a POST Request

Let’s create a more complex request with headers and a JSON body.

Create a POST request

Right-click your collection
Select “New Request”
Name it “Create User”
Click “Create”

Set the method and URL

Change the method to POST
Enter URL: https://jsonplaceholder.typicode.com/users

Add request headers

Click on the “Headers” tab and add:

Key	Value
Content-Type	application/json

Add request body

Click on the “Body” tab
Select “JSON” from the dropdown
Enter the following JSON:

{
  "name": "John Doe",
  "email": "[email protected]",
  "username": "johndoe"
}

Send the request

Click “Send” and observe the response with the created user data.

The .bru file now looks like this:

meta {
  name: Create User
  type: http
  seq: 2
}

post {
  url: https://jsonplaceholder.typicode.com/users
  body: json
  auth: none
}

headers {
  Content-Type: application/json
}

body:json {
  {
    "name": "John Doe",
    "email": "[email protected]",
    "username": "johndoe"
  }
}

Using Environment Variables

Environment variables let you reuse values across requests and switch between environments (development, staging, production).

Create an environment

Right-click on your collection
Select “Environments” > “Configure”
Click “Create Environment”
Name it “Development”

Add variables

Add the following variables:

Variable	Value
baseUrl	https://jsonplaceholder.typicode.com
apiKey	your-api-key-here

Use variables in requests

Update your request URL to use the variable:

{{baseUrl}}/users

The variable will be replaced with its value when the request is sent.

Select the environment

In the top-right corner, select “Development” from the environment dropdown.

Your environment is stored as environments/Development.bru:

vars {
  baseUrl: https://jsonplaceholder.typicode.com
  apiKey: your-api-key-here
}

Adding Tests and Assertions

Bruno supports assertions and JavaScript tests to validate API responses.

Add simple assertions

Click the “Assert” tab in your request and add:

res.status: eq 200
res.body.name: eq John Doe

Add JavaScript tests

Click the “Tests” tab and add:

test("should return valid user", function() {
  const data = res.getBody();
  expect(data).to.have.property('name');
  expect(data.name).to.equal('John Doe');
  expect(data.email).to.include('@');
});

Run and verify

Send the request and check the “Tests” tab in the response panel to see test results.

Your complete .bru file now includes tests:

meta {
  name: Create User
  type: http
  seq: 2
}

post {
  url: {{baseUrl}}/users
  body: json
  auth: none
}

headers {
  Content-Type: application/json
}

body:json {
  {
    "name": "John Doe",
    "email": "[email protected]",
    "username": "johndoe"
  }
}

assert {
  res.status: eq 200
}

tests {
  test("should return valid user", function() {
    const data = res.getBody();
    expect(data).to.have.property('name');
    expect(data.name).to.equal('John Doe');
    expect(data.email).to.include('@');
  });
}

Running Collections with CLI

Bruno CLI allows you to run your entire collection from the command line.

Navigate to your collection

cd /path/to/your/collection

Run all requests

bru run

This executes all requests in your collection sequentially.

Run specific requests

# Run a single request
bru run "Create User.bru"

# Run requests in a folder
bru run folder-name

Use with environments

bru run --env Development

Save results

bru run --output results.json

The CLI is perfect for CI/CD pipelines. It returns exit code 0 on success and 1 if any tests fail.

Organizing Requests with Folders

As your collection grows, organize requests into folders:

Create a folder

Right-click on your collection
Select “New Folder”
Name it “Users”

Move requests

Drag and drop your user-related requests into the “Users” folder.

Add folder-level scripts

Right-click the folder and select “Edit Folder” to add pre-request scripts or tests that run for all requests in that folder.

Git Integration

One of Bruno’s biggest advantages is seamless Git integration.

Initialize Git (if not already)

cd /path/to/your/collection
git init

Create .gitignore

Add a .gitignore file to exclude sensitive data:

# Ignore local environment secrets
environments/*.local.bru

Commit your collection

git add .
git commit -m "Add user API requests"

Collaborate with your team

Push to a remote repository and share with your team:

git remote add origin <your-repo-url>
git push -u origin main

Team members can now clone the repository and immediately have access to all your API collections!

Using Pre-Request Scripts

Pre-request scripts run before a request is sent, useful for generating tokens or setting variables.

// Click the "Pre Request" tab and add:

// Generate a timestamp
const timestamp = new Date().getTime();
bru.setVar("timestamp", timestamp);

// Generate a random request ID
const requestId = require('uuid').v4();
bru.setVar("requestId", requestId);

// Set a computed value
const signature = require('crypto-js').HmacSHA256(
  timestamp + requestId,
  bru.getEnvVar("secretKey")
);
bru.setVar("signature", signature.toString());

Then use these variables in your headers:

headers {
  X-Timestamp: {{timestamp}}
  X-Request-ID: {{requestId}}
  X-Signature: {{signature}}
}

Next Steps

You now know the basics of Bruno! Here’s what to explore next:

Full Documentation

Explore advanced features and detailed guides.

CLI Documentation

Learn more about automating tests with Bruno CLI.

Scripting Guide

Master pre-request scripts and test scripts.

Community

Join the Bruno community for help and discussions.

Common CLI Commands Reference

bru run

Run bru --help to see all available CLI options and commands.

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

Introduction

Creating Your First Collection

Making Your First Request

Understanding the Request File

Making a POST Request

Using Environment Variables

Adding Tests and Assertions

Running Collections with CLI

Organizing Requests with Folders

Git Integration

Using Pre-Request Scripts

Next Steps

Full Documentation

CLI Documentation

Scripting Guide

Community

Common CLI Commands Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

​Introduction

​Creating Your First Collection

​Making Your First Request

​Understanding the Request File

​Making a POST Request

​Using Environment Variables

​Adding Tests and Assertions

​Running Collections with CLI

​Organizing Requests with Folders

​Git Integration

​Using Pre-Request Scripts

​Next Steps

Full Documentation

CLI Documentation

Scripting Guide

Community

​Common CLI Commands Reference

Build docs developers (and LLMs) love

Introduction

Creating Your First Collection

Making Your First Request

Understanding the Request File

Making a POST Request

Using Environment Variables

Adding Tests and Assertions

Running Collections with CLI

Organizing Requests with Folders

Git Integration

Using Pre-Request Scripts

Next Steps

Common CLI Commands Reference