> ## 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.

# Configuration reference

> Project config (reqbook.md), environment config (env.md), auth modes, retry policy, and the web preview settings.

## Project config: `api-docs/reqbook.md`

`api-docs/reqbook.md` is the project configuration file. It uses YAML frontmatter and structured YAML code blocks inside named markdown sections.

### Frontmatter fields

| Field         | Required | Type    | Description                                                               |
| ------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `name`        | yes      | string  | Project name shown in the CLI, web preview, reports, and generated index. |
| `version`     | yes      | integer | Reqbook spec format version. Must be `1` for the current spec format.     |
| `default-env` | yes      | string  | Environment used when a command is run without `--env`.                   |

Unknown frontmatter keys produce a warning and are ignored, allowing future versions to add fields without breaking older clients.

### Complete example

```yaml filename="api-docs/reqbook.md" theme={null}
---
name: my-api
version: 1
default-env: dev
---

# My API

One-paragraph description of the project.

## Defaults

timeout: 5000
retry:
 attempts: 3
 backoff: exponential
auth: bearer

## Web preview

port: 8080
host: 127.0.0.1
theme: auto
autosave: 2s

## Plugins

plugins: []

## Notes

Free-form team notes and conventions. The parser ignores this section entirely.
```

### ## Defaults section

The `## Defaults` code block sets project-wide defaults for every endpoint. Individual endpoint frontmatter can override each value. CLI flags (`--timeout`) override both.

| Key              | Type         | Built-in default | Description                                                           |
| ---------------- | ------------ | ---------------- | --------------------------------------------------------------------- |
| `timeout`        | integer (ms) | `5000`           | Request timeout in milliseconds.                                      |
| `retry.attempts` | integer      | `0`              | Number of retry attempts after the first failure. `0` means no retry. |
| `retry.backoff`  | enum         | `fixed`          | Backoff strategy: `fixed` or `exponential`.                           |
| `auth`           | enum         | `none`           | Default auth mode: `none`, `bearer`, `basic`, or `custom`.            |

If `## Defaults` is absent, the built-in defaults are used for every endpoint.

### ## Web preview section

The `## Web preview` code block controls `rqb serve`. CLI flags (`--port`, `--host`) override these values.

| Key        | Type    | Default     | Description                                           |
| ---------- | ------- | ----------- | ----------------------------------------------------- |
| `port`     | integer | `8080`      | TCP port for the preview server.                      |
| `host`     | string  | `127.0.0.1` | Host to bind to.                                      |
| `theme`    | string  | `auto`      | Color theme: `auto`, `light`, or `dark`.              |
| `autosave` | string  | `2s`        | Debounce interval for live-reload after file changes. |

### ## Plugins section

```yaml theme={null}
plugins: []
```

the current Reqbook release does not execute plugins. The `## Plugins` section is reserved for future use. Keep it as an empty list or omit the section entirely.

### ## Notes section

Free-form prose, checklists, or team conventions. The Reqbook parser ignores this section entirely. Use it for anything that should live alongside the config but not affect execution.

***

## Auth modes

Set the auth mode in `reqbook.md`'s `## Defaults` section (project-wide) or in individual endpoint frontmatter (per-endpoint override).

| Mode     | Description                                                                                                 |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| `none`   | No `Authorization` header added. This is the built-in default.                                              |
| `bearer` | Adds `Authorization: Bearer {{authToken}}`. Requires `authToken` to be resolved from any variable source.   |
| `basic`  | Adds `Authorization: Basic <base64(username:password)>`. Requires both `username` and `password` variables. |
| `custom` | The request block must include the `Authorization` header explicitly. Reqbook does not inject anything.     |

<Tip>
  Set a project-wide default in `reqbook.md`'s `## Defaults` block, then override per-endpoint with `auth:` in the endpoint's frontmatter. The endpoint value always wins.
</Tip>

***

## Retry policy

Configure retries in `reqbook.md`'s `## Defaults` section or in individual endpoint frontmatter.

```yaml theme={null}
retry:
 attempts: 3
 backoff: exponential
```

| Key        | Type    | Default | Description                                                                                          |
| ---------- | ------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `attempts` | integer | `0`     | Number of retry attempts after the first failure. `0` means no retry.                                |
| `backoff`  | enum    | `fixed` | `fixed`: retry immediately with no added delay. `exponential`: double the wait between each attempt. |

<Note>
  Retries apply to network errors (exit code `4`) and to `5xx` responses. They do **not** retry on test assertion failures (exit code `1`) or spec errors (exit code `2`). The `--timeout` CLI flag sets the per-attempt timeout.
</Note>

***

## Environment config: template and local files

Reqbook uses two environment markdown files:

| File                               | Git behavior | Purpose                                                           |
| ---------------------------------- | ------------ | ----------------------------------------------------------------- |
| `api-docs/_shared/env.template.md` | Commit       | Shared shape and safe defaults for new contributors.              |
| `api-docs/_shared/env.md`          | Ignore       | Local values used by the CLI, web preview, MCP tools, and agents. |

Both files use the same format. Each environment is a second-level heading followed by a `yaml` code block.

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

## dev

baseUrl: http://localhost:8080
userId: 123
pageSize: 20

## staging

baseUrl: https://staging.example.com
userId: 456

## prod

baseUrl: https://api.example.com
```

The environment name passed to `--env` must match one of these headings exactly. If the heading is missing, Reqbook exits with code `2`.

<Warning>
  Do not put secrets in either env markdown file. Tokens, passwords, and private keys must go in `.env.local` or `RQB_*` environment variables. The parser enforces this at validation time and exits with code `5` if a secret pattern is detected.
</Warning>

***

## Variable resolution priority

When the same variable name is defined in more than one source, the highest-priority source wins.

| 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 endpoint's YAML block |
| 4           | `_shared/env.md` for the selected env | `## dev` block with `userId: 123`         |
| 5           | `.env.local`                          | `authToken=local-dev-token`               |
| 6 (lowest)  | OS environment variables (`RQB_*`)    | `RQB_USER_ID=99`                          |

OS environment variables are stripped of the `RQB_` prefix and converted to lower camel case:

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