Skip to main content

​
Overview

Bruno CLI enables you to automate API testing in your continuous integration and deployment workflows. Run your collections in GitHub Actions, GitLab CI, Jenkins, or any other CI/CD platform.

​
Installation

Install Bruno CLI in your CI environment: 
npm install -g @usebruno/cli

​
Basic Usage

1

Navigate to your collection

The Bruno CLI needs to be run from your collection directory.
cd path/to/your-collection
2

Run all requests

Execute all requests in your collection:
bru run
3

Check exit codes

Bruno CLI returns different exit codes for scripting:
  • 0 - Execution successful
  • 1 - Assertion, test, or request failed
  • 2 - Output directory doesn’t exist
  • 3 - Infinite loop detected
  • 4 - Not in collection root directory
  • 5 - Input file doesn’t exist
  • 6 - Environment doesn’t exist
  • 255 - Other error occurred

​
Running Specific Tests

​
Single Request

Run a specific request file: 
bru run request.bru

​
Folder of Requests

Run all requests in a subfolder: 
bru run folder

​
With Environment

Specify an environment for your tests: 
bru run folder --env Prod

​
Tests Only

Run only requests that have tests defined: 
bru run --tests-only

​
Output and Reporting

​
JSON Output

Save test results as JSON: 
bru run --output results.json

​
JUnit Report

Generate JUnit XML for CI integration: 
bru run --output junit.xml --format junit

​
Multiple Reporters

Generate multiple report formats: 
bru run \
  --reporter-json results.json \
  --reporter-junit junit.xml \
  --reporter-html report.html

​
GitHub Actions Integration

Here’s a real example from Bruno’s own CI pipeline: 
name: API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    name: Run API Tests
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20'
      
      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli
      
      - name: Run API Tests
        run: |
          cd packages/bruno-tests/collection
          bru run --env Prod --output junit.xml --format junit
      
      - name: Publish Test Report
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          check_name: API Test Results
          files: packages/bruno-tests/collection/junit.xml

​
GitLab CI Integration

.gitlab-ci.yml
stages:
  - test

api-tests:
  stage: test
  image: node:20
  
  before_script:
    - npm install -g @usebruno/cli
  
  script:
    - cd api-tests
    - bru run --env Production --output results.json
  
  artifacts:
    when: always
    reports:
      junit: api-tests/junit.xml
    paths:
      - api-tests/results.json

​
Jenkins Pipeline

Jenkinsfile
pipeline {
  agent any
  
  stages {
    stage('Install Bruno CLI') {
      steps {
        sh 'npm install -g @usebruno/cli'
      }
    }
    
    stage('Run API Tests') {
      steps {
        dir('api-tests') {
          sh 'bru run --env Production --output junit.xml --format junit'
        }
      }
    }
  }
  
  post {
    always {
      junit 'api-tests/junit.xml'
    }
  }
}

​
Advanced CLI Options

​
Environment Variables

Override individual environment variables: 
bru run --env Production --env-var API_KEY=secret123
Override multiple variables: 
bru run \
  --env Production \
  --env-var API_KEY=secret123 \
  --env-var BASE_URL=https://api.staging.example.com

​
SSL Certificates

Use custom CA certificates: 
bru run --cacert myCustomCA.pem
Use only custom CA (ignore default truststore): 
bru run --cacert myCustomCA.pem --ignore-truststore

​
Request Control

Bail on Failure

Stop execution after first failure:
bru run --bail

Add Delay

Add delay between requests (in milliseconds):
bru run --delay 1000

Skip Headers

Skip headers in reports:
bru run --reporter-skip-all-headers

Insecure Mode

Allow insecure server connections:
bru run --insecure

​
CSV Data-Driven Testing

Run collection with CSV data: 
bru run --csv-file-path data.csv

​
Client Certificates

Provide client certificate configuration: 
bru run --client-cert-config cert-config.json

​
Docker Integration

Run Bruno tests in a Docker container:
Dockerfile
FROM node:20-alpine

WORKDIR /tests

# Install Bruno CLI
RUN npm install -g @usebruno/cli

# Copy collection
COPY ./api-tests /tests

# Run tests
CMD ["bru", "run", "--env", "Production", "--output", "results.json"]
Use in CI: 
steps:
  - name: Build test image
    run: docker build -t api-tests .
  
  - name: Run tests
    run: docker run api-tests

​
Best Practices

Keep your Bruno collections alongside your code in Git. This ensures tests stay in sync with your API changes.
Create separate environment files for Development, Staging, and Production:
environments/
├── Development.bru
├── Staging.bru
└── Production.bru
Always generate test reports in CI to track failures and history:
bru run --reporter-junit junit.xml --reporter-html report.html
In CI pipelines, use --bail to fail fast and save build time:
bru run --bail --env Production
Never commit sensitive data. Use CI environment variables:
bru run --env Production --env-var API_KEY=$CI_API_KEY

​
Exit Codes Reference

Use these exit codes for scripting and CI failure detection:
CodeMeaning
0Execution successful
1Assertion, test, or request failed
2Output directory doesn’t exist
3Request chain loops endlessly
4Not in collection root directory
5Input file doesn’t exist
6Environment doesn’t exist
7Environment override not string or object
8Environment override malformed
9Invalid output format
255Other error occurred

​
Troubleshooting

Error: Not in collection root directoryMake sure you’re running bru from the directory containing bruno.json. Use cd to navigate to your collection first.
Error: Environment doesn’t existCheck that your environment file exists in the environments/ folder and the name matches exactly (case-sensitive).
Debugging CI failuresAdd the --output results.json flag to capture detailed error information for debugging failed CI runs.

Build docs developers (and LLMs) love

Get started for freeTalk to us