> ## Documentation Index
> Fetch the complete documentation index at: https://bruno-a6972042-docs-timeline-scripts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

Bruno CLI lets you run API collections from the terminal — ideal for automation, CI/CD pipelines, and repeatable test runs. This guide walks you through installing the CLI, running collections, generating reports, and integrating with your workflow.

## Prerequisites

* A basic understanding of HTTP and REST
* **[Node.js](https://nodejs.org/en/download/)** (v18 LTS or higher recommended)
* **[Git](https://git-scm.com/install/)** (to clone the sample collection)

## Getting started

Use the **[Bruno Starter Guide](https://github.com/bruno-collections/bruno-starter-guide)** collection as the hands-on sample for this walkthrough. It contains example requests, tests, assertions, and a `local` environment — the same collection used in the [Bruno Quick Start](/introduction/quick-start).

Clone the repository:

```bash theme={null}
git clone https://github.com/bruno-collections/bruno-starter-guide.git
cd bruno-starter-guide
```

<Tip>
  Use the **[Bruno Starter Guide](https://github.com/bruno-collections/bruno-starter-guide)** as a reference while following this guide. If a step fails, open the collection in Bruno to compare your setup with the expected request configuration.
</Tip>

Work through the steps **in order**. Each step assumes the previous one.

***

## 1. Install Bruno CLI

**Objective:** Install Bruno CLI globally and verify it is available in your terminal.

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g @usebruno/cli
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm install -g @usebruno/cli
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add @usebruno/cli
    ```
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
bru --version
```

You should see the installed version number (for example, `3.4.2`).

**Success Criteria:**

* `bru` command is available in your terminal.
* `bru --version` prints a version number without errors.

More: [Installation](/bru-cli/installation)

***

## 2. Run the entire collection

**Objective:** Execute all requests in the Bruno Starter Guide collection from the command line.

Make sure you are inside the cloned collection directory (the folder containing `opencollection.yml`):

```bash theme={null}
cd path/to/bruno-starter-guide
bru run
```

Bruno CLI runs each request sequentially and prints a summary table when finished:

```
01-github-api (200 OK) - 471 ms
02-echo-bru (getaddrinfo ENOTFOUND {{baseurl}})
03-script-request (200 OK) - 1186 ms
...

📊 Execution Summary
┌───────────────┬────────────────────────┐
│ Metric        │         Result         │
├───────────────┼────────────────────────┤
│ Status        │         ✗ FAIL         │
├───────────────┼────────────────────────┤
│ Requests      │ 5 (4 Passed, 1 Failed) │
└───────────────┴────────────────────────┘
```

Some requests may fail without an environment — that is expected. You will fix this in the next step.

**Success Criteria:**

* `bru run` executes without installation errors.
* CLI output lists all five requests in the collection.
* An execution summary table is displayed at the end.

More: [Command Examples](/bru-cli/runCollection)

***

## 3. Run with an environment

**Objective:** Run the collection using the `local` environment so variable placeholders like `{{baseURL}}` resolve correctly.

The Bruno Starter Guide includes a `local` environment at `environments/local.yml` with a `baseURL` variable. Activate it with the `--env` flag:

```bash theme={null}
bru run --env local
```

With the environment applied, requests that depend on `{{baseURL}}` resolve and their tests and assertions run:

```
02-echo-bru (200 OK) - 1067 ms
Tests
   ✓ body has title
   ✓ 200 status code
Assertions
   ✓ res.status: eq 200
   ✓ res.body.title: eq Bruno
```

**Success Criteria:**

* `bru run --env local` completes with **✓ PASS** in the execution summary.
* Tests and assertions for `02-echo-bru` pass (green checkmarks).
* All five requests show a successful status.

More: [Environment Variables](/variables/environment-variables)

***

## 4. Run a single request

**Objective:** Run one specific request instead of the entire collection.

Specify the request file path after `bru run`:

```bash theme={null}
bru run 01-github-api.yml
```

Bruno CLI executes only that request:

```
01-github-api (200 OK) - 148 ms

📊 Execution Summary
┌───────────────┬──────────────┐
│ Status        │    ✓ PASS    │
│ Requests      │ 1 (1 Passed) │
└───────────────┴──────────────┘
```

You can also run multiple files or folders in one command:

```bash theme={null}
bru run 01-github-api.yml 03-script-request.yml
```

**Success Criteria:**

* Only the specified request runs.
* Execution summary shows **1 (1 Passed)**.
* Response status is **200 OK**.

***

## 5. Run requests with tests only

**Objective:** Filter the collection run to requests that have tests or active assertions.

Use the `--tests-only` flag to skip requests without tests:

```bash theme={null}
bru run --env local --tests-only
```

Only `02-echo-bru` (which has tests and assertions) is executed:

```
02-echo-bru (200 OK) - 1158 ms
Tests
   ✓ body has title
   ✓ 200 status code
Assertions
   ✓ res.status: eq 200
   ✓ res.body.title: eq Bruno

📊 Execution Summary
│ Requests      │ 1 (1 Passed) │
│ Tests         │     2/2      │
│ Assertions    │     2/2      │
```

**Success Criteria:**

* Only requests with tests or assertions are executed.
* Tests show **2/2** passed.
* Assertions show **2/2** passed.

More: [Command Options](/bru-cli/commandOptions)

***

## 6. Generate test reports

**Objective:** Export test results to HTML, JSON, and JUnit report files.

Run the collection with reporter flags to write results to disk:

```bash theme={null}
bru run --env local \
  --reporter-html results.html \
  --reporter-json results.json \
  --reporter-junit results.xml
```

When the run completes, Bruno CLI writes the report files:

```
Wrote html results to results.html
Wrote json results to results.json
Wrote junit results to results.xml
```

Open `results.html` in a browser for a visual summary. Use `results.json` for programmatic analysis or `results.xml` for CI tools that consume JUnit format.

**Success Criteria:**

* `results.html`, `results.json`, and `results.xml` are created in the current directory.
* HTML report opens in a browser and shows request results.
* JSON and XML files contain test execution data.

More: [Generating Reports](/bru-cli/builtInReporters)

***

## 7. Data-Driven Testing

**Objective:** Create a CSV or JSON data file, use row values in the `02-echo-bru` request, and run it from the CLI with an HTML report.

The Bruno Starter Guide includes `02-echo-bru`, a POST request to the [echo.usebruno.com](https://echo.usebruno.com) endpoint. You will send a different JSON body on each iteration using data from a file.

### Update the request in Bruno

1. Open the **Bruno Starter Guide** collection in Bruno.
2. Open the **`02-echo-bru`** request.
3. Select the **`local`** environment (top-right).
4. Go to the **Body** tab and update the JSON to use placeholders that match your data file columns:

```json theme={null}
{
  "title": "{{title}}",
  "msg": "{{msg}}"
}
```

5. Save the request.

<Tip>
  The data file does not replace your request body automatically. Each column (CSV) or key (JSON) becomes an iteration variable. Use `{{columnName}}` in the body so Bruno sends that row's values on each run.
</Tip>

### Create a data file

Create **one** of the following files in your collection folder (`bruno-starter-guide/`):

<Tabs>
  <Tab title="CSV">
    Create `users.csv`:

    ```csv theme={null}
    title,msg
    Bruno,Loved by developers. Built for developers.
    Opensource,Git-friendly API client.
    CLI,Run collections from the terminal.
    ```
  </Tab>

  <Tab title="JSON">
    Create `users.json`:

    ```json theme={null}
    [
      { "title": "Bruno", "msg": "Loved by developers. Built for developers." },
      { "title": "Opensource", "msg": "Git-friendly API client." },
      { "title": "CLI", "msg": "Run collections from the terminal." }
    ]
    ```
  </Tab>
</Tabs>

### Try it in the Bruno app (optional)

1. Open the collection **Runner** (runner icon in the top right corner).
2. Attach `users.csv` or `users.json` as the data file.
3. Select the **`local`** environment and run **`02-echo-bru`**.
4. Review the **Timeline** to confirm each iteration sent a different `title` and `msg`.

### Run from the CLI

From the collection directory, run `02-echo-bru` once per data row and write an HTML report:

<Tabs>
  <Tab title="CSV">
    ```bash theme={null}
    bru run --env local 02-echo-bru.yml \
      --csv-file-path users.csv \
      --reporter-html results.html
    ```
  </Tab>

  <Tab title="JSON">
    ```bash theme={null}
    bru run --env local 02-echo-bru.yml \
      --json-file-path users.json \
      --reporter-html results.html
    ```
  </Tab>
</Tabs>

Bruno CLI runs the request three times (once per row) and creates `results.html`:

```
02-echo-bru (200 OK) - 1067 ms
02-echo-bru (200 OK) - 1042 ms
02-echo-bru (200 OK) - 1038 ms

📊 Execution Summary
│ Status        │    ✓ PASS    │
│ Requests      │ 3 (3 Passed) │

Wrote html results to results.html
```

Open `results.html` in your browser for a visual summary of all three iterations. See [Generating Reports](/bru-cli/builtInReporters) for JSON, JUnit, and other reporter options.

**Success Criteria:**

* `users.csv` or `users.json` exists in the collection folder with `title` and `msg` columns.
* `02-echo-bru` body uses `{{title}}` and `{{msg}}`.
* CLI run completes with **3 (3 Passed)** in the execution summary.
* `results.html` is created and shows one result per data row.

More: [Data Driven Testing](/testing/automate-test/data-driven-testing) · [Command Examples](/bru-cli/runCollection#running-a-collection-with-a-csv-file) · [Generating Reports](/bru-cli/builtInReporters)

***

## 8. Override environment variables

**Objective:** Pass or override environment variables at runtime without editing environment files.

Use the `--env-var` flag to set variables on the command line. This is useful for secrets and CI-specific values:

```bash theme={null}
bru run --env local --env-var baseURL=https://echo.usebruno.com
```

You can chain multiple overrides:

```bash theme={null}
bru run --env local \
  --env-var baseURL=https://echo.usebruno.com \
  --env-var API_KEY=your-key-here
```

<Tip>
  Variables marked as secrets in the Bruno app are not accessible via the CLI. Pass them directly with `--env-var`.
</Tip>

**Success Criteria:**

* Collection runs successfully with overridden variables.
* No changes are required to environment files on disk.

More: [Command Examples](/bru-cli/runCollection#passing-environment-variables)

***

## 9. Import an OpenAPI specification

**Objective:** Create a Bruno collection from an OpenAPI spec using the CLI.

Bruno CLI can import OpenAPI documents directly into a collection folder — useful for bootstrapping collections or CI pipelines that sync with API specs:

```bash theme={null}
bru import openapi \
  --source https://petstore3.swagger.io/api/v3/openapi.json \
  --output ./petstore-api \
  --collection-name "Petstore API"
```

Bruno CLI fetches the spec, converts it, and writes the collection:

```
Reading OpenAPI specification from https://petstore3.swagger.io/api/v3/openapi.json...
Converting OpenAPI specification to Bruno format...
Bruno collection created at ./petstore-api
```

Navigate into the new collection and run it:

```bash theme={null}
cd petstore-api
bru run
```

**Success Criteria:**

* `petstore-api` directory is created with `opencollection.yml` and request files.
* `bru run` inside the imported collection executes without import errors.

More: [Import Data](/bru-cli/import)

***

## 10. Automate with CI/CD

**Objective:** Understand how Bruno CLI fits into automated testing pipelines.

Bruno CLI is designed for CI/CD. A typical GitHub Actions workflow:

1. Checks out your repository
2. Installs `@usebruno/cli`
3. Runs `bru run` with environment and reporter flags
4. Uploads the HTML report as a build artifact

Example workflow snippet:

```yaml theme={null}
- name: Install Bruno CLI
  run: npm install -g @usebruno/cli

- name: Run Bruno collection
  working-directory: collections/my-api
  run: |
    bru run \
      --env ci \
      --reporter-html ../../reports/test-report.html \
      --reporter-junit ../../reports/test-results.xml
```

**Success Criteria:**

* You understand the basic CI/CD pattern for Bruno CLI.
* You know where to find a complete GitHub Actions example.

More: [GitHub Actions Integration](/bru-cli/gitHubCLI) · [Jenkins Integration](/bru-cli/jenkins) · [Docker](/bru-cli/docker)

***

Congratulations on completing the Bruno CLI Quick Start! You have learned how to install the CLI, run collections, use environments, generate reports, run data-driven tests, import OpenAPI specs, and integrate with CI/CD.

**Next steps:**

* [Command Options](/bru-cli/commandOptions) — full list of CLI flags
* [Command Examples](/bru-cli/runCollection) — data-driven testing, tags, and parallel runs
* [Data Driven Testing](/testing/automate-test/data-driven-testing) — CSV/JSON iteration in the app and CLI
* [Generating Reports](/bru-cli/builtInReporters) — HTML, JSON, and JUnit reporters
* [Proxy Configuration](/bru-cli/proxyConfiguration) — run collections behind a proxy
* [Bruno Quick Start](/introduction/quick-start) — build the same collection in the Bruno app