Bruno cli

Bruno CLI

Bruno CLI (bru) runs Bruno API collections from the terminal — executing requests, generating reports, importing API specs, and powering API-test CI/CD.

Gotchas (read first)

These are the non-obvious facts to surface before writing any Bruno command. When correcting a user's command, check these first.

• v3.0.0 changed the default sandbox from developer to safe. If the user reports that scripts, require(...), filesystem access, or external npm packages stopped working after upgrading, the fix is --sandbox=developer. Only two valid values: safe (default) or developer.
• "Secret" variables marked in the Bruno app are NOT readable by the CLI. They must be passed explicitly (--env-var TOKEN=...) or injected via CI secrets. Don't assume the collection's saved secrets will flow through.
• bru run runs from inside the collection directory. When invoked from elsewhere (or from a nested collection inside a workspace), pass --workspace-path pointing at the workspace root — typically --workspace-path ../.. from a CI working-directory of collections/<name>.
• -o/--output and -f/--format on bru run are DEPRECATED. Never suggest them. Use --reporter-json, --reporter-junit, and/or --reporter-html instead. (Note: on bru import, -o/--output and -f/--output-file are still valid and distinct.)
• Version gates to respect. Add these as comments when version-sensitive:
  • CSV data files (--csv-file-path) require CLI ≥ 1.35.0.
  • Tag filters (--tags, --exclude-tags) require CLI ≥ 2.8.0.
  • JSON environment files (--env-file foo.json) require CLI ≥ 2.13.0.
• OpenAPI folder import defaults to opencollection (YAML), not classic .bru. If the user expects .bru files, you must pass --collection-format=bru.
• Node 18+ required. Use @usebruno/cli (the scoped name) — not bruno-cli.

Install (default: npm)

npm install -g @usebruno/cli
bru --version

Alternatives if the user already uses pnpm or yarn:

pnpm install -g @usebruno/cli
yarn global add @usebruno/cli

Command Cheatsheet — bru run

Use this table as the primary lookup. Pull the matching row, then add any other flags from the full reference as needed.

Goal	Command
Run current collection	bru run
Run a folder	bru run <folder>
Run specific files/folders	bru run req1.bru folder1 req2.bru
Named environment	bru run --env Local
Override a variable (repeatable)	bru run --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd
Env file (.bru or .json)	bru run --env-file ./environments/local.bru
Global/workspace env from nested collection	bru run --global-env Beta --workspace-path ../..
Data-driven from CSV (≥1.35.0)	bru run --csv-file-path ./data.csv
Data-driven from JSON	bru run --json-file-path ./data.json
Repeat N times	bru run --iteration-count=2
Run in parallel	bru run --parallel
Filter by tag (≥2.8.0)	bru run --tags=smoke,sanity
Skip tagged requests	bru run --exclude-tags=skip,draft
Stop on first failure	bru run --bail
Delay between requests (ms)	bru run --delay 250
Only requests that have tests/assertions	bru run --tests-only
Recursive	bru run -r
Allow insecure TLS	bru run --insecure
Disable cookies	bru run --disable-cookies
Disable all proxies	bru run --noproxy
Custom CA only	bru run --cacert ./ca.pem --ignore-truststore
Client certs / mTLS	bru run --client-cert-config ./client-cert-config.json
Developer sandbox (v3+)	bru run --sandbox=developer
JSON report	bru run --reporter-json results.json
JUnit report	bru run --reporter-junit results.xml
HTML report	bru run --reporter-html results.html
All three reporters	bru run --reporter-json r.json --reporter-junit r.xml --reporter-html r.html
Redact all headers in report	--reporter-skip-all-headers
Redact specific headers	--reporter-skip-headers "Authorization" "X-Auth-Token"
Skip request/response bodies	--reporter-skip-request-body, --reporter-skip-response-body, or shorthand --reporter-skip-body

For the complete flag list grouped by category, read references/command-options.md. Load that file when the user asks about a flag that isn't in the table above, or when you need to confirm the full set of options for a stage of bru run/bru import.

Environment Files

Two formats are accepted by --env-file:

1. .bru (native) — the typical project-level environment file.

2. .json (≥ 2.13.0) — mainly for global environments created in the Bruno UI. Schema:

   {
     "name": "My Environment",
     "variables": [
       { "name": "host",    "value": "https://api.example.com", "enabled": true },
       { "name": "api_key", "value": "your-api-key-here",       "enabled": true }
     ]
   }
   

Combine freely:

bru run --env Local --global-env Production \
  --env-var JWT_TOKEN=xyz --env-var API_KEY=abcd

Importing API Specs — bru import

Default to bru import openapi for OpenAPI (YAML or JSON); bru import wsdl for SOAP.

Default OpenAPI command (OpenCollection YAML layout — the CLI's default since the current docs):

bru import openapi \
  --source ./openapi.yaml \
  --output ./collections/petstore \
  --collection-name "Petstore API"

Variations:

• Classic .bru layout on disk → add --collection-format=bru.
• Single JSON export file (no folder) → replace --output with --output-file ./petstore.json.
• Private HTTPS source with a self-signed cert → add --insecure.
• Group OpenAPI requests by URL path instead of tags → add --group-by path.
• WSDL → bru import wsdl --source ./service.wsdl --output ./collections/soap --collection-name "SOAP Service".

Always confirm the desired on-disk layout with the user when migrating older projects — classic .bru users upgrading to a newer CLI often get surprised by the YAML default.

Reporters

Three built-in reporters: JSON, JUnit, HTML. They compose — run all three at once to get machine-readable + human-readable output. Header/body redaction flags apply uniformly to every active reporter. App-defined secrets are masked automatically.

Proxy, TLS, mTLS

• --noproxy → disables both collection-defined and system proxies for this run.
• --insecure → skip TLS verification (use only for dev/debug).
• --cacert <file> → add a CA bundle. Combine with --ignore-truststore to use only that CA.
• --client-cert-config <file> → per-domain client certs. See references/command-options.md for the JSON schema and a PEM/PFX example.

CI/CD Integration

For complete, copy-paste workflow files (GitHub Actions YAML and Jenkinsfile), read references/ci-examples.md. Load it whenever the user asks for a CI workflow, pipeline script, or when you need to write one. It includes example workspace layouts, explanatory tables, and tips for each platform.

Default shape when the user just says "run Bruno in CI":

1. Install Node 18+.
2. npm install -g @usebruno/cli.
3. cd into the collection directory; if it's nested inside a workspace, pass --workspace-path ../.. (adjust depth).
4. bru run --global-env ci --reporter-html results.html --reporter-junit results.xml.
5. Upload/archive the report artifacts even on failure (GitHub: if: ${{ !cancelled() }}; Jenkins: archiveArtifacts in a success stage with post { always { ... } } logging).

Authoring Checklist (apply before returning a command)

Run through this mentally before sending Bruno CLI output to the user:

• Is the CLI version relevant (CSV / tags / JSON env / sandbox)? If so, add a comment noting the minimum version.
• If running from a nested collection in a workspace, is --workspace-path set?
• Avoided the deprecated -o/--output and -f/--format on bru run?
• Does the command need --sandbox=developer? (Any user-written require(...), filesystem access, or npm dep in scripts/tests → yes.)
• Are secrets being passed via --env-var / CI secrets, not assumed to flow from the Bruno app?
• For bru import openapi, did you confirm the user wants opencollection (default) vs bru layout?
• In CI: reports archived even on failure?

Reference Files (when to load)

• references/command-options.md — load when the cheatsheet table above doesn't cover the user's flag, when generating bru import commands, or when the user asks to list all options. Full reference grouped by Basic / Setup / Request / SSL & Security / Output & Reporting / Import, plus a ready-to-use client-cert-config.json example.
• references/ci-examples.md — load before writing a GitHub Actions workflow, a Jenkinsfile, or when the user asks about integrating Bruno into any CI system. Contains complete, copy-paste templates and layout diagrams.

Official docs (link users here for more depth): https://docs.usebruno.com/bru-cli/overview.