Bruno CLI for coding agents

When a coding agent changes an API handler, Bruno CLI can run the repository’s saved API requests against a test service and report whether they pass. Bruno stores requests in plain-text files. A collection is a group of saved API requests and tests. It can live beside the code in Git. The agent runs the bru command from a shell; the CLI sends the requests to the configured API and prints the results.

That makes Bruno useful for checking an API change against existing request-level tests. Bruno keeps the collection on disk, but sends each request over the network to its configured target. Choose a test endpoint and a collection whose requests are safe to run before asking an agent to execute them.

Install and run a collection

Install the CLI with npm, the package manager for JavaScript tools. Then run a collection with bru run, specifying its directory:

npm install -g @usebruno/cli
bru --version
bru run ./bruno --env Local

The Bruno CLI documentation covers setup and run options. Here, ./bruno is the path to the collection in the repository, and Local names an environment defined for that collection. Replace both with values from the repository. An environment holds settings such as the target API URL; selecting one tells Bruno which settings to use.

The CLI reads the collection files locally, then sends the requests to the target specified by the collection and selected environment. A GET request meant to read data is a sensible first run. Before running it, confirm that the target is a test service and that the collection has no requests that create or delete data. The Bru markup documentation describes Bruno’s plain-text request format, which lets an agent inspect the requests and tests before running them.

Before asking a coding agent to run checks, make sure the repository contains the collection and a suitable environment. The agent can inspect the relevant request files and run the collection after changing a handler, then report which checks failed. For example:

Inspect the API handler change and the Bruno collection in ./bruno. Run its read-only checks against the Local environment. Report failed requests and relevant response details. Do not run requests that create, update, or delete data.

Handle credentials outside the prompt

Configure Bruno to authenticate requests to the protected API, then select the environment that points to the intended test service. Keep credential values out of the agent prompt. Provide them through a secret mechanism the shell or CI environment can access. Confirm that the collection references those values in a way your Bruno version supports.

The CLI documentation explains how to select an environment and provide values when you run the CLI. Before running the CLI, check the repository’s collection and environment settings. The command sends real network requests, and a mistaken environment can direct them to the wrong service.

Save test results as JUnit

Bruno can write results in JUnit format, an XML format that continuous-integration tools can read. The documented command uses --output for the report path and --format junit for the format:

bru run ./bruno --env Local --output results.xml --format junit

According to the Bruno CLI output-format discussion, JUnit output requires a CLI version newer than 1.3.0. Bruno does not directly create an HTML report. To view the results in a browser, use a separate tool to turn the JUnit XML into a format you can view there. In GitHub Actions, Bruno’s integration documentation describes running collections in CI and making reports available as workflow artifacts.

Know what the CLI checks

Bruno runs the requests and tests defined in a collection, but a successful run does not prove an API change is safe: the collection must test the changed behavior, and the selected environment must point to the intended service. As collections grow, the agent has to identify which saved requests relate to the change. The agent should review the collection before running it to avoid unnecessary or unsafe calls.

Bruno works well with a coding agent when the repository keeps API requests under version control and the agent needs to run them again after a code change. It does not replace tests for code paths the collection never exercises. In a local run, Bruno reads the collection and saves the report as local files, but sends every API request to its configured network target.