Skip to content

Update Docs for Bruno CLI #391

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 27, 2025
Merged

Update Docs for Bruno CLI #391

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7f32abe
updated table
ganesh-bruno Jun 23, 2025
b591976
added await keyword in js ref doc
ganesh-bruno Jun 23, 2025
552ef78
added docs for github ci actions
ganesh-bruno Jun 24, 2025
70ef0c3
added docs for cli
ganesh-bruno Jun 25, 2025
1d03e92
updated node version
ganesh-bruno Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion src/pages/bru-cli/_meta.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,8 @@ export default {
"installation": "Installation",
"commandOptions": "Command Options",
"runCollection": "Run a Collection",
"builtInReporters": "Generate Reports"
"builtInReporters": "Generate Reports",
"proxyConfiguration": "Proxy Configuration",
"gitHubCLI": "GitHub Actions",
"jenkins": "Jenkins CI"
}
8 changes: 4 additions & 4 deletions src/pages/bru-cli/builtInReporters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You can generate any combination of these reports and even run them simultaneous
To generate a report in JSON format, use the `--reporter-json` option:

```bash copy
bru run request.bru --reporter-json results.json
bru run --reporter-json results.json
```

This will output the test results in a results.json file, which can be useful for further processing or programmatic analysis.
Expand All @@ -19,7 +19,7 @@ This will output the test results in a results.json file, which can be useful fo
To generate a report in JUnit format, use the `--reporter-junit` option:

```bash copy
bru run request.bru --reporter-junit results.xml
bru run --reporter-junit results.xml
```

The results.xml file will be in a format compatible with JUnit, making it ideal for integration with CI/CD pipelines that rely on JUnit reporting.
Expand All @@ -30,7 +30,7 @@ The results.xml file will be in a format compatible with JUnit, making it ideal
To generate a human-readable HTML report, use the `--reporter-html` option:

```bash copy
bru run request.bru --reporter-html results.html
bru run --reporter-html results.html
```

This will create an results.html file that provides a visual representation of the test outcomes, ideal for quick reviews.
Expand All @@ -40,7 +40,7 @@ This will create an results.html file that provides a visual representation of t
You can generate multiple reports at once by specifying more than one reporter option. For example, to generate JSON, JUnit, and HTML reports simultaneously, run:

```bash copy
bru run request.bru --reporter-json results.json --reporter-junit results.xml --reporter-html results.html
bru run --reporter-json results.json --reporter-junit results.xml --reporter-html results.html
```

This command will create three files: `results.json, results.xml, and results.html`, allowing you to analyze the results in different formats as needed.
Expand Down
203 changes: 69 additions & 134 deletions src/pages/bru-cli/commandOptions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,132 +4,106 @@ import { Callout } from "nextra/components";

Bruno CLI provides a variety of command options to help you customize your API testing and execution process. These options allow you to specify environments, configure reports, handle security, and much more. Below is a comprehensive list of available options:

## Bruno version
To check the current version of your Bruno CLI installation, use the following command:
## Options

```bash copy
bru --version
```
This will display the version number of the Bruno CLI you have installed. It's a helpful command for ensuring you're working with the latest version or for troubleshooting version-specific issues.

## Getting Started

Navigate to the directory where your API collection resides, and run the following command:
To use options, add them to the bru run command after you specify the collection file or folder:

```bash copy
bru run
```bash
bru run [options]
```

This will run all the requests in your collection. You can also run specific files or folders:

```bash copy
# Run a single file
bru run request.bru

# Run multiple files
bru run request1.bru request2.bru

# Run a folder
bru run folder
To view a list of available options for Bruno CLI, run the following command:

# Run multiple folders
bru run folder1 folder2

# Mix of files and folders
bru run folder1 request1.bru folder2 request2.bru
```bash
bru run -h
```

## Running Requests in a Folder
To run all the requests within a folder, use:
### Basic options

```bash copy
bru run folder
```
| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `-h`, `--help` | Output usage information |
| `--version` | Output the version number |

## Using Environments
If you need to use a specific environment, you can pass it with the `--env` option:
### Setup options

```bash copy
bru run folder --env Local
```
| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `--env [string]` | Specify environment to run with |
| `--env-var [string]` | Overwrite a single environment variable, multiple usages possible |
| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run |
| `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] |
| `--csv-file-path` | CSV file to run the collection with |
| `--json-file-path` | Path to the JSON data file |
| `--iteration-count [number]` | Number of times to run the collection |
| `-r` | Indicates a recursive run [boolean] [default: false] |

## Passing Environment Variables
### Request options

<Callout type="info">
Variables marked as secrets in Bruno app are not accessible via the CLI. Pass them directly as command-line arguments.
</Callout>
| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `--delay [number]` | Delay between each requests (in milliseconds) |
| `--tests-only` | Only run requests that have tests or active assertions |
| `--bail` | Stop execution after a failure of a request, test, or assertion |

```bash copy
bru run folder --env Local --env-var JWT_TOKEN=1234
```
### SSL & Security options

### Multiple Environment Variables
| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `--cacert [string]` | CA certificate to verify peer against |
| `--ignore-truststore` | Use custom CA certificate exclusively and ignore default truststore [boolean] [default: false] |
| `--client-cert-config` | Path to the Client certificate config file used for securing the connection |
| `--insecure` | Allow insecure server connections |
| `--disable-cookies` | Automatically save and send cookies with requests [boolean] [default: false] |
| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] |

You can override multiple environment variables by using additional `--env-var` flags:
### Output & Reporting options

```bash copy
bru run folder --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234
```
| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `-o`, `--output [string]` | **[DEPRECATED]** Path to write file results to. Use reporter options instead |
| `-f`, `--format [string]` | **[DEPRECATED]** Format of the file results. Use reporter options instead |
| `--reporter-json [string]` | Path to generate a JSON report |
| `--reporter-junit [string]` | Path to generate a JUnit report |
| `--reporter-html [string]` | Path to generate an HTML report |
| `--reporter-skip-all-headers` | Skip all headers in the report [boolean] [default: false] |
| `--reporter-skip-headers` | Skip specific headers in the report [array] [default: []] |

Each `--env-var` flag adds or overrides a single environment variable, and you can chain as many as needed.
### Import options

| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) |
| `--output-file [string]` | Output file to export as Bruno collection in JSON format |
| `--collection-name [string]` | Name for the imported collection from OpenAPI |

## Adding Delay
If you need to add a delay between requests during the execution of your API collection, you can use the `--delay` option.
## Examples

Example:
```bash copy
bru run --delay 1000
```
This will run all the requests in your collection.

## Running Multiple Iterations
You can run a collection multiple times in a single command using the `--iteration-count` flag. This is useful for load testing or when you need to execute the same collection with different data sets.

Example:
```bash copy
bru run --iteration-count=2
bru run
```

This will execute the collection twice. You can specify any positive integer to control how many times the collection runs.

## Using Client Certificates for API Requests

If your API requests require client certificates for authentication, you can specify using the `--client-cert-config` option. The configuration should be provided in a JSON file. Here's an example of how to use this option:
You can also run specific files or folders:

```bash copy
bru run folder --client-cert-config /path/to/client-cert-config.json
```
# Run a single file
bru run request.bru

The client-cert-config.json file should contain the following fields:

```json
{
"enabled": true,
"certs": [
{
"domain": "usebruno.com",
"type": "cert",
"certFilePath": "certs/server_1.crt",
"keyFilePath": "private/server_1.key",
"passphrase": "Iu$eBrun0_#Secure!"
},
{
"domain": "the-example.com",
"type": "pfx",
"pfxFilePath": "pfx/server_3.pfx",
"passphrase": "L!ghT_Y@g@mi_2024!"
}
]
}
```
# Run multiple files
bru run request1.bru request2.bru

## Disabling Proxies
# Run a folder
bru run folder

If you need to bypass all proxy settings (both collection-defined and system proxies) when running requests, you can use the `--noproxy` flag:
# Run multiple folders
bru run folder1 folder2

```bash copy
bru run --noproxy
# Mix of files and folders
bru run folder1 request1.bru folder2 request2.bru
```
The flag completely disables all proxy settings for that particular CLI run.

## Importing OpenAPI Specifications

Expand Down Expand Up @@ -159,48 +133,9 @@ Where:
- `<your-openapi.yaml>`: Path to your OpenAPI specification file (can be either YAML or JSON format)
- `<preferred-location>`: Base path and filename for your JSON output

## Options

| Option | Details |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `-h`, `--help` | Show help |
| `--version` | Show version number |
| `-r` | Indicates a recursive run (default: false) |
| `--cacert [string]` | CA certificate to verify peer against |
| `--ignore-truststore` | The specified custom CA certificate (--cacert) will be used exclusively and the default truststore is ignored [boolean] [default: false] |
| `--disable-cookies` | Automatically save and sent cookies with requests [boolean] [default: false] |
| `--env [string]` | Specify environment to run with |
| `--env-var [string]` | Overwrite a single environment variable, multiple usages possible |
| `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] |
| `-o`, `--output [string]` | **[DEPRECATED]** Path to write file results to. Use reporter options instead |
| `-f`, `--format [string]` | **[DEPRECATED]** Format of the file results. Use reporter options instead |
| `--reporter-json [string]` | Path to generate a JSON report |
| `--reporter-junit [string]` | Path to generate a JUnit report |
| `--reporter-html [string]` | Path to generate an HTML report |
| `--insecure` | Allow insecure server connections |
| `--tests-only` | Only run requests that have tests or active assertions |
| `--bail` | Stop execution after a failure of a request, test, or assertion |
| `--csv-file-path` | CSV file to run the collection with |
| `--iteration-count [number]` | Number of times to run the collection |
| `--reporter--skip-all-headers` | Skip all headers in the report |
| `--reporter-skip-headers` | Skip specific headers in the report |
| `--client-cert-config` | Client certificate configuration by passing a JSON file |
| `--delay [number]` | Add delay to each request |
| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) |
| `--output-file [string]` | Output file to export as Bruno collection in JSON format |
| `--collection-name [string]` | Name for the imported collection from OpenAPI |
| `--reporter-skip-all-headers` | Skip all headers in the report [boolean] [default: false] |
| `--reporter-skip-headers` | Skip specific headers in the report [array] [default: []] |
| `--client-cert-config` | Path to the Client certificate config file used for securing the connection |
| `--delay [number]` | Delay between each requests (in milliseconds) |
| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] |
| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) |
| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run |


## Demo
![bru cli](/screenshots/cli-demo.webp)


## Support
If you encounter any issues or have any feedback or suggestions, please raise them on our [GitHub repository <strong><sup>↗</sup></strong>](https://github.com/usebruno/bruno)
98 changes: 98 additions & 0 deletions src/pages/bru-cli/gitHubCLI.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
import { Callout } from "nextra/components";

# GitHub Actions Integration

[GitHub Actions](https://docs.github.com/en/actions) is a powerful continuous integration and continuous delivery (CI/CD) platform that enables you to automate your software development workflows directly from your GitHub repository. It provides seamless integration with GitHub's ecosystem, making it an ideal choice for teams looking to automate their API testing workflows.

Bruno CLI integrates seamlessly with GitHub Actions to automate API testing workflows.




## Prerequisites
- [Git](https://git-scm.com/downloads) Installed.
- GitHub repository with Bruno collection.


## Automate API Testing with GitHub Actions

1. Ensure your Bruno collections are properly organized in your repository:

```
your-api-project/
├── .github/
│ └── workflows/
│ └── api-tests.yml
├── collections/
│ ├── authentication/
│ │ ├── login.bru
│ │ └── logout.bru
├── environments/
│ ├── development.bru
│ ├── ci.bru
│ └── production.bru
└── bruno.json
```

2. In your repository, create the following directory structure:

```bash
mkdir -p .github/workflows
```

3. Create a new file `.github/workflows/api-tests.yml` sample script:

```yaml
name: API Tests

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

jobs:
test:
runs-on: ubuntu-latest

steps:
- name: Checkout code
uses: actions/checkout@v4

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'

- name: Install Bruno CLI
run: npm install -g @usebruno/cli

- name: Run API Tests
run: bru run --env ci --reporter-html results.html

- name: Upload Test Results
uses: actions/upload-artifact@v4
with:
name: test-results
path: results.html
```

4. **Commit and push** your workflow file:
```bash
git add .github/workflows/api-tests.yml
git commit -m "Add GitHub Actions workflow for API testing"
git push origin main
```

5. **Monitor the workflow**:
- Go to your GitHub repository
- Click on the "Actions" tab
- You should see your workflow running

6. **View results**:
- Once completed, download the test results from the artifacts section
- Open `results.html` in your browser for detailed reports

## Learn More

For more advanced GitHub Actions features and configurations, visit the [GitHub Actions documentation](https://docs.github.com/en/actions).
Loading