Quick Start

Get started with Bruno in minutes. Create your first collection and make your first API request.

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

1. Launch Bruno

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

2. Create a new collection

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

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

3. 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.

1. Create a new request

   1. Right-click on your collection name in the sidebar
   2. Select “New Request”
   3. Name it “Get Users”
   4. Click “Create”
2. Configure the request

   In the request editor:

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

   GET https://jsonplaceholder.typicode.com/users
   
3. 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.

1. Create a POST request

   1. Right-click your collection
   2. Select “New Request”
   3. Name it “Create User”
   4. Click “Create”
2. Set the method and URL

   1. Change the method to POST
   2. Enter URL: https://jsonplaceholder.typicode.com/users
3. Add request headers

   Click on the “Headers” tab and add:

   Key	Value
   Content-Type	application/json

4. Add request body

   1. Click on the “Body” tab
   2. Select “JSON” from the dropdown
   3. Enter the following JSON:

   {
     "name": "John Doe",
     "email": "[e-mail]",
     "username": "johndoe"
   }
   
5. 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": "[e-mail]",
    "username": "johndoe"
  }
}

Using Environment Variables

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

1. Create an environment

   1. Right-click on your collection
   2. Select “Environments” > “Configure”
   3. Click “Create Environment”
   4. Name it “Development”
2. Add variables

   Add the following variables:

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

3. 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.

4. 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.

1. Add simple assertions

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

   res.status: eq 200
   res.body.name: eq John Doe
   
2. 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('@');
   });
   
3. 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": "[e-mail]",
    "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.

1. Navigate to your collection

   cd /path/to/your/collection
   
2. Run all requests

   bru run
   

   This executes all requests in your collection sequentially.

3. Run specific requests

   # Run a single request
   bru run "Create User.bru"
   
   # Run requests in a folder
   bru run folder-name
   
4. Use with environments

   bru run --env Development
   
5. 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:

1. Create a folder

   1. Right-click on your collection
   2. Select “New Folder”
   3. Name it “Users”
2. Move requests

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

3. 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.

1. Initialize Git (if not already)

   cd /path/to/your/collection
   git init
   
2. Create .gitignore

   Add a .gitignore file to exclude sensitive data:

   # Ignore local environment secrets
   environments/*.local.bru
   
3. Commit your collection

   git add .
   git commit -m "Add user API requests"
   
4. 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

Run entire collection

bru run

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