> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Run HTTP and GraphQL collections from the command line using the Requestly CLI binary.

The Requestly CLI lets you run collections, inspect environments, and list projects directly from your terminal or CI pipeline - no browser or desktop app required.

## Installation

Download the binary for your platform, unzip it, and run it directly. The binary is self-contained with no additional dependencies.

| Platform    | Download                                                                                           |
| ----------- | -------------------------------------------------------------------------------------------------- |
| Linux x64   | [binary-linux-x64-1.35.0.zip](https://sdk-assets.browserstack.com/binary-linux-x64-1.35.0.zip)     |
| Linux arm64 | [binary-linux-arm64-1.35.0.zip](https://sdk-assets.browserstack.com/binary-linux-arm64-1.35.0.zip) |
| macOS x64   | [binary-macos-x64-1.35.0.zip](https://sdk-assets.browserstack.com/binary-macos-x64-1.35.0.zip)     |
| macOS arm64 | [binary-macos-arm64-1.35.0.zip](https://sdk-assets.browserstack.com/binary-macos-arm64-1.35.0.zip) |
| Windows x64 | [binary-win-x64-1.35.0.zip](https://sdk-assets.browserstack.com/binary-win-x64-1.35.0.zip)         |

After downloading, unzip and make the binary executable:

```bash theme={null}
unzip binary-macos-arm64-1.35.0.zip
mv binary-macos-arm64 browserstack-binary
chmod +x browserstack-binary
```

<Note>
  Some operating systems block execution of binaries downloaded from the internet by default. Run `chmod +x browserstack-binary` if you see a permission error.
</Note>

All examples in this guide use `browserstack-binary` as the executable name. The actual filename after unzipping is platform-dependent (e.g. `binary-macos-arm64` on macOS arm64) - rename it to match.

## Invocation

```text theme={null}
browserstack-binary requestly <command> [subcommand] [target] [flags]
```

## Authentication

Cloud operations - fetching a collection by cloud ID, listing cloud projects, collections, and environments - require BrowserStack credentials set as environment variables:

| Variable                  | Description                  |
| ------------------------- | ---------------------------- |
| `BROWSERSTACK_USERNAME`   | Your BrowserStack username   |
| `BROWSERSTACK_ACCESS_KEY` | Your BrowserStack access key |

Both must be set together. Local filesystem runs, Postman JSON files, and URL-fetch targets do not require credentials.

```bash theme={null}
export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key
browserstack-binary requestly collection run <cloud-collection-id> --project <project-id>
```

To find your username and access key, open your [BrowserStack account profile](https://www.browserstack.com/accounts/profile/details).

## Commands

### `collection run`

Run a collection or request. The target type is auto-detected - no explicit type flag needed.

```text theme={null}
browserstack-binary requestly collection run <target> [flags]
```

#### Target detection

The CLI resolves the target in this order:

| Target                                                                                        | Detected as                                                                                                                      |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Starts with `http://` or `https://`                                                           | URL fetch - downloads JSON and runs it. Must be a valid Postman v2.1 or Requestly collection.                                    |
| Directory containing `__requestly.json`                                                       | Requestly local project - runs all collections under `apis/`.                                                                    |
| Directory containing `__metadata.json` with `"type": "collection"`                            | Specific Requestly collection - runs only that collection.                                                                       |
| `.json` file with Postman v2.1 schema (`info._postman_id` or `info.schema` containing `v2.1`) | Postman v2.1 collection file.                                                                                                    |
| Cloud collection ID (e.g. `abc123-def456`)                                                    | Fetches the collection from Requestly cloud. Requires `--project <id>` plus `BROWSERSTACK_USERNAME` + `BROWSERSTACK_ACCESS_KEY`. |

If the target cannot be resolved, the CLI exits with code `1` and a descriptive error message.

#### Execution flags

| Flag                               | Short | Default    | Description                                                                                                                                                                                |
| ---------------------------------- | ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--project <id>`                   |       |            | Cloud project ID. Required for cloud collection-ID targets. Not used for local/file/URL targets.                                                                                           |
| `--environment <name/path/id>`     | `-e`  |            | Environment to activate. Accepts: environment name (resolved from a Requestly project's `environments/` directory), file path to a standalone environment JSON, or a cloud environment ID. |
| `--env-var <key=value>`            |       |            | Override an environment variable. Repeatable.                                                                                                                                              |
| `--global-var <key=value>`         |       |            | Override a global variable. Repeatable.                                                                                                                                                    |
| `--iteration-data <path>`          | `-d`  |            | CSV or JSON data file for data-driven runs. The collection runs once per row (CSV) or object (JSON).                                                                                       |
| `--iteration-count <n>`            | `-n`  | `1`        | Number of times to run the collection. With `-d`, multiplies iterations: total = N x rows.                                                                                                 |
| `--delay-request <ms>`             |       | `0`        | Pause between consecutive requests (milliseconds).                                                                                                                                         |
| `--on-error <end/continue/ignore>` |       | `continue` | Behavior on assertion failure. `end`: stop on first failure. `continue`: run to completion, exit `1` if any failed. `ignore`: run to completion, failures do not affect exit code.         |
| `--bail`                           |       |            | Shortcut for `--on-error end`. When used with `-d` or `-n`, stops the entire run (all remaining iterations), not just the current one.                                                     |
| `--timeout-request <ms>`           |       | `0`        | Per-request timeout. `0` = no limit.                                                                                                                                                       |
| `--folder <name>`                  |       |            | Run only the named folder within a Postman v2.1 collection. Repeatable. Postman targets only.                                                                                              |
| `--insecure`                       | `-k`  |            | Disable TLS certificate validation.                                                                                                                                                        |
| `--verbose`                        |       |            | Log detailed request/response info (method, URL, status, headers, timing) for each request.                                                                                                |

#### Reporter flags

| Flag                              | Short | Default                       | Description                                                                                                         |
| --------------------------------- | ----- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--reporters <list>`              | `-r`  | `cli`                         | Comma-separated reporters to activate: `cli`, `json`, `junit`, `html`. All listed reporters run simultaneously.     |
| `--reporter-json-export <path>`   |       | `./rq-reports/rq-report.json` | Output path for the JSON report (Newman-compatible schema).                                                         |
| `--reporter-junit-export <path>`  |       | `./rq-reports/rq-report.xml`  | Output path for JUnit XML. Compatible with GitHub Actions, GitLab CI, Jenkins, CircleCI, and Bamboo.                |
| `--reporter-html-export <path>`   |       | `./rq-reports/rq-report.html` | Output path for a self-contained HTML report.                                                                       |
| `--reporter-omit-request-bodies`  |       |                               | Remove request bodies from all reporter output.                                                                     |
| `--reporter-omit-response-bodies` |       |                               | Remove response bodies from all reporter output.                                                                    |
| `--reporter-omit-headers`         |       |                               | Remove all headers from all reporter output.                                                                        |
| `--reporter-skip-headers <names>` |       |                               | Remove specific headers by name (comma-separated).                                                                  |
| `--reporter-omit-all`             |       |                               | Omit all request bodies, response bodies, and headers. Equivalent to combining the three `--reporter-omit-*` flags. |

<Note>
  Missing export directories are created automatically. If a directory cannot be created, the CLI exits `1` after the run completes - tests still execute.
</Note>

`--reporter-omit-*` flags affect the JSON and HTML reporters regardless of `--verbose`. In terminal output, they suppress the additional headers/bodies that `--verbose` would otherwise show.

#### Global flags

| Flag                    | Short | Description                                       |
| ----------------------- | ----- | ------------------------------------------------- |
| `--color <auto/on/off>` |       | ANSI color output. Default: `auto` (detects TTY). |
| `--help`                | `-h`  | Show help.                                        |
| `--version`             | `-v`  | Print CLI version and exit.                       |

#### Exit codes

| Code | Meaning                                                                                                                                                                                                |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | All assertions passed (including an empty collection with zero requests). HTTP 4xx/5xx responses are not failures - only [`rq.test()`](/api-client/rq-api-reference/rq-test) assertion failures count. |
| `1`  | Any of: assertion failures; target not found or unreadable; invalid or unrecognized JSON; URL/cloud fetch failed; missing credentials for a cloud target; reporter export write failed.                |
| `2`  | Fatal/uncaught error (e.g. process crash).                                                                                                                                                             |

***

### `project list`

List all projects the authenticated user is a member of.

```text theme={null}
browserstack-binary requestly project list [--output <table|json>]
```

| Flag                    | Default | Description                                   |
| ----------------------- | ------- | --------------------------------------------- |
| `--output <table/json>` | `table` | Output format. `json` is suitable for piping. |

Requires `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY`.

***

### `collection list`

List collections in a project.

```text theme={null}
browserstack-binary requestly collection list --project <id> [--output <table|json>]
```

| Flag                    | Default | Description                |
| ----------------------- | ------- | -------------------------- |
| `--project <id>`        |         | **(Required)** Project ID. |
| `--output <table/json>` | `table` | Output format.             |

Requires `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY`.

***

### `environment list`

List environments in a project (cloud or local).

```text theme={null}
browserstack-binary requestly environment list --project <id> [--output <table|json>]
browserstack-binary requestly environment list <path> [--output <table|json>]
```

| Flag                    | Default | Description                                                |
| ----------------------- | ------- | ---------------------------------------------------------- |
| `--project <id>`        |         | Cloud project ID. Required when targeting a cloud project. |
| `--output <table/json>` | `table` | Output format.                                             |

Pass a local project path as the positional argument to list environments from the filesystem without credentials.

***

### `environment view`

Show variable details for a specific environment.

```text theme={null}
browserstack-binary requestly environment view <id> --project <id> [--output <table|json>]
browserstack-binary requestly environment view <path> [--output <table|json>]
```

| Flag                    | Default | Description                                                              |
| ----------------------- | ------- | ------------------------------------------------------------------------ |
| `--project <id>`        |         | Cloud project ID. Required when identifying the environment by cloud ID. |
| `--output <table/json>` | `table` | Output format.                                                           |

Pass a local environment file path as the positional argument to inspect it without credentials.

***

## Terminal output

The default `cli` reporter streams results in real time. Each request prints as it completes:

```text theme={null}
Requestly - Running your collection...

→ Auth Types Demo
  API Keys
    GET https://httpbin.org/headers [200 OK, 342ms]
    ✓ Status is 200

  → Basic Authentication
    GET https://httpbin.org/basic-auth/demo_user/demo_pass [200 OK, 215ms]
    ✓ Basic auth successful
    ✕ Response contains token
       expected response body to contain 'token'

┌─────────────────────────────┬─────────────────────┬─────────────────────┐
│                             │            executed │              failed │
├─────────────────────────────┼─────────────────────┼─────────────────────┤
│                  iterations │                   1 │                   0 │
├─────────────────────────────┼─────────────────────┼─────────────────────┤
│                    requests │                   2 │                   0 │
├─────────────────────────────┼─────────────────────┼─────────────────────┤
│                test-scripts │                   2 │                   0 │
├─────────────────────────────┼─────────────────────┼─────────────────────┤
│         prerequest-scripts  │                   0 │                   0 │
├─────────────────────────────┼─────────────────────┼─────────────────────┤
│                  assertions │                   3 │                   1 │
├─────────────────────────────────────────────────────────────────────────┤
│ total run duration: 0.6s                                                │
├─────────────────────────────────────────────────────────────────────────┤
│ total data received: 4.2kB (approx)                                     │
├─────────────────────────────────────────────────────────────────────────┤
│ average response time: 278ms [min: 215ms, max: 342ms, s.d.: 63ms]      │
└─────────────────────────────────────────────────────────────────────────┘
```

`console.log()` output from scripts appears between the request line and assertions, wrapped in dash-pipe delimiters:

```text theme={null}
-
| Total posts: 100
| Response time: 622ms
-
```

***

## Examples

**Run a local Requestly project:**

```bash theme={null}
browserstack-binary requestly collection run ./my-project/
```

**Run a specific collection within a project:**

```bash theme={null}
browserstack-binary requestly collection run ./my-project/apis/Auth-Types-Demo/
```

**Run a Postman v2.1 file with JUnit output:**

```bash theme={null}
browserstack-binary requestly collection run ./postman-collection.json \
  -r cli,junit \
  --reporter-junit-export results.xml
```

**Run a specific folder from a Postman collection:**

```bash theme={null}
browserstack-binary requestly collection run ./postman-collection.json \
  --folder "Posts API" \
  --folder "Auth Tests"
```

**Run a collection from a URL:**

```bash theme={null}
browserstack-binary requestly collection run https://example.com/collection.json
```

**Run a cloud collection with an environment:**

```bash theme={null}
browserstack-binary requestly collection run abc123-def456 --project <project-id> -e production
```

**Data-driven run (3 repetitions of a CSV file):**

```bash theme={null}
browserstack-binary requestly collection run ./my-project/ -d test-data.csv -n 3
```

**Bail on first failure with variable overrides:**

```bash theme={null}
browserstack-binary requestly collection run ./my-project/ \
  --bail \
  --env-var host=localhost \
  --env-var port=8080
```

**All four reporters with sensitive headers stripped:**

```bash theme={null}
browserstack-binary requestly collection run ./my-project/ \
  -r cli,json,junit,html \
  --reporter-json-export reports/run.json \
  --reporter-junit-export reports/junit.xml \
  --reporter-html-export reports/report.html \
  --reporter-skip-headers Authorization,X-Api-Key
```

**CI pipeline (JUnit output, fail fast, credentials from env):**

```bash theme={null}
BROWSERSTACK_USERNAME=$BS_USER \
BROWSERSTACK_ACCESS_KEY=$BS_KEY \
browserstack-binary requestly collection run <cloud-collection-id> --project <cloud-project-id> \
  --bail \
  -r cli,junit \
  --reporter-junit-export test-results/junit.xml
```

**List projects:**

```bash theme={null}
browserstack-binary requestly project list
browserstack-binary requestly project list --output json
```

**List collections in a project:**

```bash theme={null}
browserstack-binary requestly collection list --project proj-abc123
browserstack-binary requestly collection list --project proj-abc123 --output json
```

**View an environment:**

```bash theme={null}
browserstack-binary requestly environment view env-xyz789 --project proj-abc123
browserstack-binary requestly environment view ./my-project/environments/staging.json
```