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

# Variables & environments

> Reqbook resolves {{variable}} placeholders from six sources in strict priority order. Learn how to configure environments, use .env.local, and pass secrets safely.

## Variable syntax

Reqbook supports two placeholder forms that can appear anywhere in request blocks, response blocks, and pipeline definitions.

**Inline variable** resolved from any variable source:

```http theme={null}
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
```

**Path parameter** shorthand for URL path segments, resolved from the same sources:

```http theme={null}
GET {{baseUrl}}/users/:id
```

Both forms are interchangeable from a resolution standpoint. Use `:param` in the `path` frontmatter field and URL paths; use `{{name}}` everywhere else.

***

## Resolution priority

When the same variable name appears in more than one source, the highest-priority source wins. Reqbook resolves variables in this order, from highest to lowest:

| Priority    | Source                                | Example                               |
| ----------- | ------------------------------------- | ------------------------------------- |
| 1 (highest) | Pipeline step capture                 | `Capture: response.body.id as userId` |
| 2           | CLI `--var` flag                      | `--var userId=42`                     |
| 3           | Endpoint frontmatter                  | `userId: 42` in the YAML block        |
| 4           | `_shared/env.md` for the selected env | `## dev` section                      |
| 5           | `.env.local`                          | `authToken=local-token`               |
| 6 (lowest)  | `RQB_*` OS environment variables      | `RQB_AUTH_TOKEN=...`                  |

<Note>
  The web UI, CLI, flows, and agent tools use the same priority order. A request that runs in the browser should resolve the same variables when an agent or CI runs it.
</Note>

### Priority in practice

```bash theme={null}
RQB_USER_ID=from-os rqb exec api-docs/apis/users/get-user.md --var userId=from-cli
# {{userId}} resolves to "from-cli" CLI outranks OS env
```

***

## Environment template and local values

`api-docs/_shared/env.template.md` stores the shared shape and safe defaults for each environment. `api-docs/_shared/env.md` stores the local values used at runtime and is gitignored by default. Select an environment with `--env=<name>`.

````markdown filename="api-docs/_shared/env.template.md" theme={null}
# Environments

## dev

```yaml
baseUrl: http://localhost:8080
pageSize: 20
```

## staging

```yaml
baseUrl: https://staging.example.com
pageSize: 20
```

## prod

```yaml
baseUrl: https://api.example.com
pageSize: 50
```
````

<Warning>
  Do not put tokens, passwords, or API keys in either env markdown file. The Reqbook parser detects common secret patterns and exits with code 5 before any network request is made.
</Warning>

***

## .env.local local secrets

`.env.local` uses standard dotenv syntax. It is gitignored by default and is never committed to version control.

```dotenv filename=".env.local" theme={null}
authToken=local-development-token
webhookSecret=local-development-secret
stripeKey=sk_test_...
```

<Tip>
  `rqb init` creates both `api-docs/_shared/env.template.md` and `api-docs/_shared/env.md`. It adds `.env.local` and `api-docs/_shared/env.md` to `.gitignore` automatically. Run `rqb doctor` to confirm both ignored entries are listed.
</Tip>

***

## RQB\_\* environment variables

Reqbook reads only variables prefixed with `RQB_` from the OS environment. The prefix is stripped and the remainder is converted to lower camelCase before resolution.

| OS variable      | Reqbook variable |
| ---------------- | ---------------- |
| `RQB_AUTH_TOKEN` | `authToken`      |
| `RQB_BASE_URL`   | `baseUrl`        |
| `RQB_USER_ID`    | `userId`         |

### CI/CD pattern

Set secrets as masked CI environment variables and map them with the `RQB_` prefix:

```yaml filename=".github/workflows/api-tests.yml" theme={null}
env:
 RQB_AUTH_TOKEN: ${{ secrets.API_TOKEN }}
 RQB_BASE_URL: https://staging.example.com
```

This keeps secrets out of spec files entirely and works with any CI provider that supports environment variable injection.

***

## Missing variables

If a variable cannot be resolved from any source, Reqbook exits with code 2 before making any network request. The error message names the variable and lists the ways to fix it.

```
api-docs/apis/users/get-user.md: unresolved variable "authToken"
Fix: define authToken in .env.local, pass --var authToken=..., or set RQB_AUTH_TOKEN.
```

<Tip>
  Use `--dry-run` to check which variables are resolved and see the fully-rendered request without sending anything to the network. This is the fastest way to catch missing variables before running in CI.
</Tip>

***

## Nested variables

the current Reqbook release does not resolve variables recursively. If resolving `{{baseUrl}}` produces a string that contains another `{{variable}}`, Reqbook returns an error rather than performing a second resolution pass.

```yaml theme={null}
# Invalid nested variable reference
apiHost: "{{host}}"
baseUrl: "https://{{apiHost}}"
```

This restriction is intentional. Recursive resolution can cause secret values to be embedded inside other values in ways that bypass output masking. Define each variable as a concrete value in the appropriate source instead.