# MCP server
Source: https://docs.markapidown.net/agents/mcp

Ten structured tools for MCP-compatible coding agents: exec, diagnose, flow, author, vars, search, context, history, session, and exec_batch. Surgical context by default; verbose mode for debugging.

The MCP server exposes Reqbook operations as structured JSON-RPC tools for MCP-compatible coding agents. Execution tools return compact JSON by default, `rqb_diagnose` returns an agent-facing next-action plan after a failed endpoint, and `rqb_context` returns surgical contract context unless you request `compact` or `schema` mode. Full request/response payloads only appear when you pass `verbose: true`.

***

## Register with an agent

<Steps>
  <Step title="Install a project or agent config">
    ```bash theme={null}
    rqb install mcp --agent=claude-code
    rqb install mcp --agent=codex-cli
    rqb install mcp --agent=cursor
    rqb install mcp --agent=copilot
    rqb install mcp --agent=opencode
    ```

    Omit `--agent` to install MCP config for every detected agent in the workspace.
  </Step>

  <Step title="Restart or reload the agent">
    Each client discovers MCP servers differently. Restart the agent, reload MCP tools, or use the client's MCP list command.
  </Step>

  <Step title="Verify registration">
    ```bash theme={null}
    claude mcp list
    codex mcp list
    opencode mcp list
    ```

    Expected Claude Code output:

    ```text theme={null}
    rqb: rqb mcp - ✓ Connected
    ```
  </Step>
</Steps>

### Config files written

| Agent                     | Config file                             | Shape                            |
| ------------------------- | --------------------------------------- | -------------------------------- |
| Claude Code               | `.mcp.json`                             | `mcpServers.rqb.command = "rqb"` |
| Codex CLI / IDE           | `.codex/config.toml`                    | `[mcp_servers.rqb]`              |
| Cursor                    | `.cursor/mcp.json`                      | `mcpServers.rqb`                 |
| GitHub Copilot in VS Code | `.vscode/mcp.json`                      | `servers.rqb`                    |
| OpenCode                  | `opencode.json`                         | `mcp.rqb`                        |
| Antigravity               | `~/.gemini/antigravity/mcp_config.json` | `mcpServers.rqb`                 |
| Windsurf / Cascade        | `~/.codeium/windsurf/mcp_config.json`   | `mcpServers.rqb`                 |

<Note>
  Codex loads project-scoped `.codex/config.toml` only for trusted projects. GitHub Copilot requires Agent mode and, for Business/Enterprise accounts, the organization's MCP policy must allow MCP servers. Windsurf and Antigravity use global `mcp_config.json` files, so reload the client after installing.
</Note>

***

## Available tools

| Tool             | Purpose                                                                            |
| ---------------- | ---------------------------------------------------------------------------------- |
| `rqb_exec`       | Execute one endpoint spec compact result by default                                |
| `rqb_diagnose`   | Execute one endpoint and return likely cause, inspect targets, and verify commands |
| `rqb_flow`       | Run a pipeline compact per-step summary by default                                 |
| `rqb_author`     | Create or update a spec (validates before writing, refuses silent overwrite)       |
| `rqb_vars`       | Show which variables a spec needs and which are resolved                           |
| `rqb_search`     | Search specs by method, path, tag, or text no file reading required                |
| `rqb_context`    | Return bounded executable API context for a target, flow, or changed specs         |
| `rqb_history`    | Execution history and trend for a spec                                             |
| `rqb_session`    | Get/set session env + vars (defaults for all exec/flow calls)                      |
| `rqb_exec_batch` | Run multiple specs and return a summary table                                      |

For tools that execute a concrete spec or pipeline, the MCP server resolves variables from `api-docs/_shared/env.md`, `.env.local`, `RQB_*` / `MAD_*` environment variables, session vars, and explicit tool `vars`. Explicit `vars` have the highest priority.

**Not in MCP use these directly:**

| Operation            | How                     |
| -------------------- | ----------------------- |
| Validate specs       | `rqb validate <path>`   |
| Start the browser UI | `rqb serve`             |
| Import from cURL     | `rqb import curl '...'` |

***

## Compact vs verbose output

By default, `rqb_exec` and `rqb_flow` return only what agents need to act: pass/fail, status code, diff, and error type. Full request and response bodies are omitted.

```json theme={null}
{
 "passed": false,
 "status": 422,
 "duration_ms": 234,
 "error_type": "CONTRACT_MISMATCH",
 "hint": "Update ## Expected response in the spec to match actual, or fix the API",
 "diff": { "passed": false, "status": null, "headers": [], "body": "response body did not match expected shape" }
}
```

Pass `verbose: true` to include the full `request` and `response` objects.

***

## Error taxonomy

All tools use a consistent set of error type strings so agents can branch without parsing text:

| `error_type`           | Meaning                                               |
| ---------------------- | ----------------------------------------------------- |
| `CONTRACT_MISMATCH`    | Response doesn't match `## Expected response`         |
| `VAR_MISSING`          | One or more `{{variables}}` could not be resolved     |
| `AUTH_FAILED`          | Response was 401 or 403                               |
| `NETWORK_ERROR`        | Connection or timeout failure                         |
| `SPEC_PARSE_ERROR`     | Spec file has invalid frontmatter or missing sections |
| `VALIDATION_ERROR`     | Request or expected response block has a syntax error |
| `UNSUPPORTED_PROTOCOL` | Spec uses `ws` or `sse` (not yet implemented)         |

Execution errors include a `hint` field with a short actionable string. For deeper branching after a failed endpoint, call `rqb_diagnose` and use its `likely_cause`, `next_action`, `inspect`, and `verify` fields.

***

## Tool reference

### rqb\_exec

Execute one endpoint spec and return the HTTP result.

**Input**

| Parameter        | Type    | Required | Default            | Description                                                |
| ---------------- | ------- | -------- | ------------------ | ---------------------------------------------------------- |
| `spec_path`      | string  | yes      |                    | Path to the spec file                                      |
| `env`            | string  | no       | session or `"dev"` | Environment name                                           |
| `vars`           | object  | no       | `{}`               | Runtime variable overrides                                 |
| `verbose`        | boolean | no       | `false`            | Include full request + response objects                    |
| `dry_run`        | boolean | no       | `false`            | Resolve variables and return request without sending       |
| `infer_expected` | boolean | no       | `false`            | Add `inferred_expected` block ready to paste into the spec |

**Compact output (default)**

```json theme={null}
{
 "passed": true,
 "status": 201,
 "duration_ms": 143,
 "error_type": null,
 "diff": { "passed": true, "status": null, "headers": [], "body": null },
 "assertion_results": []
}
```

**On failure CONTRACT\_MISMATCH with hints**

```json theme={null}
{
 "passed": false,
 "status": 200,
 "error_type": "CONTRACT_MISMATCH",
 "hint": "Update ## Expected response in the spec to match actual, or fix the API",
 "hints": [
 "Update ## Expected response: change status line to HTTP/1.1 200 <reason>",
 "Run with infer_expected: true to get the actual response as an Expected Response block"
 ],
 "diff": { "passed": false, "status": "expected 201, got 200", "headers": [], "body": null }
}
```

**With `infer_expected: true`**

```json theme={null}
{
 "passed": true,
 "inferred_expected": "HTTP/1.1 201 Created\nContent-Type: application/json\n\n{\"id\":\"usr_123\",\"email\":\"ada@example.com\"}"
}
```

Paste the value into your spec's `## Expected response` block.

***

### rqb\_diagnose

Execute one endpoint and return a compact diagnosis for the agent's next step. Use this after `rqb_exec` fails and before reading backend source broadly.

**Input**

| Parameter           | Type    | Required | Default            | Description                                              |
| ------------------- | ------- | -------- | ------------------ | -------------------------------------------------------- |
| `spec_path`         | string  | yes      |                    | Path to the spec file                                    |
| `env`               | string  | no       | session or `"dev"` | Environment name                                         |
| `vars`              | object  | no       | `{}`               | Runtime variable overrides                               |
| `timeout_ms`        | integer | no       | endpoint default   | Request timeout override                                 |
| `strict_assertions` | boolean | no       | `false`            | Treat failing structured assertions as contract failures |

**Output**

```json theme={null}
{
 "passed": false,
 "status": 422,
 "error_type": "CONTRACT_MISMATCH",
 "summary": "POST /refunds/quote failed: CONTRACT_MISMATCH",
 "likely_cause": "API returned documented error response HTTP 422.",
 "next_action": "Inspect request variables/body/auth first; the backend may be correct and the test input may be invalid.",
 "inspect": [
  "backend route for POST /refunds/quote",
  "api-docs/apis/refunds/post-refund-quote.md ## Expected response",
  "api-docs/apis/refunds/post-refund-quote.md ## Error responses"
 ],
 "verify": [
  "rqb validate api-docs",
  "rqb exec api-docs/apis/refunds/post-refund-quote.md --env dev"
 ],
 "diff": { "status": "expected 201, got 422", "headers": [], "body": null, "assertions": [] }
}
```

The tool returns the same object as `structuredContent`, so MCP clients can branch on `error_type`, `likely_cause`, `inspect`, and `verify` without parsing the text content.

***

### rqb\_flow

Run a pipeline and return per-step results.

**Input**

| Parameter       | Type    | Required | Default            | Description                             |
| --------------- | ------- | -------- | ------------------ | --------------------------------------- |
| `pipeline_path` | string  | yes      |                    | Path to the pipeline file               |
| `env`           | string  | no       | session or `"dev"` | Environment name                        |
| `verbose`       | boolean | no       | `false`            | Include full execution objects per step |

**Compact output (default)**

```json theme={null}
{
 "passed": false,
 "captures": { "orderId": "ord_456" },
 "steps": [
 { "name": "Create order", "endpoint": "apis/orders/post-orders.md", "passed": true, "status": 201, "error_type": null },
 { "name": "Fetch order", "endpoint": "apis/orders/get-order.md", "passed": false, "status": 404, "error_type": "CONTRACT_MISMATCH" }
 ]
}
```

***

### rqb\_author

Create a new spec file or update an existing one.

**Input**

| Parameter   | Type    | Required | Default | Description                       |
| ----------- | ------- | -------- | ------- | --------------------------------- |
| `spec_path` | string  | yes      |         | Destination file path             |
| `content`   | string  | yes      |         | Full markdown content of the spec |
| `overwrite` | boolean | no       | `false` | Allow replacing an existing file  |

**Output** `{ "created": true, "file": "api-docs/...", "method": "POST", "path": "/users", "title": "Create User" }`

On validation failure: the error from the parser. The file is not created or modified.

<Note>
  `rqb_author` validates the spec before touching the filesystem. If validation fails, nothing is written.
</Note>

***

### rqb\_vars

Show which variables a spec requires and which are resolved for the current environment.

**Input**

| Parameter   | Type   | Required | Default            | Description                  |
| ----------- | ------ | -------- | ------------------ | ---------------------------- |
| `spec_path` | string | yes      |                    | Path to the spec file        |
| `env`       | string | no       | session or `"dev"` | Environment to check against |

**Output**

```json theme={null}
{
 "spec": "apis/users/create-user.md",
 "env": "dev",
 "ready": false,
 "variables": [
 { "name": "baseUrl", "kind": "template", "resolved": true, "source": "env.md" },
 { "name": "authToken", "kind": "template", "resolved": false, "hint": "Set in _shared/env.md [dev] or pass as vars: {\"authToken\": \"...\"}" },
 { "name": "userId", "kind": "path_param", "resolved": false, "hint": "Pass as vars: {\"userId\": \"...\"}" }
 ]
}
```

`ready: true` means all variables are resolved and the spec can be executed immediately.

***

### rqb\_search

Search specs without reading individual files. Useful for discovering relevant specs before deciding which ones to run.

**Input** (all optional)

| Parameter | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| `q`       | string | Text search in title or description          |
| `method`  | string | HTTP method filter (`"GET"`, `"POST"`, etc.) |
| `path`    | string | URL path substring match                     |
| `tag`     | string | Tag filter                                   |

**Output**

```json theme={null}
{
 "count": 3,
 "results": [
 { "file": "apis/users/create-user.md", "method": "POST", "path": "/users", "title": "Create User", "tags": ["users", "write"] },
 { "file": "apis/users/get-user.md", "method": "GET", "path": "/users/:userId", "title": "Get User", "tags": ["users", "read"] }
 ]
}
```

***

### rqb\_context

Return bounded executable API context for an endpoint, flow, or changed specs. This is the lowest-token way to give an agent relevant request/response contracts without asking it to read many files.

**Input** (all optional)

| Parameter      | Type                                      | Default       | Description                                                                                                                         |
| -------------- | ----------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `target`       | string                                    |               | Endpoint/flow id or file path, e.g. `users.create`                                                                                  |
| `changed_from` | string                                    |               | Git ref used to summarize changed specs only                                                                                        |
| `root`         | string                                    | `api-docs`    | Reqbook docs root                                                                                                                   |
| `token_budget` | integer                                   | `600`         | Approximate output token budget                                                                                                     |
| `mode`         | `"surgical"` \| `"compact"` \| `"schema"` | `"surgical"`  | Contract-only, human-readable compact, or JSON schema summary                                                                       |
| `intent`       | string                                    | `"implement"` | Agent task intent, e.g. `implement`, `debug`, `test`, `review`, or `document`                                                       |
| `brief`        | boolean                                   | `true`        | Token-optimized context: no title/guidance, bounded executable sections                                                             |
| `max_fields`   | integer                                   | `6`           | Maximum request/response fields per section. Use `12` for implement/review/debug tasks that need complete behavior.                 |
| `include`      | string                                    |               | Comma-separated sections: `title`, `variables`, `request`, `response`, `errors`, `assertions`, `rules`, `verify`, `guidance`, `all` |
| `no_guidance`  | boolean                                   | `false`       | Omit agent workflow guidance text                                                                                                   |
| `verbose`      | boolean                                   | `false`       | Include full request and expected response blocks                                                                                   |
| `env`          | string                                    | `dev`         | Environment used in suggested next commands                                                                                         |

**Output**

```text theme={null}
API contract (implement): POST /users
File: apis/users/post-users.md
Variables: baseUrl, authToken
Request body: body.email:string, body.role:string
Success response: HTTP 201 body.id:string, body.email:string
Error responses: HTTP 400 body.error:string, body.message:string
Verify:
- rqb validate api-docs
- rqb exec api-docs/apis/users/post-users.md --env dev
```

The tool also returns `structuredContent` for MCP clients, so agents can consume method/path, bounded field lists, error responses, assertions, and verify commands without parsing text. Use `mode: "schema"` when the client wants the text content itself to be machine-readable JSON.

***

### rqb\_history

Return recent execution history for a spec.

**Input**

| Parameter   | Type    | Required | Default | Description                        |
| ----------- | ------- | -------- | ------- | ---------------------------------- |
| `spec_path` | string  | yes      |         | Path to the spec file              |
| `last`      | integer | no       | `10`    | Number of recent entries to return |

**Output**

```json theme={null}
{
 "spec": "apis/users/create-user.md",
 "trend": "regressing",
 "entries": [
 { "timestamp": "2026-05-29T10:00:00Z", "passed": true, "status": 201, "duration_ms": 230, "error_type": null },
 { "timestamp": "2026-05-29T10:05:00Z", "passed": false, "status": 422, "duration_ms": 89, "error_type": "CONTRACT_MISMATCH" }
 ]
}
```

`trend` is `"stable"`, `"improving"`, or `"regressing"` based on the last 6 executions.

***

### rqb\_session

Get or set the session context. Session env and vars are used as defaults by all exec/flow tools explicit params always take priority.

**Input**

| Parameter | Type               | Required      | Description                      |
| --------- | ------------------ | ------------- | -------------------------------- |
| `action`  | `"get"` \| `"set"` | yes           | Get current session or update it |
| `env`     | string             | no (set only) | Environment to store in session  |
| `vars`    | object             | no (set only) | Variables to store in session    |

**Example set staging session**

```json theme={null}
{ "action": "set", "env": "staging", "vars": { "authToken": "tok_xyz" } }
```

After this, all `rqb_exec` / `rqb_flow` calls use `env: "staging"` and `authToken` by default.

***

### rqb\_exec\_batch

Execute multiple specs in one call and return a compact summary table.

**Input**

| Parameter | Type      | Required | Default            | Description             |
| --------- | --------- | -------- | ------------------ | ----------------------- |
| `specs`   | string\[] | yes      |                    | List of spec file paths |
| `env`     | string    | no       | session or `"dev"` | Environment name        |
| `vars`    | object    | no       | `{}`               | Variable overrides      |

**Output**

```json theme={null}
{
 "summary": { "total": 3, "passed": 2, "failed": 1, "duration_ms": 789 },
 "results": [
 { "spec": "apis/users/create-user.md", "passed": true, "status": 201, "duration_ms": 312 },
 { "spec": "apis/users/get-user.md", "passed": true, "status": 200, "duration_ms": 234 },
 { "spec": "apis/orders/post-orders.md", "passed": false, "status": 422, "error_type": "CONTRACT_MISMATCH", "duration_ms": 243, "hint": "Update ## Expected response in the spec to match actual, or fix the API" }
 ]
}
```

***

## Assertion DSL

Specs can include structured assertions in a `## Assertions` section. Reqbook evaluates these after each execution and returns results in `assertion_results`.

```markdown theme={null}
## Assertions
- status: 201
- body.id: exists
- body.email: equals "ada@example.com"
- body.role: in [admin, user]
- headers.content-type: contains application/json
- body.slug: matches ^[a-z-]+$
```

Supported operators: `exists`, `equals`, `contains`, `in`, `matches` (regex).

Assertion results appear in `rqb_exec` output:

```json theme={null}
{
 "assertion_results": [
 { "rule": "status: equals 201", "passed": true, "message": "= 201" },
 { "rule": "body.role: in [admin, user]", "passed": false, "message": "expected one of [admin, user], got `guest`" }
 ]
}
```

***

## MCP resources

Specs are also accessible as MCP Resources under the `rqb://spec/` URI scheme. Agents can browse and read spec content directly through the protocol without calling any tool.

***

## Typical agent workflow

```text theme={null}
1. rqb_search { "method": "POST", "tag": "orders" }
 → Finds api-docs/apis/orders/post-orders.md

2. rqb_vars { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → ready: false authToken is missing

3. rqb_session { "action": "set", "env": "dev", "vars": { "authToken": "tok_abc" } }
 → Session set

4. rqb_exec { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → { "passed": false, "error_type": "CONTRACT_MISMATCH", "hints": [...] }

5. rqb_diagnose { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → { "likely_cause": "...", "next_action": "...", "inspect": [...], "verify": [...] }

6. rqb_exec { "spec_path": "...", "infer_expected": true }
 → { "inferred_expected": "HTTP/1.1 201 Created\n..." }

7. rqb_author { "spec_path": "...", "content": "...(with inferred expected)...", "overwrite": true }
 → Spec updated

8. rqb_exec_batch { "specs": ["...", "...", "..."] }
 → { "summary": { "total": 3, "passed": 3 } }
```


# Set up agent support
Source: https://docs.markapidown.net/agents/setup

Install the skill, slash commands, and the MCP server for Claude Code, Cursor, Copilot, Codex CLI, Antigravity, OpenCode, and Windsurf.

Agent support turns a coding agent into an API-capable collaborator that can scan routes, enrich specs, build flows, and debug failures — all backed by reviewable markdown files in your repo.

<CardGroup>
  <Card title="Skills" icon="book-open">
    A single markdown playbook that teaches agents the Reqbook spec format, file layout, and how to choose the right approach for each task. All agents get the skill.
  </Card>

  <Card title="Slash commands" icon="terminal">
    Two `/rqb` commands for Claude Code and Codex CLI: `/rqb` for creating, enriching, and building flows; `/rqb-debug` for diagnosing failures.
  </Card>

  <Card title="MCP server" icon="plug">
    Structured tools for MCP-compatible agents: exec, flow, author, surgical context, and more. Agents get typed results without parsing shell output.
  </Card>

  <Card title="Shared markdown source" icon="code-pull-request">
    Every agent change is a markdown file in `api-docs/`. Reviewable, diffable, committable. No hidden state.
  </Card>
</CardGroup>

***

## Install in one command

<Steps>
  <Step title="Install skill and slash commands">
    Run the installer from the root of your project. It auto-detects which agents are present and writes the correct files for each.

    ```bash theme={null}
    rqb skills install
    ```

    The command writes the skill and (for Claude Code / Codex CLI) slash commands to the directories each agent reads.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    rqb skills list
    ```

    Example output:

    ```
    claude-code detected .claude/skills/rqb/SKILL.md
                          .claude/commands/rqb.md
                          .claude/commands/rqb-debug.md
    cursor     detected   .cursor/rules/rqb.mdc
    copilot    detected   .github/instructions/rqb.instructions.md
    ```
  </Step>

  <Step title="Register the MCP server">
    The MCP server gives compatible agents structured access to spec execution, pipelines, context packs, and authoring — no terminal output parsing.

    ```bash theme={null}
    rqb install mcp
    ```

    To target one agent:

    ```bash theme={null}
    rqb install mcp --agent=codex-cli
    rqb install mcp --agent=cursor
    rqb install mcp --agent=copilot
    ```
  </Step>
</Steps>

<Tip>
  For token-sensitive agent runs, start with `rqb_context` using `mode: "surgical"`, `brief: true`, `max_fields: 6`, and an explicit `intent`. If an endpoint fails, call `rqb_diagnose` before reading backend source. Together they return the bounded contract, likely cause, inspect targets, and verify commands before the agent decides how much source inspection is necessary.
</Tip>

***

## Per-agent install

<CodeGroup>
  ```bash Claude Code theme={null}
  rqb skills install --agent=claude-code
  # Installs: 1 skill + 2 slash commands
  # Locations: .claude/skills/rqb/, .claude/commands/
  ```

  ```bash Codex CLI theme={null}
  rqb skills install --agent=codex-cli
  # Installs: 1 skill + 2 slash commands
  # Locations: .agents/skills/rqb/, ~/.codex/commands/
  ```

  ```bash Cursor theme={null}
  rqb skills install --agent=cursor
  # Installs: 1 skill as .mdc rule
  # Location: .cursor/rules/
  ```

  ```bash GitHub Copilot theme={null}
  rqb skills install --agent=copilot
  # Installs: 1 skill as .instructions.md
  # Location: .github/instructions/
  ```

  ```bash Antigravity theme={null}
  rqb skills install --agent=antigravity
  # Installs: 1 skill
  # Location: .agents/skills/
  ```

  ```bash OpenCode theme={null}
  rqb skills install --agent=opencode
  # Installs: 1 skill
  # Location: .opencode/skills/
  ```

  ```bash Windsurf theme={null}
  rqb skills install --agent=windsurf
  # Installs: 1 skill as a rule
  # Location: .windsurf/rules/
  ```
</CodeGroup>

### What each agent gets

| Agent          | Skills  | Slash commands | MCP |
| -------------- | ------- | -------------- | --- |
| Claude Code    | 1 skill | 2 commands     | ✓   |
| Codex CLI      | 1 skill | 2 commands     | ✓   |
| Cursor         | 1 skill |                | ✓   |
| GitHub Copilot | 1 skill |                | ✓   |
| Antigravity    | 1 skill |                | ✓   |
| OpenCode       | 1 skill |                | ✓   |
| Windsurf       | 1 skill |                | ✓   |

### MCP config locations

| Agent                     | Command                               | Config                                  |
| ------------------------- | ------------------------------------- | --------------------------------------- |
| Claude Code               | `rqb install mcp --agent=claude-code` | `.mcp.json`                             |
| Codex CLI / IDE           | `rqb install mcp --agent=codex-cli`   | `.codex/config.toml`                    |
| Cursor                    | `rqb install mcp --agent=cursor`      | `.cursor/mcp.json`                      |
| GitHub Copilot in VS Code | `rqb install mcp --agent=copilot`     | `.vscode/mcp.json`                      |
| OpenCode                  | `rqb install mcp --agent=opencode`    | `opencode.json`                         |
| Antigravity               | `rqb install mcp --agent=antigravity` | `~/.gemini/antigravity/mcp_config.json` |
| Windsurf / Cascade        | `rqb install mcp --agent=windsurf`    | `~/.codeium/windsurf/mcp_config.json`   |

***

## Keep skills current

After upgrading Reqbook, check whether installed skills match the current binary:

```bash theme={null}
rqb doctor
```

To update stale skills automatically:

```bash theme={null}
rqb doctor --fix
```

<Warning>
  Stale skills are the most common cause of agents missing new commands or writing files in unexpected ways. Run `rqb doctor --fix` after every Reqbook upgrade.
</Warning>


# Skills reference
Source: https://docs.markapidown.net/agents/skills

A single SKILL.md playbook installed for every supported agent — teaches the Reqbook spec format, file layout, MCP tools, and when to use each command.

Skills are markdown playbooks embedded in the Reqbook binary. When installed, agents read them from their config directories and apply them automatically when a user prompt matches a known intent — you do not need to mention Reqbook explicitly.

<Card title="rqb" icon="book-open">
  Covers the full Reqbook workflow: project layout, endpoint spec format, Assertions operators, pipeline capture patterns, MCP tool reference, and routing rules for when to use each slash command.
</Card>

***

## Install

```bash theme={null}
rqb skills install
```

This writes the skill to every supported agent's config directory. To target one agent:

```bash theme={null}
rqb skills install --agent=cursor
rqb skills install --agent=copilot
rqb skills install --agent=claude-code
```

***

## What the skill teaches

### Project layout

```
api-docs/
├── reqbook.md              # project config (name, default-env, timeouts)
├── _shared/env.template.md # shared environment template
├── _shared/env.md          # local base URLs and variables
├── apis/<resource>/<method>-<slug>.md   # one file per endpoint
└── flows/<name>.md         # multi-step pipelines
```

### Endpoint format

Required frontmatter: `resource`, `protocol: http`, `method`, `path` (`:param` for path params), `version: 1`.

Sections in order: `## Request` → `## Expected response` → `## Error responses` (optional) → `## Assertions` (optional) → `## Tests` (optional) → `## Notes` (optional).

### Assertions

Structured rules that run after each execution:

| Operator   | Example                                   |
| ---------- | ----------------------------------------- |
| *(equals)* | `status: 200` · `body.name: Ada Lovelace` |
| `exists`   | `body.id: exists`                         |
| `in [...]` | `body.role: in [admin, user]`             |
| `contains` | `headers.content-type: contains json`     |
| `matches`  | `body.slug: matches ^[a-z]+$`             |

### Pipeline capture patterns

| Pattern                      | When to use               |
| ---------------------------- | ------------------------- |
| `response.body.<field>`      | Top-level JSON field      |
| `response.body.<a>.<b>`      | Nested JSON field         |
| `response.body[<n>].<field>` | Field from nth array item |
| `response.headers.<name>`    | Response header value     |

### Routing table

The skill routes the agent to the right tool or command based on the situation:

| Situation                            | Action                  |
| ------------------------------------ | ----------------------- |
| Create or update specs               | `/rqb`                  |
| Debug a failing endpoint or pipeline | `/rqb-debug`            |
| Execute a spec                       | `rqb_exec` MCP tool     |
| Diagnose a failed endpoint           | `rqb_diagnose` MCP tool |
| Run a pipeline                       | `rqb_flow` MCP tool     |

***

## Supported agents

| Agent          | Skill format       | Path                                       |
| -------------- | ------------------ | ------------------------------------------ |
| Claude Code    | `SKILL.md`         | `.claude/skills/rqb/SKILL.md`              |
| Cursor         | `.mdc`             | `.cursor/rules/rqb.mdc`                    |
| GitHub Copilot | `.instructions.md` | `.github/instructions/rqb.instructions.md` |
| Codex CLI      | `SKILL.md`         | `.agents/skills/rqb/SKILL.md`              |
| Antigravity    | `SKILL.md`         | `.agents/skills/rqb/SKILL.md`              |
| OpenCode       | `SKILL.md`         | `.opencode/skills/rqb/SKILL.md`            |
| Windsurf       | `.md` (rule)       | `.windsurf/rules/rqb.md`                   |

All agents receive the same skill content — only the file format differs.


# Slash commands
Source: https://docs.markapidown.net/agents/slash-commands

Two /rqb commands for Claude Code and Codex CLI — each handles a complex, multi-step task that benefits from LLM reasoning rather than a fixed script.

## Design philosophy

Simple terminal operations — `rqb init`, `rqb serve`, `rqb validate`, `rqb exec` — work best when run directly. They are fast, composable, and don't need an agent in the loop.

Slash commands exist for tasks that are **genuinely complex**: where the right answer depends on understanding your codebase, your domain model, or the relationships between data — not just executing a formula.

***

## Available commands

<CardGroup>
  <Card title="/rqb" icon="magnifying-glass">
    Create specs, enrich expected responses, or build and run pipelines. Routes automatically based on what you pass.
  </Card>

  <Card title="/rqb-debug" icon="bug">
    Diagnose a failing endpoint or pipeline across validation, execution, and diff.
  </Card>
</CardGroup>

***

## /rqb

**When to use:** Creating new specs, enriching expected responses and tests, or building and running flow pipelines.

The command routes based on your argument:

| Argument                               | What happens                         |
| -------------------------------------- | ------------------------------------ |
| *(empty)*, `scan`, or a directory      | Scan routes and create missing specs |
| `enrich`, a `.md` file, or a directory | Enrich expected responses and tests  |
| `flow` or a flow description           | Build or run a pipeline              |

```
/rqb
/rqb src/routes/
/rqb enrich api-docs/apis/users/post-users.md
/rqb flow checkout: login, add items, place order, verify
/rqb api-docs/flows/checkout.md
```

### Scan mode

**What makes it intelligent:** The agent doesn't just run `rqb import project` and stop. When automatic discovery produces stubs, the agent reads your handler source code — request/response types, DTOs, model classes — and produces specs with real field names and semantically accurate example values. A `user.email` field becomes `"user@example.com"`, not `"string"`.

What the agent does:

1. Tries `rqb import project` first (OpenAPI or running server)
2. If stubs are produced, reads handler source to enrich field shapes
3. If nothing is detected, finds route files and reads full type definitions
4. Creates specs via `rqb_author` MCP tool (validates before writing, never overwrites)
5. Runs `rqb validate api-docs/` then `rqb index`

### Enrich mode

**What makes it intelligent:** The agent uses a bounded evidence ladder — reads the spec, inspects the matching handler and referenced DTO/schema files, optionally executes the live dev endpoint, then stops and asks for an example if the shape is unknown. It never guesses.

What the agent does:

1. Reads the spec and its route handler
2. Runs `rqb_exec` with `infer_expected: true` if the server is up — uses the live response
3. Writes real field values to `## Expected response`
4. Adds `## Assertions`: at minimum `status` and one `body.<key>: exists`
5. Adds `## Tests`: happy path + auth failure + one validation error

### Flow mode

**What makes it intelligent:** Before writing a single line, the agent reasons about data dependencies — which step produces `authToken`? Which downstream steps need it? What should be asserted at each step to make the flow meaningful, not just a sequence of "status 200" checks?

What the agent does when building:

1. Reads existing specs to understand what data each endpoint returns
2. Maps the capture/inject chain before writing
3. Identifies missing specs (offers to create them)
4. Writes the pipeline file with meaningful assertions at each step
5. Validates with `rqb validate`

What the agent does when running:

* Executes `rqb_flow` MCP tool
* Reports each step's status, captured values (secrets masked), and first failure with diagnosis

***

## /rqb-debug

**When to use:** An endpoint is returning an unexpected result, a spec diff is failing, or a pipeline is breaking at a specific step.

```
/rqb-debug GET /users/:id is returning 404
/rqb-debug the checkout flow fails at step 3
/rqb-debug api-docs/apis/orders/post-orders.md
```

### Single endpoint

What the agent does:

1. Locates the spec via `rqb_search` MCP or `rg`
2. Validates the spec structure
3. Dry-runs to check what's being sent (baseUrl, auth, path params)
4. Executes and interprets the result:

| Exit code         | Meaning                   | Next action                                         |
| ----------------- | ------------------------- | --------------------------------------------------- |
| `0`               | Passed — response matched | No action needed                                    |
| `2`               | Invalid spec              | Fix frontmatter or `## Request` http block          |
| `4`               | Network error             | Check `baseUrl` in `_shared/env.md`, server running |
| `5`               | Secret in spec            | Move value to `.env.local` or `RQB_*`               |
| Response mismatch | API changed or regression | Update `## Expected response` or fix the API        |

### Pipeline

What the agent does:

1. Reads all step files — checks order, capture expressions, inject names, referenced specs
2. Runs the full flow via `rqb_flow` MCP
3. Identifies the first failing step
4. Debugs that step in isolation with captured values from prior steps injected as `--var`

***

## Terminal commands — use these directly

| What you want to do      | Command                                                  |
| ------------------------ | -------------------------------------------------------- |
| Initialize a new project | `rqb init --name my-api --dev-url http://localhost:3000` |
| Start the web preview    | `rqb serve`                                              |
| Start the mock server    | `rqb mock api-docs/`                                     |
| Run one endpoint spec    | `rqb exec api-docs/apis/users/get-user.md`               |
| Validate all specs       | `rqb validate api-docs/`                                 |
| Register MCP server      | `rqb install mcp --agent=claude-code`                    |
| Import a curl command    | `rqb import curl`                                        |

***

## Supported agents

| Agent          | Slash commands |
| -------------- | -------------- |
| Claude Code    | ✓ (2 commands) |
| Codex CLI      | ✓ (2 commands) |
| Cursor         | (use skills)   |
| GitHub Copilot | (use skills)   |
| Antigravity    | ✓ (2 commands) |
| OpenCode       | (use skills)   |


# Reqbook CLI for API Testing
Source: https://docs.markapidown.net/cli/overview

Run Reqbook from the terminal to validate, execute, flow-test, import, and package markdown API specs for coding agents.

## What is rqb-cli?

**rqb-cli** is the terminal interface to Reqbook. Every capability is accessible as a subcommand.

Use it for:

* Scripted API testing and CI/CD pipelines
* Importing and validating specs
* Running ad-hoc HTTP requests from the terminal
* AI agent tool integration via MCP

## Commands

| Command                                                         | What it does                                                                  |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `rqb init`                                                      | Scaffold a new collection in the current project                              |
| `rqb request <METHOD> <URL>`                                    | Send an ad-hoc HTTP request                                                   |
| `rqb exec <file>`                                               | Execute one endpoint spec                                                     |
| `rqb diagnose <file>`                                           | Diagnose a failed endpoint with likely cause and next action                  |
| `rqb flow <file>`                                               | Run a multi-step pipeline, or inspect resolved step requests with `--dry-run` |
| `rqb validate <path>`                                           | Validate endpoint or pipeline files                                           |
| `rqb check <path>`                                              | Run PR-focused contract checks and reports                                    |
| `rqb context <target>`                                          | Print bounded executable API context for coding agents                        |
| `rqb agent pack <target>`                                       | Write an agent-ready context pack with guardrails and verify commands         |
| `rqb import postman\|insomnia\|openapi\|collection\|http\|curl` | Import from another tool or local collection format                           |
| `rqb export openapi <path>`                                     | Export markdown endpoint specs as OpenAPI                                     |
| `rqb serve`                                                     | Launch rqb-ui in a browser                                                    |
| `rqb mock`                                                      | Start a mock HTTP server                                                      |
| `rqb mcp`                                                       | Start MCP server for AI agent integration                                     |
| `rqb doctor`                                                    | Diagnose project setup                                                        |

## Same binary two interfaces

```
rqb serve → opens rqb-ui in your browser
rqb exec → runs in the terminal (rqb-cli)
```

Both ship in one binary. There is no separate installation.


# rqb request
Source: https://docs.markapidown.net/cli/request

Send an ad-hoc HTTP request from the terminal without creating a spec file first.

## Overview

`rqb request` lets you fire off any HTTP request from the terminal no spec file needed. It feels like `curl` but with automatic variable resolution and optional spec saving.

## Usage

```bash theme={null}
rqb request <METHOD> <URL> [options]
```

## Examples

```bash theme={null}
# Simple GET
rqb request GET https://api.example.com/users

# POST with JSON body
rqb request POST https://api.example.com/users \
 -H "Content-Type: application/json" \
 -d '{"name":"Ada Lovelace"}'

# Use variables from env.md
rqb request GET https://api.example.com/users/{{userId}} --var userId=42

# Dry-run (print resolved request, don't send)
rqb request GET https://api.example.com/users --dry-run

# Save result as a spec file
rqb request GET https://api.example.com/users --save api-docs/apis/users/get-users.md

# Auto-save to current collection
rqb request GET https://api.example.com/users --save
```

## Default output

Compact by default (agent-friendly):

```
200 OK 147ms
[{"id":1,"name":"Ada Lovelace"}]
```

Add `--verbose` for the full diff view.

## Options

| Flag                         | Description                                                       |
| ---------------------------- | ----------------------------------------------------------------- |
| `-H, --header <Name: Value>` | Add a request header. Repeatable.                                 |
| `-d, --data <body>`          | Request body string, or `@file` to read from a file.              |
| `--var <key=value>`          | Variable override. Repeatable.                                    |
| `--env <name>`               | Environment for variable resolution (default: `dev`).             |
| `--dry-run`                  | Print the resolved request without sending.                       |
| `--timeout <ms>`             | Timeout override in milliseconds.                                 |
| `--save [path]`              | Save result as a spec file. Omit path to auto-save to collection. |
| `--verbose`                  | Full diff output.                                                 |

## Workspace behaviour

* **Inside a git repo**: the collection is at `<repo-root>/api-docs/`. Auto-saved requests go to `<repo-root>/api-docs/apis/scratch/`.
* **Outside a git repo**: the collection is at `~/.rqb/workspace/default/api-docs/`. Unsaved requests go to `~/.rqb/workspace/scratch/api-docs/`.


# Markdown Endpoint Files
Source: https://docs.markapidown.net/essentials/endpoint-files

Write every Reqbook endpoint as a markdown file with YAML frontmatter, an HTTP request block, and an expected response block.

## What is an endpoint file?

An endpoint file is a `.md` file that serves as both documentation and an executable HTTP request. The CLI, web preview, CI, and AI agents all read the same file there is no separate schema, generated client, or runtime artifact.

<CardGroup>
  <Card title="Browser UI" icon="desktop">
    The web preview renders the file, lets you run it, and provides runtime-only params, headers, and body overrides.
  </Card>

  <Card title="Coding agents" icon="robot">
    Agent skills use this structure to create specs safely and validate them before reporting back.
  </Card>

  <Card title="Terminal and CI" icon="terminal">
    `rqb exec` and `rqb validate` read the same markdown file for automation.
  </Card>
</CardGroup>

***

## File location and naming

Endpoint files live under `api-docs/apis/<resource>/`. The recommended filename format is `<method-lower>-<slug>.md`.

| HTTP method + path                     | Filename                                     |
| -------------------------------------- | -------------------------------------------- |
| `GET /users/:id`                       | `get-user-by-id.md`                          |
| `POST /orders`                         | `post-orders.md`                             |
| `DELETE /subscriptions/:id`            | `delete-subscription-by-id.md`               |
| `PATCH /orders/:orderId/items/:itemId` | `patch-order-by-order-id-item-by-item-id.md` |

***

## Frontmatter reference

Every endpoint file must begin with YAML frontmatter delimited by `---`.

```yaml filename="api-docs/apis/users/get-user-by-id.md" theme={null}
---
resource: users
protocol: http
method: GET
path: /users/:id
tags: [users, read]
version: 1
env: [dev, staging, prod]
auth: bearer
timeout: 5000
retry:
 attempts: 0
 backoff: fixed
---
```

| Field             | Required | Type         | Description                                                         | Default         |
| ----------------- | -------- | ------------ | ------------------------------------------------------------------- | --------------- |
| `resource`        | yes      | string       | Resource group and folder name                                      |                 |
| `protocol`        | yes      | enum         | `http`, `ws`, or `sse`. Only `http` executes in the current release |                 |
| `method`          | yes      | enum         | `GET` `POST` `PUT` `PATCH` `DELETE` `HEAD` `OPTIONS`                |                 |
| `path`            | yes      | string       | Path with `:param` for path params                                  |                 |
| `tags`            | no       | string\[]    | Searchable labels shown in web preview and reports                  | `[]`            |
| `version`         | yes      | integer      | Spec version (must be `1`)                                          |                 |
| `env`             | no       | string\[]    | Environments where this endpoint is valid. Empty = all              | `[]`            |
| `auth`            | no       | enum         | `none` / `bearer` / `basic` / `custom`                              | project default |
| `timeout`         | no       | integer (ms) | Per-request timeout in milliseconds                                 | `5000`          |
| `retry.attempts`  | no       | integer      | Retry count after failure                                           | `0`             |
| `retry.backoff`   | no       | enum         | `fixed` or `exponential`                                            | `fixed`         |
| `response.match`  | no       | enum         | `shape`, `strict`, or `schema` comparison mode                      | `shape`         |
| `response.ignore` | no       | string\[]    | Strict-mode paths to ignore, such as `body.id`                      | `[]`            |

<Note>
  Unknown frontmatter keys produce a warning and are ignored. This forward-compatible behavior means future Reqbook versions can introduce new fields without breaking existing spec files.
</Note>

***

## The Request block

`## Request` must contain exactly one `http` fenced code block. The first line is the request line; subsequent lines are headers; a blank line separates headers from the optional body.

### Request line forms

```http theme={null}
GET {{baseUrl}}/users/:id
GET /users/:id
POST https://api.example.com/users
```

<Note>
  Relative URLs are resolved against the selected environment's `baseUrl` from `api-docs/_shared/env.md`. Absolute URLs are used as-is.
</Note>

### Full request with headers and body

```http theme={null}
POST {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Content-Type: application/json
Accept: application/json

{
 "email": "{{email}}",
 "name": "{{name}}"
}
```

***

## The Expected response block

`## Expected response` must contain exactly one `http` fenced code block. Reqbook diffs the actual response against this block after every execution.

### Comparison behavior

| Part    | Comparison                                                                      |
| ------- | ------------------------------------------------------------------------------- |
| Status  | Strict equality                                                                 |
| Headers | Subset match listed headers must be present; extra response headers are allowed |
| Body    | JSON shape when both sides are valid JSON; exact string match otherwise         |

Set `response.match: strict` when the JSON/string body must match exactly:

```yaml theme={null}
response:
  match: strict
  ignore: [body.id, headers.x-request-id]
```

Set `response.match: schema` when the actual JSON body should validate against a schema:

````markdown theme={null}
## Schema

```json
{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string" },
    "email": { "type": "string" }
  }
}
```
````

### Example

```http theme={null}
HTTP/1.1 201 Created
Content-Type: application/json

{
 "id": "usr_123",
 "email": "user@example.com"
}
```

***

## Error responses (optional)

Use `## Error responses` to document representative error contracts such as validation failures, missing auth, not found, or conflict cases.

````markdown theme={null}
## Error responses

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
 "error": "not_found",
 "message": "User not found"
}
```
````

<Note>
  the current Reqbook release executes only the single `## Expected response` block. Error responses are reference examples for humans, the web preview source view, and AI agents.
</Note>

***

## The Assertions block (optional)

`## Assertions` contains structured rules that Reqbook evaluates after each execution. Results appear in `rqb_exec` output as `assertion_results`.

```markdown theme={null}
## Assertions
- status: 201
- body.id: exists
- body.email: equals "ada@example.com"
- body.role: in [admin, user]
- headers.content-type: contains application/json
- body.slug: matches ^[a-z-]+$
```

Supported operators:

| Operator   | Example                                    | Description                   |
| ---------- | ------------------------------------------ | ----------------------------- |
| `exists`   | `body.id: exists`                          | Field is present and non-null |
| `equals`   | `status: 201` or `body.name: equals "Ada"` | Exact match                   |
| `contains` | `headers.content-type: contains json`      | Substring match               |
| `in`       | `body.role: in [admin, user]`              | Value is one of a list        |
| `matches`  | `body.slug: matches ^[a-z-]+$`             | Regex match                   |

Paths follow the format `status`, `body.<field>.<nested>`, or `headers.<name>`.

***

## The Tests block (optional)

`## Tests` contains an `agent-task` fenced code block with freeform validation instructions for AI agents. Use this for edge cases that can't be expressed as structured assertions.

````markdown theme={null}
## Tests

```agent-task
- Verify duplicate email returns 409.
- Verify the response time is under 200ms under normal load.
```
````

<Note>
  Reqbook does not execute `agent-task` code. The block is read by AI agents as instructions.
</Note>

***

## Notes section (optional)

`## Notes` is free-form markdown for team context: rate limits, edge cases, links to related endpoints, and migration notes. The Reqbook parser ignores this section entirely.

***

## Complete example

````markdown filename="api-docs/apis/users/get-user-by-id.md" theme={null}
---
resource: users
protocol: http
method: GET
path: /users/:id
tags: [users, read]
version: 1
env: [dev, staging]
auth: bearer
timeout: 5000
retry:
 attempts: 0
 backoff: fixed
---

# Get user by id

Fetch a single user record by stable user identifier.

## Request

```http
GET {{baseUrl}}/users/:id
Authorization: Bearer {{authToken}}
Accept: application/json
```

## Expected response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
 "id": "usr_123",
 "name": "Ada Lovelace",
 "email": "ada@example.com"
}
```

## Tests

```agent-task
- Verify the response status is 200.
- Verify response.body.id equals the requested id.
- Verify response.body.email is a valid email address.
- Verify Authorization header is masked in all output.
```

## Notes

Use this endpoint after login to fetch the current user's profile.
````

***

## Running an endpoint

Use the UI while developing and the CLI when you need automation.

<Tabs>
  <Tab title="Web UI">
    ```bash theme={null}
    rqb serve
    ```

    Open the endpoint, fill runtime-only params or headers, click Run, and inspect the response panel. The markdown file changes only when you enter edit mode and save.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Basic execution
    rqb exec api-docs/apis/users/get-user-by-id.md

    # With environment and variable override
    rqb exec api-docs/apis/users/get-user-by-id.md --env=staging --var id=usr_456

    # Dry run print the resolved request without sending
    rqb exec api-docs/apis/users/get-user-by-id.md --dry-run
    ```
  </Tab>
</Tabs>


# API Flow Testing Pipelines
Source: https://docs.markapidown.net/essentials/pipelines

Chain markdown endpoint specs into executable API flows that capture response values and inject them into later steps.

## What is a pipeline?

A pipeline is a markdown file in `api-docs/flows/` that chains endpoint specs into sequential or parallel steps. Each step can capture values from a response and inject them as variables into later steps auth tokens, resource IDs, pagination cursors, and anything else extracted from a live response.

```text theme={null}
Create user ── capture response.body.id as userId
 ↓
Login ── inject userId, capture response.body.token as authToken
 ↓
Get profile ── inject userId and authToken
```

You can write this markdown by hand, ask an agent to create it, or design it visually in the [Web preview](/guides/web-preview) flow canvas.

***

## Pipeline frontmatter

Pipeline files use the same frontmatter delimiter as endpoint files, with a required `type: pipeline` field.

```yaml filename="api-docs/flows/user-onboarding.md" theme={null}
---
type: pipeline
name: user-onboarding
description: Create a user, log in, and pair a device.
continue-on-error: false
parallel: false
---
```

| Field               | Required | Type    | Description                                             | Default |
| ------------------- | -------- | ------- | ------------------------------------------------------- | ------- |
| `type`              | yes      | string  | Must be `pipeline`                                      |         |
| `name`              | yes      | string  | Stable pipeline name used in CLI output and reports     |         |
| `description`       | no       | string  | Human-readable summary shown in web preview and reports |         |
| `continue-on-error` | no       | boolean | Keep running after a failed step                        | `false` |
| `parallel`          | no       | boolean | Run independent steps concurrently                      | `false` |

***

## Step syntax

Steps are a numbered ordered list under `## Steps`. Each item names the step and points to an endpoint file path relative to `api-docs/`.

```markdown theme={null}
## Steps

1. **Create user** → `apis/users/create-user.md`
 - Capture: `response.body.id` as `userId`
2. **Login** → `apis/users/post-login.md`
 - Inject: `userId`
 - Capture: `response.body.token` as `authToken`
3. **Pair device** → `apis/devices/post-pair.md`
 - Inject: `authToken`, `userId`
 - Assert: `response.status == 201`
```

### Step directives

<Tabs>
  <Tab title="Capture">
    Extract a value from the response and save it as a named variable for use in all subsequent steps.

    ```markdown theme={null}
    - Capture: `response.body.id` as `userId`
    - Capture: `response.body.token` as `authToken`
    - Capture: `response.headers.x-request-id` as `requestId`
    - Capture: `response.body[0].id` as `firstItemId`
    - Capture: `response.body.items[2].sku` as `thirdSku`
    ```

    Supported capture expression patterns:

    | Pattern                          | Example                      | When to use                             |
    | -------------------------------- | ---------------------------- | --------------------------------------- |
    | `response.body.<field>`          | `response.body.id`           | Simple top-level JSON field             |
    | `response.body.<a>.<b>`          | `response.body.data.token`   | Nested JSON field                       |
    | `response.body[<n>].<field>`     | `response.body[0].id`        | Field from the nth item in a JSON array |
    | `response.body.<a>[<n>].<field>` | `response.body.items[0].sku` | Nested array item field                 |
    | `response.headers.<name>`        | `response.headers.Location`  | Response header value                   |

    Use JSONPath-style dot notation for JSON responses. Captured values have the highest variable priority and override all other sources for all later steps in the pipeline.
  </Tab>

  <Tab title="Inject">
    Declare which captured variables from previous steps this step requires.

    ```markdown theme={null}
    - Inject: `authToken`, `userId`
    ```

    Injected variables are resolved from earlier `Capture` directives. If the named capture has not happened yet because the producing step hasn't run or failed Reqbook returns an error before sending the request.
  </Tab>

  <Tab title="Assert">
    Add a pass/fail condition evaluated after the step's `## Expected response` comparison.

    ```markdown theme={null}
    - Assert: `response.status == 201`
    - Assert: `response.body.active == true`
    ```

    A failing `Assert` is treated the same as a failed expected response check. If `continue-on-error: false`, the pipeline stops at that step.
  </Tab>
</Tabs>

***

## Sequential vs parallel execution

<Tabs>
  <Tab title="Sequential (default)">
    Steps run in the order they appear in the `## Steps` list.

    * If `continue-on-error: false` (the default), the pipeline stops at the first failing step and reports which step failed.
    * Captured values are available to all steps that appear after the capturing step.
    * Use sequential pipelines whenever later steps depend on the results of earlier ones which is true for most real-world flows.
  </Tab>

  <Tab title="Parallel">
    Set `parallel: true` in the frontmatter to allow Reqbook to run independent steps concurrently.

    * A step that uses `Inject` always waits for the step that produced the required `Capture` before it starts.
    * Steps with no `Inject` dependency may run at the same time as other independent steps.
    * Use parallel pipelines for independent setup steps such as seeding multiple test fixtures before a main flow begins.

    Prefer a simple rule: if a step injects a captured value, keep it after the step that captures that value. Independent setup steps can run in parallel.
  </Tab>
</Tabs>

***

## Running a pipeline

<Tabs>
  <Tab title="Web UI">
    ```bash theme={null}
    rqb serve
    ```

    Open the flow canvas, select a flow, run it, and inspect each step result. Use the canvas when you are designing captures and connections.

    <img alt="Flow canvas with endpoint blocks and connections" />
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Run a pipeline
    rqb flow api-docs/flows/user-onboarding.md --env=dev

    # Inject additional variables at the CLI level
    rqb flow api-docs/flows/user-onboarding.md --env=staging --var email=test@example.com

    # Force sequential execution even if parallel: true is set
    rqb flow api-docs/flows/user-onboarding.md --no-parallel

    # Structured JSON output for CI
    rqb flow api-docs/flows/user-onboarding.md --output=json
    ```
  </Tab>
</Tabs>

***

## Complete example

```markdown filename="api-docs/flows/user-onboarding.md" theme={null}
---
type: pipeline
name: user-onboarding
description: Create a user, log in, and verify the profile.
continue-on-error: false
parallel: false
---

# User onboarding

End-to-end flow from account creation to profile verification.

## Steps

1. **Create user** → `apis/users/post-users.md`
 - Capture: `response.body.id` as `userId`
2. **Login** → `apis/users/post-login.md`
 - Inject: `userId`
 - Capture: `response.body.token` as `authToken`
3. **Get profile** → `apis/users/get-user-by-id.md`
 - Inject: `authToken`, `userId`
 - Assert: `response.status == 200`
```

<Tip>
  Keep pipeline files short and focused on one user journey. A pipeline that tests ten unrelated things is harder to debug when step 7 fails. Prefer one pipeline per scenario.
</Tip>


# Security
Source: https://docs.markapidown.net/essentials/security

Reqbook prevents secrets from being committed to version control. Learn about secret detection, allowed secret locations, and output masking.

## Never commit secrets

Reqbook treats endpoint, pipeline, project markdown, and `env.template.md` as safe-to-commit artifacts. Generated `env.md` files are gitignored by default because environment values often drift by machine or deployment. Secrets belong in `.env.local`, CI environment variables, or a secret manager never in env markdown, endpoint files, pipeline files, or `reqbook.md`. The parser actively enforces this before any request is sent.

***

## Secret detection

Reqbook scans `env.template.md`, `env.md`, endpoint files, pipeline files, and `reqbook.md` for common secret patterns during `rqb validate` and before every execution. If a match is found, the command exits with **code 5** no network request is made.

### Patterns that trigger exit code 5

| Pattern                | Example                            | Reason                            |
| ---------------------- | ---------------------------------- | --------------------------------- |
| `Bearer eyJ...`        | `Authorization: Bearer eyJhbGc...` | JWT-like bearer token             |
| Hex strings > 32 chars | `a3f9c2d1b4e8...` (33+ hex chars)  | Typical API key encoding          |
| Prefix `sk_`           | `sk_live_abc123`                   | Stripe-style secret key           |
| Prefix `pk_live_`      | `pk_live_abc123`                   | Stripe-style live publishable key |

### Error format

```
api-docs/_shared/env.md:12: possible secret detected
Fix: move this value to .env.local or RQB_* environment variables.
```

The error includes the file path and line number so you can find and move the offending value immediately.

***

## Allowed secret locations

| Location             | When to use                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `.env.local`         | Local development. Must be listed in `.gitignore`. Never committed.                                                      |
| `RQB_*` OS env vars  | CI/CD pipelines and shared environments. Set in your CI provider's secret store.                                         |
| Secret manager + env | `RQB_AUTH_TOKEN=$(vault read secret/api-token)` inject at runtime from HashiCorp Vault, AWS Secrets Manager, or similar. |

Generated `api-docs/_shared/env.md` files are also listed in `.gitignore` by default, while `api-docs/_shared/env.template.md` is meant to be committed. Both are still for non-secret values only.

<Tip>
  `rqb doctor` checks that `.env.local` and the generated `api-docs/_shared/env.md` path are listed in `.gitignore` and reports an error with a fix suggestion if either is missing. Run it after `rqb init` and before onboarding new contributors.
</Tip>

***

## Output masking

Reqbook masks auth header values and known secret variable names in all output surfaces: CLI console, JSON reports, JUnit XML, markdown reports, and the web preview response history.

| Input                               | Masked output                |
| ----------------------------------- | ---------------------------- |
| `Authorization: Bearer abc123`      | `Authorization: Bearer ****` |
| `Authorization: Basic dXNlcjpwYXNz` | `Authorization: Basic ****`  |
| `authToken=abc123`                  | `authToken=****`             |

Masking is applied before writing to any file, stream, or storage. Unmasked values are never written to disk by Reqbook.

***

## Production confirmation

Running against a `prod` or `production` environment requires explicit confirmation in an interactive terminal. Reqbook prompts before sending any request when a production environment is selected.

```bash theme={null}
rqb exec api-docs/apis/users/delete-user.md --env=prod
# Reqbook: You are about to execute endpoint against `prod`. Confirm? [y/N]
```

In non-interactive shells, Reqbook refuses to send production requests unless `--yes` is passed after deliberate review:

```bash theme={null}
rqb exec api-docs/apis/users/get-users.md --env=prod --yes
```

<Warning>
  Never pass `--yes` to destructive endpoints (`DELETE`, or `POST` to production data) in automated pipelines without deliberate human review of the entire workflow. Production confirmation exists to prevent accidental data loss from misconfigured CI jobs.
</Warning>

***

## Localhost and desktop writes

`rqb serve` binds to loopback by default and rejects browser writes that clearly come from a cross-site origin. This protects the common case where a random website tries to submit a write request to your local Reqbook preview server.

Reqbook desktop adds an extra session check for unsafe methods (`POST`, `PUT`, `PATCH`, and `DELETE`). The embedded server issues an HttpOnly `rqb_write_token` cookie with `SameSite=Strict` when the desktop UI loads. Desktop write endpoints require that active session, so drive-by browser writes without the desktop session are rejected.

This is not a substitute for operating-system account security. A local process running as your user can still access files that your user can access. Treat Reqbook desktop as a local developer tool and avoid opening untrusted workspaces.

Run the desktop smoke test before release candidates to verify this guard:

```bash theme={null}
cargo build --locked -p rqb-desktop
node scripts/desktop-smoke.mjs
```

***

## Anonymous active usage

Anonymous active-usage reporting in the web and desktop UI is **off by default**. Users can enable or disable it from the **Feedback and support** popup.

When enabled, Reqbook sends a heartbeat containing:

* a random identifier stored in browser-local storage,
* the surface: `desktop` or `web`,
* the Reqbook version.

Reqbook does not include workspace paths, API URLs, request or response data, headers, variables, environment values, filenames, or source content. Disabling anonymous usage stops heartbeats and removes the local identifier.

The server retains each active-presence key for five minutes. Counts therefore represent opted-in users active within the last five minutes and can be delayed by Cloudflare KV propagation.

***

## Exit codes

Every Reqbook command exits with a stable, machine-readable code. CI pipelines can branch on these codes to distinguish test failures from spec errors.

| Code | Meaning                                                            |
| ---- | ------------------------------------------------------------------ |
| `0`  | Passed                                                             |
| `1`  | Test failed response did not match expected                        |
| `2`  | Invalid spec missing field, unresolved variable, or malformed file |
| `3`  | Engine error internal Reqbook error                                |
| `4`  | Network error connection refused, timeout, or DNS failure          |
| `5`  | Secret detected a versioned file contains a possible credential    |


# Variables & environments
Source: https://docs.markapidown.net/essentials/variables

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.


# API Testing for AI Coding Agents
Source: https://docs.markapidown.net/guides/ai-agents

Use Reqbook with Claude Code, Cursor, Copilot, Codex CLI, Antigravity, OpenCode, and Windsurf to read, write, validate, and run API specs.

# Reqbook makes agents API-capable.

Agents are great at writing code but struggle with API work — they can't reliably run requests from inside the session, produce API specs that stay in sync with the code, or review results in a structured way.

Reqbook gives agents the building blocks they need: markdown files they can read and write, tools that return structured results, and playbooks that know when to call the CLI and when to use LLM reasoning.

<CardGroup>
  <Card title="Skills" icon="book-open" href="/agents/skills">
    A single markdown playbook that teaches agents the spec format, file layout, and decision trees — installed to the directory each agent reads from automatically.
  </Card>

  <Card title="Slash commands" icon="terminal" href="/agents/slash-commands">
    Two `/rqb` commands for the complex, LLM-native tasks: spec creation and enrichment, flow building, and debugging.
  </Card>

  <Card title="MCP server" icon="plug" href="/agents/mcp">
    Ten structured tools for MCP-compatible agents — exec, diagnose, flow, author, vars, search, context, history, session, and exec\_batch. Surgical context by default.
  </Card>

  <Card title="Shared source" icon="code-pull-request">
    Every agent change is a markdown file in `api-docs/`. Reviewable, diffable, committable. No hidden state.
  </Card>
</CardGroup>

***

## The division of labor

The key design decision: not every operation needs an agent. Simple, deterministic operations belong in the terminal. Agents add value when a task requires reasoning about your codebase, your domain model, or the relationships between data.

| Operation                           | Where                        | Why                                                                                                                                          |
| ----------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Init, serve, validate, exec, mock   | Terminal                     | Fast, composable, no LLM needed                                                                                                              |
| Scan routes and create specs        | `/rqb`                       | Needs to read source types and infer realistic field values                                                                                  |
| Enrich expected responses and tests | `/rqb enrich`                | Needs to understand field semantics, volatile vs stable values, domain edge cases                                                            |
| Build a workflow pipeline           | `/rqb flow`                  | Needs to reason about data dependencies between steps                                                                                        |
| Debug a failing endpoint or flow    | `/rqb-debug`                 | Multi-step diagnosis with contextual interpretation                                                                                          |
| Execute a spec (structured result)  | `rqb_exec` MCP               | Returns compact JSON — pass `verbose: true` for full payloads                                                                                |
| Diagnose a failed endpoint          | `rqb_diagnose` MCP           | Returns likely cause, next action, inspect targets, and verify commands before broad source reading                                          |
| Dry-run (resolve vars, don't send)  | `rqb_exec` + `dry_run: true` | Catches missing variables before hitting the network                                                                                         |
| Check variable readiness            | `rqb_vars` MCP               | Shows what's resolved and what's missing before exec                                                                                         |
| Search specs by method/tag/path     | `rqb_search` MCP             | Compact index — no file reading required                                                                                                     |
| Build surgical API context          | `rqb_context` MCP            | Gives the agent method/path, bounded body fields, response fields, error cases, assertions, and verify commands instead of many source files |
| Run a pipeline (structured result)  | `rqb_flow` MCP               | Returns per-step state for programmatic debugging                                                                                            |
| Author a spec (with write guard)    | `rqb_author` MCP             | Validates before writing, refuses silent overwrites                                                                                          |
| Check execution trend               | `rqb_history` MCP            | Stable/improving/regressing over recent runs                                                                                                 |
| Set session defaults                | `rqb_session` MCP            | Set env + vars once; all exec/flow calls inherit                                                                                             |
| Run multiple specs                  | `rqb_exec_batch` MCP         | Summary table — not N full JSON objects                                                                                                      |

***

## Skills — all agents

Skills are the "always-on" layer: installed to each agent's config directory, they activate automatically when API-related topics come up in the conversation. No explicit command needed.

One skill covers the full workflow:

* **rqb** — Project layout, endpoint spec format, Assertions operators, pipeline capture patterns, MCP tool reference, and routing rules for when to use each slash command.

Installed via `rqb skills install` to agent-specific locations (`.claude/skills/`, `.cursor/rules/`, `.github/instructions/`, etc.).

***

## Slash commands — Claude Code and Codex CLI

Two commands covering the tasks where LLM reasoning produces better results than a fixed script:

| Command      | What it does                                                                                          |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `/rqb`       | Creates specs, enriches expected responses, and builds/runs pipelines — routes based on your argument |
| `/rqb-debug` | Diagnoses failing endpoints and pipelines with contextual interpretation of each error                |

***

## MCP server — MCP-compatible agents

Ten tools that return structured JSON or surgical context for the agent to act on programmatically:

| Tool             | When to use                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `rqb_exec`       | Execute a spec and get a structured result with diff                                            |
| `rqb_diagnose`   | Diagnose a failed endpoint with likely cause, next action, inspect targets, and verify commands |
| `rqb_flow`       | Run a pipeline and get per-step state                                                           |
| `rqb_author`     | Write a spec with validation guard and overwrite protection                                     |
| `rqb_vars`       | Check variable resolution before exec                                                           |
| `rqb_search`     | Find specs by method, path, or tag                                                              |
| `rqb_context`    | Build surgical or schema API context for a target, flow, or changed specs                       |
| `rqb_history`    | Check execution trend over recent runs                                                          |
| `rqb_session`    | Set env and vars once for all subsequent calls                                                  |
| `rqb_exec_batch` | Run multiple specs and get a summary table                                                      |

Spec and pipeline tools resolve variables the same way as the CLI: `_shared/env.md`, `.env.local`, `RQB_*` / `MAD_*`, session vars, then explicit tool `vars`.

***

## Recommended Claude Code setup

<Steps>
  <Step title="Install skill and slash commands">
    ```bash theme={null}
    rqb skills install --agent=claude-code
    ```
  </Step>

  <Step title="Register MCP">
    ```bash theme={null}
    rqb install mcp --agent=claude-code
    ```
  </Step>

  <Step title="Open the web preview">
    ```bash theme={null}
    rqb serve
    ```

    Keep the preview open while the agent edits specs — review and run changed files immediately in the browser.
  </Step>
</Steps>

With all three active:

* The agent knows Reqbook conventions and makes good decisions without prompting (skill)
* You can trigger complex workflows precisely without writing long prompts (slash commands)
* The agent gets structured results without parsing terminal output (MCP)

For implement, review, or debug runs, ask the agent to call `rqb_context` first with `mode: "surgical"`, `brief: true`, `max_fields: 12`, `include: "variables,request,response,errors,rules,verify"`, and an explicit `intent` such as `"implement"` or `"debug"`. Use `max_fields: 6` only for a known narrow lookup. If `rqb_exec` fails, call `rqb_diagnose` before reading backend source. This keeps the loop focused on the bounded contract, literal error codes, compact business rules, likely cause, inspect targets, and verify commands.

***

## Supported agents

| Agent          | Skills | Slash commands | MCP |
| -------------- | ------ | -------------- | --- |
| Claude Code    | ✓      | ✓ (2 commands) | ✓   |
| Codex CLI      | ✓      | ✓ (2 commands) | ✓   |
| Cursor         | ✓      |                | ✓   |
| GitHub Copilot | ✓      |                | ✓   |
| Antigravity    | ✓      |                | ✓   |
| OpenCode       | ✓      |                | ✓   |
| Windsurf       | ✓      |                | ✓   |

***

## Next steps

<CardGroup>
  <Card title="Set up agent support" icon="download" href="/agents/setup">
    Install the skill, slash commands, and MCP in one command.
  </Card>

  <Card title="Slash commands reference" icon="terminal" href="/agents/slash-commands">
    Full details on /rqb and /rqb-debug.
  </Card>

  <Card title="MCP server reference" icon="plug" href="/agents/mcp">
    All 9 tools with input/output schemas and examples.
  </Card>
</CardGroup>


# Markdown API Testing in CI/CD
Source: https://docs.markapidown.net/guides/ci-cd

Run Reqbook in GitHub Actions, GitLab CI, or any CI system and gate deployments on executable markdown API specs.

## Overview

Reqbook is a single static binary with stable exit codes, making it straightforward to integrate into any CI pipeline. Common use cases include: validating specs on every pull request, running endpoint tests against staging before a deployment, and detecting secrets committed to spec files before they reach the remote.

See the [Exit codes reference](/reference/exit-codes) for a full list of codes and what triggers each one.

***

## Release automation

This repository ships a tag-based release workflow at `.github/workflows/release.yml`. Push a tag like `v0.1.0`, or run the `release` workflow manually with an existing `v*` tag, to build release binaries, package the VS Code extension, create a GitHub Release, and optionally publish to external package managers.

Package-manager publishing is gated by GitHub repository variables. Leave a variable unset or set it to `false` to keep that channel disabled while still producing GitHub Release artifacts.

### GitHub Release artifacts

The release workflow must publish these binary assets because the shell, PowerShell, and npm installers download by exact asset name:

| Platform            | Required asset                          |
| ------------------- | --------------------------------------- |
| macOS Apple Silicon | `rqb-aarch64-apple-darwin.tar.xz`       |
| macOS Intel         | `rqb-x86_64-apple-darwin.tar.xz`        |
| Linux ARM64         | `rqb-aarch64-unknown-linux-musl.tar.xz` |
| Linux x64           | `rqb-x86_64-unknown-linux-musl.tar.xz`  |
| Windows x64         | `rqb-x86_64-pc-windows-msvc.zip`        |
| VS Code             | `reqbook-vscode-<tag>.vsix`             |

Each CLI archive is published with a matching `.sha256` file. The workflow fails before and after creating the GitHub Release if any required asset is missing.

### Manual release trigger

Manual release runs are for retrying or promoting an existing tag. Create and push the tag first:

```bash theme={null}
git tag v0.1.0
git push origin v0.1.0
```

Then open GitHub Actions, choose the `release` workflow, click **Run workflow**, and enter:

| Input        | Value                                                                     |
| ------------ | ------------------------------------------------------------------------- |
| `tag`        | Existing tag, for example `v0.1.0`.                                       |
| `draft`      | `true` only when you want to review the GitHub Release before publishing. |
| `prerelease` | `true` for alpha, beta, rc, or early public builds.                       |

The workflow checks out the tag, not the current `main` branch. The tag must start with `v`.

### Required GitHub configuration

| Channel                   | GitHub Secret          | Repository Variable     | Notes                                                                                                        |
| ------------------------- | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| GitHub Releases           | none                   | none                    | Uses the built-in `GITHUB_TOKEN` with `contents: write`.                                                     |
| GHCR Docker image         | none                   | none                    | Uses the built-in `GITHUB_TOKEN` with `packages: write`; publishes `ghcr.io/<owner>/rqb:<tag>` and `latest`. |
| crates.io                 | `CARGO_REGISTRY_TOKEN` | `PUBLISH_CRATES=true`   | Token must be allowed to publish the `reqbook` crate.                                                        |
| npm                       | `NPM_TOKEN`            | `PUBLISH_NPM=true`      | Token must publish the `reqbook` package; workflow uses npm provenance.                                      |
| Visual Studio Marketplace | `VSCE_PAT`             | `PUBLISH_VSCODE=true`   | PAT must manage the `reqbook` publisher.                                                                     |
| Open VSX                  | `OVSX_PAT`             | `PUBLISH_OPEN_VSX=true` | Token must publish under the manifest publisher namespace.                                                   |
| Homebrew tap              | `HOMEBREW_TAP_TOKEN`   | `PUBLISH_HOMEBREW=true` | Reserved for a tap update job; this repository does not update a tap yet.                                    |

Optional Homebrew variables for a future tap job:

| Variable                  | Example                     | Purpose                      |
| ------------------------- | --------------------------- | ---------------------------- |
| `HOMEBREW_TAP_REPOSITORY` | `ngoclinh93qt/homebrew-tap` | Target tap repository.       |
| `HOMEBREW_FORMULA_NAME`   | `rqb`                       | Formula file/name to update. |

### Setting secrets and variables

```bash theme={null}
gh secret set CARGO_REGISTRY_TOKEN
gh secret set NPM_TOKEN
gh secret set VSCE_PAT

gh variable set PUBLISH_CRATES --body true
gh variable set PUBLISH_NPM --body true
gh variable set PUBLISH_VSCODE --body true
```

Open VSX and Homebrew can stay disabled until those channels are ready:

```bash theme={null}
gh variable set PUBLISH_OPEN_VSX --body false
gh variable set PUBLISH_HOMEBREW --body false
```

Do not store `RQB_*` runtime API credentials as release publishing secrets unless a CI test needs them. `RQB_*` values are for executing API specs, while the package-manager tokens above are for publishing artifacts.

***

## GitHub Actions

<Steps>
  <Step title="Install Reqbook">
    Add a step to download the binary. The install script detects the platform automatically.

    ```yaml theme={null}
    - name: Install Reqbook
    run: curl -fsSL https://markapidown.net/install.sh | sh
    ```
  </Step>

  <Step title="Validate specs">
    Run `rqb validate` against the entire `api-docs/` directory. Exit code `2` means a spec has a structural error; exit code `5` means a secret was committed.

    ```yaml theme={null}
    - name: Validate specs
    run: rqb validate api-docs/
    ```
  </Step>

  <Step title="Run endpoint tests">
    Pass secrets via `RQB_*` environment variables. They map automatically to camel-case variable names in your specs.

    ```yaml theme={null}
    - name: Run endpoint tests
    env:
    RQB_AUTH_TOKEN: ${{ secrets.STAGING_AUTH_TOKEN }}
    RQB_BASE_URL: https://staging.example.com
    run: |
    rqb exec api-docs/apis/health/get-health.md --env=staging
    rqb exec api-docs/apis/users/get-users.md --env=staging
    ```
  </Step>

  <Step title="Run pipelines">
    Use `rqb flow` for multi-step scenarios that chain request captures across endpoints.

    ```yaml theme={null}
    - name: Run onboarding pipeline
    env:
    RQB_AUTH_TOKEN: ${{ secrets.STAGING_AUTH_TOKEN }}
    run: rqb flow api-docs/flows/user-onboarding.md --env=staging
    ```
  </Step>
</Steps>

### Full workflow example

```yaml filename=".github/workflows/api-tests.yml" theme={null}
name: API spec tests

on:
 push:
 branches: [main]
 pull_request:
 paths:
 - 'api-docs/**'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install Reqbook
 run: curl -fsSL https://markapidown.net/install.sh | sh

 - name: Validate specs
 run: rqb validate api-docs/

 - name: Run endpoint tests
 env:
 RQB_AUTH_TOKEN: ${{ secrets.STAGING_AUTH_TOKEN }}
 RQB_BASE_URL: https://staging.example.com
 run: |
 rqb exec api-docs/apis/health/get-health.md --env=staging
 rqb exec api-docs/apis/users/get-users.md --env=staging

 - name: Run onboarding pipeline
 env:
 RQB_AUTH_TOKEN: ${{ secrets.STAGING_AUTH_TOKEN }}
 run: rqb flow api-docs/flows/user-onboarding.md --env=staging
```

***

## JUnit reports

Generate JUnit XML output for CI test reporters. Most CI systems can parse JUnit XML to display per-test results inline in pull request checks.

```bash theme={null}
rqb exec api-docs/apis/users/get-user-by-id.md \
 --env=staging \
 --output=junit > results.xml
```

Upload and publish in GitHub Actions:

```yaml theme={null}
- name: Run tests and capture output
 env:
 RQB_AUTH_TOKEN: ${{ secrets.STAGING_AUTH_TOKEN }}
 run: |
 rqb exec api-docs/apis/users/get-user-by-id.md \
 --env=staging --output=junit > results.xml

- name: Upload test results
 uses: actions/upload-artifact@v4
 with:
 name: rqb-results
 path: results.xml

- name: Publish test report
 uses: dorny/test-reporter@v1
 with:
 name: Reqbook API tests
 path: results.xml
 reporter: java-junit
```

***

## Passing secrets safely

Use `RQB_*` environment variables to inject secrets. The `RQB_` prefix is stripped and the name is converted to lower camel case before variable resolution.

```yaml theme={null}
env:
 RQB_AUTH_TOKEN: ${{ secrets.API_TOKEN }} # becomes {{authToken}}
 RQB_STRIPE_KEY: ${{ secrets.STRIPE_KEY }} # becomes {{stripeKey}}
```

<Warning>
  Do NOT use `--var authToken=$SECRET` in CI. Shell argument lists may appear in CI logs, exposing the secret value. Always use `RQB_*` environment variables to pass secrets into Reqbook.
</Warning>

***

## Exit code handling

```bash theme={null}
rqb exec api-docs/apis/users/get-user.md --env=staging
CODE=$?
case $CODE in
 0) echo "Passed" ;;
 1) echo "Response mismatch check the spec or API behavior" ; exit 1 ;;
 4) echo "Network error check VPN, service health, or BASE_URL" ; exit 1 ;;
 5) echo "Secret committed to spec file fix before merging" ; exit 1 ;;
 *) echo "Unexpected error (code $CODE)" ; exit 1 ;;
esac
```

<Tip>
  Treat exit code `4` (network error) differently from exit code `1` (response mismatch) in your CI pipeline. A network error means the staging environment may be down it does not necessarily mean your spec is wrong.
</Tip>

***

## GitLab CI

```yaml filename=".gitlab-ci.yml" theme={null}
stages:
 - validate
 - test

validate-specs:
 stage: validate
 script:
 - curl -fsSL https://markapidown.net/install.sh | sh
 - rqb validate api-docs/

api-tests:
 stage: test
 variables:
 RQB_AUTH_TOKEN: $STAGING_AUTH_TOKEN
 RQB_BASE_URL: https://staging.example.com
 script:
 - rqb exec api-docs/apis/health/get-health.md --env=staging
 - rqb flow api-docs/flows/user-onboarding.md --env=staging
 only:
 - main
 - merge_requests
```

***

## Pinning the binary version

For reproducible CI builds, pin the Reqbook version explicitly rather than always installing the latest release.

```bash theme={null}
# Install a specific version
curl -fsSL https://markapidown.net/install.sh | sh -s -- --version=v1.2.0
```

Alternatively, check the binary into your repository under `bin/rqb` and reference it directly. The binary is statically linked and has no runtime dependencies.


# Desktop smoke testing
Source: https://docs.markapidown.net/guides/desktop-smoke

Start the Tauri desktop app, verify the embedded Reqbook web/API surface, and shut it down automatically.

## Overview

Reqbook desktop is a Tauri wrapper around the same embedded preview server used by `rqb serve`. A practical first desktop test is to launch the native binary, wait for the preview server, verify the SPA and desktop-critical API endpoints, then stop the app.

This is a smoke test, not a full click-level native E2E suite. It proves the desktop binary can boot the local server, serve the web UI, issue the desktop write-session cookie, block unauthenticated writes, switch workspace, and read endpoint/flow metadata.

## Run the smoke test

Build the web UI and desktop binary first:

```bash theme={null}
cd web
npm ci
npm run build
cd ..
cargo build --locked -p rqb-desktop
```

Run the smoke script from the repository root:

```bash theme={null}
node scripts/desktop-smoke.mjs
```

The script creates a temporary local workspace, checks `GET /`, verifies the `rqb_write_token` desktop session cookie, confirms `POST /api/workspace/open` is forbidden without that session, opens the workspace with the session cookie, checks `GET /api/workspace/current`, `GET /api/index`, and `GET /api/flows`, then terminates the desktop process.

It does not call any external API and does not modify remote data.

## Configuration

| Environment variable                 | Default                    | Purpose                                                            |
| ------------------------------------ | -------------------------- | ------------------------------------------------------------------ |
| `RQB_DESKTOP_BIN`                    | `target/debug/rqb-desktop` | Path to the desktop binary to launch.                              |
| `RQB_DESKTOP_TIMEOUT_MS`             | `30000`                    | Maximum time to wait for the embedded preview server.              |
| `RQB_DESKTOP_SMOKE_KEEP_APP=1`       | unset                      | Keep the desktop app running after the test for manual inspection. |
| `RQB_DESKTOP_SMOKE_KEEP_WORKSPACE=1` | unset                      | Keep the temporary workspace for debugging.                        |

## What this catches

* Desktop binary fails to start.
* Embedded web assets are missing or stale.
* Preview server does not bind to a loopback port.
* Tauri app cannot serve the React UI.
* Desktop write-session cookie is not issued.
* Desktop write endpoints accept unauthenticated writes.
* Workspace switching is broken.
* Endpoint index or flow index cannot be read from the active workspace.

## What still needs full native E2E

Use Tauri WebDriver/`tauri-driver` or platform-specific automation for click-level tests that open the native window and verify real UI behavior:

1. Open the app and confirm the main window is nonblank.
2. Pick or create a workspace through the native folder picker path.
3. Open an endpoint page and run a request against a local fixture API.
4. Open a flow canvas, run a flow, and verify the run state is visible.
5. Save a spec/flow and assert the file changed only inside `api-docs/`.
6. Repeat against packaged release artifacts on macOS, Windows, and Linux.

Keep the smoke script in CI as the fast guard, and reserve native click-level tests for release candidates or a nightly job.


# E2E testing
Source: https://docs.markapidown.net/guides/e2e-testing

Run Reqbook end-to-end checks for the flow canvas, embedded preview server, and desktop smoke path.

## Overview

Reqbook has two practical end-to-end checks:

* Flow canvas browser E2E: launches `rqb serve`, opens the real React UI in Playwright, clicks **Run flow**, and verifies capture/inject behavior against a local fixture API.
* Desktop smoke: launches the Tauri desktop binary, verifies the embedded preview server, desktop write-session guard, workspace switching, and flow/index metadata.

Both tests create temporary local workspaces and do not modify remote data.

## Flow canvas browser E2E

Install web dependencies and build the embedded UI:

```bash theme={null}
cd web
npm ci
npm run build
cd ..
cargo build --locked
```

Install the Playwright Chromium runner once:

```bash theme={null}
cd web
npx playwright install chromium
```

Run the flow canvas E2E from the repository root:

```bash theme={null}
node scripts/flow-canvas-e2e.mjs
```

Or run it from `web/`:

```bash theme={null}
npm run e2e:flow
```

The script starts a local fixture API, creates a temporary Reqbook workspace, starts `rqb serve` on a random loopback port, opens `/flows/flows/e2e-flow.md`, clicks **Run flow**, and verifies:

* the flow canvas renders;
* exactly two flow nodes are present;
* the run summary shows `Passed`;
* every node status is `ok`;
* the fixture API received `POST /posts` followed by `GET /users/42`, proving capture/inject worked.

When the script fails, it writes debug artifacts to `target/e2e-artifacts/flow-canvas/`:

* `flow-canvas.png` screenshot;
* `flow-canvas.html` rendered DOM;
* `preview.log` server output;
* `fixture-requests.json` calls received by the fixture API;
* `error.txt` stack trace.

## CI gate

`.github/workflows/ci.yml` runs the flow canvas E2E in a dedicated `Web E2E` job on Ubuntu:

```yaml theme={null}
- name: Install Playwright Chromium
  run: cd web && npx playwright install --with-deps chromium
- name: Build web UI
  run: cd web && npm run build
- name: Build Reqbook binary
  run: cargo build --locked
- name: Run flow canvas E2E
  run: cd web && npm run e2e:flow
- name: Upload E2E failure artifacts
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: flow-canvas-e2e-artifacts
    path: target/e2e-artifacts/flow-canvas
    if-no-files-found: ignore
```

Keep this job separate from the Rust matrix so UI regressions are easy to identify and the core test matrix remains fast to scan.

## Desktop smoke

Build the desktop binary:

```bash theme={null}
cargo build --locked -p rqb-desktop
```

Run the desktop smoke:

```bash theme={null}
node scripts/desktop-smoke.mjs
```

This launches the Tauri binary, verifies the SPA loads, checks the desktop `rqb_write_token` session guard, opens a temporary workspace, reads `/api/index`, reads `/api/flows`, then terminates the app.

## What remains for release-grade native E2E

The flow canvas E2E covers the web surface. The desktop smoke covers native launch and embedded server wiring. Before a public desktop release, add native click-level tests using Tauri WebDriver or platform automation:

1. Launch the packaged desktop artifact.
2. Verify the native window is nonblank.
3. Open or create a workspace through the native folder picker path.
4. Run a flow from the native window and assert the same node/run states as the browser E2E.
5. Save a spec/flow and assert writes stay inside `api-docs/`.


# Migrating from other tools
Source: https://docs.markapidown.net/guides/migration

Import existing API specs from Postman, Insomnia, or OpenAPI into Reqbook with a single command.

## General approach

The import commands convert foreign formats into Reqbook markdown endpoint files. Structural information URLs, HTTP methods, headers, request bodies, status codes maps cleanly and is imported directly. Dynamic behavior pre-request scripts, JavaScript assertions, OAuth flows cannot be mechanically converted and is imported as `agent-task` blocks for manual review.

### Post-import checklist

<Steps>
  <Step title="Validate the imported specs">
    Run `rqb validate api-docs/` and fix any exit code `2` errors before doing anything else. Each error includes the file path, line number when known, and a suggested fix.

    ```bash theme={null}
    rqb validate api-docs/
    ```
  </Step>

  <Step title="Move secrets out of spec files">
    If `rqb validate` exits with code `5`, a secret was imported into a versioned spec file. Move the value to `.env.local` or a `RQB_*` environment variable, then re-run validation.

    ```bash theme={null}
    # .env.local
    authToken=your-token-here
    stripeKey=sk_live_...
    ```
  </Step>

  <Step title="Review agent-task blocks">
    Each `agent-task` block marks a place where the original spec had JavaScript logic, a dynamic variable, or a pre-request script that needs manual implementation. Open each flagged file and decide whether to implement it as an `## Expected response` assertion or a pipeline capture.
  </Step>

  <Step title="Verify round-trip with exec">
    Run `rqb exec` against your development environment on at least one imported endpoint to confirm the spec resolves and the response matches.

    ```bash theme={null}
    rqb exec api-docs/apis/users/get-users.md --env=dev
    ```
  </Step>

  <Step title="Regenerate the index if needed">
    If you added or renamed files manually after the import, regenerate `api-docs/README.md`.

    ```bash theme={null}
    rqb index
    ```
  </Step>
</Steps>

***

## Importing from Postman

<Tabs>
  <Tab title="Import steps">
    **1. Export from Postman**

    In Postman, open the collection and choose **File → Export → Collection v2.1 JSON**. Save the file locally.

    **2. Run the import**

    ```bash theme={null}
    rqb import postman my-collection.json
    ```

    **3. Validate**

    ```bash theme={null}
    rqb validate api-docs/
    ```

    **4. Move secrets**

    Open `.env.local` and add any token values that were flagged by validation:

    ```bash theme={null}
    # .env.local
    authToken=your-token-here
    ```

    **5. Review generated agent-task blocks**

    Each block marks a place where Postman had JavaScript logic pre-request scripts, dynamic variable generation, or complex test assertions that needs manual follow-up.

    **6. Re-run validation and exec**

    ```bash theme={null}
    rqb validate api-docs/
    rqb exec api-docs/apis/users/get-users.md --env=dev
    ```
  </Tab>

  <Tab title="Concept mapping">
    | Postman                                  | Reqbook                                                            | Notes                                                                                 |
    | ---------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
    | Collection                               | `api-docs/` project                                                | Name and description become project prose in `reqbook.md`.                            |
    | Folder                                   | Resource directory (e.g. `apis/users/`)                            | Folder names become resource directory names.                                         |
    | Request                                  | Endpoint `.md` file                                                | One request becomes one `<method>-<slug>.md` file.                                    |
    | URL + method                             | `path` frontmatter + `http` request block                          | `{{var}}` syntax is preserved.                                                        |
    | Headers                                  | Headers in `http` request block                                    | Auth headers become `{{variable}}` references.                                        |
    | JSON body                                | Body in `http` request block                                       | Formatted for readable diffs.                                                         |
    | Test scripts (simple status/body checks) | `## Expected response` block                                       | Simple assertions are converted directly.                                             |
    | Test scripts (complex JavaScript)        | `agent-task` block                                                 | JS logic is imported as manual review instructions.                                   |
    | Pre-request scripts                      | `agent-task` block                                                 | Not executable; imported as review instructions.                                      |
    | Collection variables                     | `_shared/env.template.md`, local `_shared/env.md`, or `.env.local` | Non-secret shared shape goes in the template; local values go in gitignored `env.md`. |
    | Environments                             | `_shared/env.template.md` / `_shared/env.md` sections              | Each Postman environment becomes a `## <name>` heading.                               |
    | Auth helper (bearer/basic)               | `auth:` in frontmatter or `reqbook.md`                             | Maps directly for `bearer` and `basic` types.                                         |

    **What needs manual review after import**

    | Item                                                     | Reason                                                                                                          |
    | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
    | Pre-request scripts                                      | JavaScript cannot be converted to markdown. Imported as `agent-task` instructions.                              |
    | Dynamic variables (`{{$timestamp}}`, `{{$randomEmail}}`) | No direct Reqbook equivalent. Replace with `--var` flags, `env.md` values, or pipeline captures.                |
    | Complex assertions                                       | JavaScript test logic becomes `agent-task` items. Re-implement as `## Expected response` checks where possible. |
    | Environment secrets                                      | Postman environments containing tokens must move to `.env.local` or `RQB_*` env vars.                           |
    | Chained requests                                         | Use a Reqbook pipeline to chain requests and capture response values between steps.                             |
  </Tab>
</Tabs>

***

## Importing from Insomnia

<Tabs>
  <Tab title="Import steps">
    **1. Export from Insomnia**

    In Insomnia, go to **Application → Preferences → Data → Export Data → Current Workspace**. Select **Insomnia v4** format and save the JSON file.

    **2. Run the import**

    ```bash theme={null}
    rqb import insomnia insomnia_export.json
    ```

    **3. Validate**

    ```bash theme={null}
    rqb validate api-docs/
    ```

    **4. Move secrets and review agent-task blocks**

    Move any flagged secret values to `.env.local`. Review `agent-task` blocks for plugin logic and template tags that need manual implementation.
  </Tab>

  <Tab title="Concept mapping">
    | Insomnia                           | Reqbook                                                            | Notes                                                                                                             |
    | ---------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
    | Workspace                          | `api-docs/` project                                                | Workspace name becomes the project name.                                                                          |
    | Request group (folder)             | Resource directory                                                 | Group names become resource directory names.                                                                      |
    | Request                            | Endpoint `.md` file                                                | One request becomes one `<method>-<slug>.md` file.                                                                |
    | URL                                | `path` frontmatter + `http` request block                          | Template variables (`{{ var }}`) convert to `{{var}}` syntax.                                                     |
    | Method                             | `method` frontmatter + request line                                |                                                                                                                   |
    | Headers                            | Headers in `http` request block                                    |                                                                                                                   |
    | Body                               | Body in `http` request block                                       |                                                                                                                   |
    | Environment (base + sub)           | `_shared/env.template.md` / `_shared/env.md` sections              | Each becomes a `## <name>` heading.                                                                               |
    | Environment variables              | `_shared/env.template.md`, local `_shared/env.md`, or `.env.local` | Non-secret shared shape goes in the template. Local values go to gitignored `env.md`. Secrets go to `.env.local`. |
    | Test results                       | `## Expected response` block                                       | Simple status checks are preserved.                                                                               |
    | Plugins / pre/post-request scripts | `agent-task` block                                                 | Imported as manual review instructions.                                                                           |

    **What needs manual review after import**

    | Item                                      | Reason                                                                                                               |
    | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
    | Template tags (`{% now %}`, `{% uuid %}`) | Insomnia-specific tags have no direct Reqbook equivalent. Replace with pipeline captures or `--var` flags.           |
    | Plugin-based pre/post-request logic       | Imported as `agent-task` instructions.                                                                               |
    | Environment secrets                       | Must move to `.env.local` or `RQB_*` env vars.                                                                       |
    | OAuth 2.0 flows                           | Multi-step auth flows should become a Reqbook pipeline that captures the token and injects it into subsequent steps. |
  </Tab>
</Tabs>

***

## Importing from OpenAPI

```bash theme={null}
rqb import openapi openapi.yaml
# or
rqb import openapi openapi.json
```

<Tabs>
  <Tab title="Import steps">
    **1. Validate your OpenAPI file**

    Ensure the spec is valid OpenAPI 3.x YAML or JSON before importing. Use a linter such as `spectral lint` if needed.

    **2. Run the import**

    ```bash theme={null}
    rqb import openapi openapi.yaml
    ```

    **3. Validate the result**

    ```bash theme={null}
    rqb validate api-docs/
    ```

    **4. Add additional environments**

    If your OpenAPI spec defines multiple `servers`, only the first is imported as the `dev` environment. Add the others manually to `_shared/env.md`:

    ```yaml theme={null}
    ## staging
    baseUrl: https://staging.example.com

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

    **5. Review agent-task blocks**

    OpenAPI specs often have JSON Schema validation constraints that become `agent-task` review items. Decide whether to implement them as `## Expected response` body assertions or to leave them as documentation.
  </Tab>

  <Tab title="Concept mapping">
    | OpenAPI                          | Reqbook                                   | Notes                                                                                                              |
    | -------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
    | `info.title`                     | `name` in `reqbook.md`                    |                                                                                                                    |
    | `servers[0].url`                 | `baseUrl` in `_shared/env.md` dev section | Additional servers need manual env sections.                                                                       |
    | `paths.<path>.<method>`          | Endpoint `.md` file                       | One operation becomes one `<method>-<slug>.md` file.                                                               |
    | `operationId`                    | File slug                                 | Used to generate the filename. Falls back to method + path.                                                        |
    | `tags[0]`                        | Resource directory                        | The first tag determines the directory name.                                                                       |
    | `parameters` (path/query/header) | Variables in `http` request block         | Path params use `:param` syntax.                                                                                   |
    | `requestBody`                    | Body in `http` request block              | First example or schema stub is used.                                                                              |
    | `responses.<code>`               | `## Expected response` block              | Only the first documented response code is imported.                                                               |
    | `security bearerAuth`            | `auth: bearer` in frontmatter             | `basicAuth` maps to `auth: basic`.                                                                                 |
    | `components/schemas`             | `## Schema` or `## Notes`                 | Response schemas can be used with `response.match: schema`; broader component reuse may still need manual cleanup. |

    **What needs manual review after import**

    | Item                       | Reason                                                                                                                                |
    | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
    | Multiple response codes    | Only the first documented response is imported. Add others manually in `## Notes`.                                                    |
    | JSON Schema validation     | Use `response.match: schema` with a `## Schema` block for executable response-body validation. Review complex `$ref` graphs manually. |
    | OAuth 2.0 / OpenID Connect | Model as a Reqbook pipeline that captures the token and injects it into subsequent steps.                                             |
    | Multiple servers           | Only the first server is imported as `dev`. Add remaining servers as additional `env.md` sections.                                    |
    | Callbacks and webhooks     | Must be documented manually. `protocol: ws` and `protocol: sse` are reserved for future use.                                          |
  </Tab>
</Tabs>


# Agent API Workflow
Source: https://docs.markapidown.net/guides/vibe-coding

Use Reqbook as the API memory and execution layer for coding agents that need runnable specs, flows, and bounded context.

# Make your coding agent API-aware.

Reqbook is strongest when a coding agent is part of your API workflow. The agent can read source routes, create markdown specs, validate them, run requests, and build flows. You still keep control because every result is saved as reviewable markdown in the repo.

<Note>
  If you only want terminal commands, use the [CLI reference](/reference/cli). If you want to inspect and run specs visually, use the [Web preview](/guides/web-preview). This guide focuses on agent-first development.
</Note>

***

## Set up the project

<Steps>
  <Step title="Initialise Reqbook">
    ```bash theme={null}
    rqb init --name=my-api --dev-url=http://localhost:8080 --yes
    ```

    This creates `api-docs/`, an example endpoint, `_shared/env.template.md`, local `_shared/env.md`, and `.gitignore` protection for `.env.local` plus local `_shared/env.md`.
  </Step>

  <Step title="Install agent skills">
    ```bash theme={null}
    rqb skills install
    ```

    Or target one agent:

    ```bash theme={null}
    rqb skills install --agent=claude-code
    rqb skills install --agent=cursor
    rqb skills install --agent=copilot
    ```
  </Step>

  <Step title="Register MCP for your agent">
    MCP mode gives the agent structured Reqbook tools instead of asking it to parse terminal output.

    ```bash theme={null}
    rqb install mcp --agent=claude-code
    rqb install mcp --agent=codex-cli
    ```
  </Step>

  <Step title="Open the UI beside your agent">
    ```bash theme={null}
    rqb serve
    ```

    Keep the browser preview open while your agent edits files. The UI reads the same markdown files and updates as they change.
  </Step>
</Steps>

***

## Prompts that work well

Use prompts that describe the API intent and let the Reqbook skill choose the correct operation.

<CardGroup>
  <Card title="Create one endpoint" icon="file-pen">
    ```text theme={null}
    Add a Reqbook spec for GET /users/:userId. Use bearer auth and make userId a path param.
    ```
  </Card>

  <Card title="Scan existing routes" icon="magnifying-glass">
    ```text theme={null}
    Scan this project for API routes and add missing Reqbook specs. Do not overwrite existing specs.
    ```
  </Card>

  <Card title="Run and debug" icon="play">
    ```text theme={null}
    Test the get user endpoint in dev. If variables are missing, tell me exactly where to define them.
    ```
  </Card>

  <Card title="Create a workflow" icon="diagram-project">
    ```text theme={null}
    Build a signup flow: create user, login, capture token, then fetch profile with the captured token.
    ```
  </Card>
</CardGroup>

***

## Agent responsibilities

When the skills are installed, the agent should follow this pattern:

| Task                       | Reqbook surface         | Expected behavior                                                                                   |
| -------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| Add an endpoint            | `rqb_author` MCP tool   | Create `api-docs/apis/<resource>/<method>-<slug>.md`, validate it, regenerate the index.            |
| Run one endpoint           | `rqb_exec` MCP tool     | Resolve env variables, path params, and runtime vars; report status, duration, and diff.            |
| Diagnose a failed endpoint | `rqb_diagnose` MCP tool | Return likely cause, next action, inspect targets, and verify commands before broad source reading. |
| Create a workflow          | `/rqb flow` command     | Save a markdown flow under `api-docs/flows/`.                                                       |
| Run a workflow             | `rqb_flow` MCP tool     | Execute steps, capture values, inject them downstream, and report the first failure.                |
| Review in browser          | `rqb serve`             | Use the UI for request tweaks, response inspection, and visual flow editing.                        |

***

## What stays under your control

* Agents should not overwrite existing specs unless you explicitly ask for that exact file to be replaced.
* Secrets belong in `.env.local` or `RQB_*`, not in markdown committed to the repo.
* The browser request builder can override params, headers, and body for one run without changing the markdown file.
* Persistent changes happen only when the agent edits markdown or you use the UI edit mode and save.
* `rqb validate api-docs/` is the final safety check before commit.

***

## Example session

```text theme={null}
You: Scan this repo and add missing API specs.

Agent: Uses Reqbook project scanner.
Agent: Creates api-docs/apis/orders/post-orders.md.
Agent: Runs rqb validate api-docs/.
Agent: Runs rqb index.

You: Create a checkout flow from the order endpoints.

Agent: Reads existing specs.
Agent: Creates api-docs/flows/checkout.md.
Agent: Captures response.body.id as orderId.
Agent: Validates the flow.

You: Run it in dev.

Agent: Runs rqb flow api-docs/flows/checkout.md --env=dev.
Agent: Reports each step, captured values, and the first mismatch.
```

<Tip>
  Keep `rqb serve` open during this loop. It gives you a visual review layer while the agent edits markdown behind the scenes.
</Tip>


# VS Code extension
Source: https://docs.markapidown.net/guides/vscode-extension

Preview, validate, run, and inspect Reqbook specs from VS Code.

# VS Code extension

The Reqbook VS Code extension is the in-editor bridge for teams that write API specs directly in a Reqbook collection. It keeps the workflow narrow: edit markdown in VS Code, call the `rqb` binary for validation and execution, and keep the browser UI available for larger visual workflows.

<Note>
  The extension requires the `rqb` binary. It auto-detects `rqb` from `RQB_PATH`, workspace build outputs, Cargo, Homebrew, and PATH. Use `reqbook.rqbPath` only when you need an explicit override.
</Note>

***

## Demo

<video>
  <source type="video/mp4" />
</video>

The demo shows a runnable endpoint in VS Code with inline CodeLens actions, direct execution through `rqb`, and the structured result panel.

<Note>
  To publish the optimized Cloudflare Stream version, set `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, then run `node scripts/upload-cloudflare-stream-video.mjs docs/assets/vscode-demo.mp4 "Reqbook VS Code demo"`. Stream returns a player iframe, not an MP4 source, so replace the `<video>` block above with the returned `mdx_embed` after the upload is ready.
</Note>

***

## Commands

Open an endpoint or flow markdown file, then run these commands from the Command Palette or editor context menu:

| Command                          | What it does                                                                                                               |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Reqbook: Preview Endpoint`      | Opens a VS Code webview preview of the current markdown spec with action buttons.                                          |
| `Reqbook: Run Spec`              | Saves the current file, runs `rqb exec` for endpoints or `rqb flow` for flows/pipelines, and shows a compact result panel. |
| `Reqbook: Validate Current File` | Saves the current file, runs `rqb validate <file>`, and shows validation output.                                           |
| `Reqbook: Show Agent Context`    | Runs `rqb context <file>` and shows the surgical context that coding agents should use.                                    |

The result panel shows endpoint status, duration, request URL, response diff, structured assertions, flow steps, captures, and raw command output.

***

## Auto-detect run buttons

The extension detects runnable Reqbook files and shows Run controls only for those files:

* The collection root is the nearest parent directory with `reqbook.md` or `mad.md`; it does not need to be named `api-docs`.
* Endpoint specs inside that collection with `method:` and `path:` frontmatter show `Run Endpoint`.
* Flow and pipeline specs under `<collection>/flows/` or `<collection>/pipelines/` show `Run Flow`.
* Non-runnable collection docs such as `<collection>/reqbook.md`, `<collection>/mad.md`, `README.md`, and `_shared/env.md` do not show Run controls.

Runnable files get both an inline CodeLens button at the top of the editor and a Run button in the editor title bar.

***

## Variable autocomplete

The extension suggests variables while editing `{{variable}}` templates and path params. Suggestions are collected from:

* `<collection>/_shared/env.md`
* `.env.local`
* `:pathParam` values in the current spec
* `Capture: ... as <name>` directives in `<collection>/flows/` and `<collection>/pipelines/`

This keeps authoring fast without adding a separate project config format.

***

## Settings

| Setting               | Default | Description                                                                                                             |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `reqbook.rqbPath`     | `rqb`   | Optional path to the `rqb` binary. The extension auto-detects common local and installed paths when this remains `rqb`. |
| `reqbook.env`         | `dev`   | Environment used for `Run Endpoint` and `Show Agent Context`.                                                           |
| `reqbook.apiDocsRoot` | empty   | Optional collection root override. Relative paths resolve from the workspace root.                                      |
| `reqbook.resultPanel` | `true`  | Show command output in the Reqbook result panel. If disabled, output goes to the output channel.                        |

Example workspace setting:

```json theme={null}
{
  "reqbook.rqbPath": "/Users/you/.cargo/bin/rqb",
  "reqbook.env": "dev"
}
```

***

## Development install

The extension source lives in `packages/vscode/`.

```bash theme={null}
cd packages/vscode
npm ci
npm test
npm run check
npm run package -- --out /tmp/reqbook-vscode-0.1.4.vsix
```

Install a pre-release VSIX with:

```bash theme={null}
code --install-extension /tmp/reqbook-vscode-0.1.4.vsix
```

For local development, open the repository in VS Code, open `packages/vscode/extension.js`, and run the extension in an Extension Development Host. The extension has no runtime npm dependencies.

***

## Release checklist

Before publishing to the Visual Studio Marketplace:

* Confirm the Marketplace publisher matches the `publisher` field in `packages/vscode/package.json`.
* Run `npm ci`, `npm test`, `npm run check`, and `npm run package` from `packages/vscode/`.
* Install the generated VSIX and smoke test preview, run, validate, context, variable autocomplete, and a missing-`rqb` failure.
* Confirm the released `rqb` binary version matches the extension docs.
* Keep generated `.vsix` files and Marketplace tokens out of git.

***

## When to use each surface

| Surface                | Best for                                                                   |
| ---------------------- | -------------------------------------------------------------------------- |
| VS Code extension      | Fast edit-run-validate loops while authoring markdown specs.               |
| `rqb serve` browser UI | Rich request editing, response inspection, flow canvas, and visual review. |
| `rqb-cli`              | CI, scripts, PR checks, imports, exports, and automation.                  |
| MCP / agent skills     | Let coding agents discover, author, execute, and debug API specs.          |

The same markdown files power every surface.


# Browser API Runner
Source: https://docs.markapidown.net/guides/web-preview

Use the Reqbook browser UI to browse, execute, edit, import, and connect markdown API specs in a local workspace.

# Browser UI for markdown API specs.

`rqb serve` starts a local browser workspace over the markdown files in `api-docs/`. It is designed to sit beside your editor and coding agent: agents can write files, you can inspect and run them visually, and everything stays in sync through the filesystem.

```bash theme={null}
rqb serve
# Preview: http://127.0.0.1:8080
```

<img alt="rqb-ui endpoint browser" />

<Note>
  Reqbook binds to `127.0.0.1` by default. Use `--host=0.0.0.0` only when you intentionally want to share the preview on your local network.
</Note>

***

## Why use the UI?

The CLI is great for CI and automation. The UI is better when you are actively designing, debugging, or reviewing specs.

<CardGroup>
  <Card title="Runtime request builder" icon="sliders">
    Add path params, variables, headers, and body overrides for one execution without changing the markdown file.
  </Card>

  <Card title="Response inspection" icon="magnifying-glass">
    Inspect formatted response body, headers, raw output, duration, and diff against the expected response.
  </Card>

  <Card title="Markdown edit mode" icon="file-pen">
    Switch to edit mode when you want to persist a spec change. Save writes the markdown file back to disk.
  </Card>

  <Card title="Flow canvas" icon="diagram-project">
    Design workflows visually by connecting endpoint blocks, captures, and injections. The result is saved as `api-docs/flows/*.md`.
  </Card>

  <Card title="cURL import" icon="terminal">
    Paste a cURL command from DevTools and generate a Reqbook endpoint spec.
  </Card>

  <Card title="Agent review loop" icon="robot">
    Keep the UI open while your agent edits specs. Review and run the changed files immediately.
  </Card>
</CardGroup>

***

<img alt="Endpoint runner — request builder and response viewer" />

After clicking **Send**, the response panel shows status, duration, diff against the expected response, body, and headers.

<img alt="Endpoint response — Passed 200 with diff view" />

## Request tweaks do not rewrite markdown

The request builder is intentionally temporary:

| UI control         | Used for current run | Written to markdown automatically |
| ------------------ | -------------------: | --------------------------------: |
| Path params        |                  yes |                                no |
| Variable overrides |                  yes |                                no |
| Extra headers      |                  yes |                                no |
| Body override      |                  yes |                                no |
| Edit mode save     |                  yes |                               yes |

This lets you try an ID, token, header, or body shape without accidentally modifying the canonical spec. When a runtime tweak should become permanent, switch to edit mode and save the markdown.

***

## Flow canvas

<img alt="Flow canvas with connected endpoint blocks" />

The flow canvas is the UI surface for `api-docs/flows/`.

Use it to:

* add endpoint nodes,
* connect one endpoint result to another endpoint input,
* capture values such as `response.body.id` or `response.body[0].id`,
* inject captured variables into downstream nodes,
* save the workflow as markdown.

The saved flow can then be run from either surface:

```bash theme={null}
rqb flow api-docs/flows/checkout.md --env=dev
```

or from the browser UI with the Run flow action.

***

## Environment and variables

The UI reads `api-docs/_shared/env.md` for local non-secret environment values. If that file is missing, the Variables drawer starts from `api-docs/_shared/env.template.md` and lets you create the local file:

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

```yaml
baseUrl: https://jsonplaceholder.typicode.com
postId: 1
```
````

Use `.env.local` or `RQB_*` for secrets. Reqbook masks auth values in UI responses and reports.

***

## Common workflow with an agent

<Steps>
  <Step title="Agent creates or updates specs">
    Ask your agent to add endpoint specs or scan the project for missing routes.
  </Step>

  <Step title="UI refreshes from disk">
    Open `rqb serve` and inspect the new files in the sidebar.
  </Step>

  <Step title="Run with temporary inputs">
    Fill runtime-only params and headers, click Run, and inspect the response.
  </Step>

  <Step title="Persist only intentional changes">
    If the spec needs correction, use edit mode or ask the agent to update the markdown and validate again.
  </Step>
</Steps>

***

## Mock mode

Start the preview with `--mock` when the real backend is unavailable during frontend development, on an airplane, or before the API exists:

```bash theme={null}
rqb serve --mock
```

In mock mode:

* Clicking **Send** returns the `## Expected response` recorded in the spec file. No HTTP request is made.
* A purple **MOCK** badge appears on every response card so you always know you are looking at recorded data, not a live response.
* A **mock** chip appears in the top navigation bar while mock mode is active.
* Path parameters such as `/users/:id` are matched automatically any ID value returns the same recorded body.

Mock mode reads the same `## Expected response` blocks that `rqb mock` uses on the standalone mock server. Both features share the same source of truth.

<Tip>
  If your specs have empty `## Expected response` blocks (stub `{}`), run `/rqb enrich` to enrich them with real field names, or execute against a live server once and copy the response body into the spec manually.
</Tip>

### Mock mode vs standalone mock server

|                    | `rqb serve --mock`                | `rqb mock`                             |
| ------------------ | --------------------------------- | -------------------------------------- |
| Use case           | Interactive review in the browser | Frontend app points to a mock base URL |
| Backend traffic    | None                              | None                                   |
| Port               | Same as the preview (8080)        | Separate port (4001 by default)        |
| Latency simulation | No                                | Yes (`--latency`)                      |

***

## Server flags

```bash theme={null}
rqb serve --port=9000 --env=staging
rqb serve --mock
rqb serve /path/to/other-project
```

| Flag     | Description                                                     |
| -------- | --------------------------------------------------------------- |
| `--port` | Local preview port.                                             |
| `--host` | Host to bind. Defaults to `127.0.0.1`.                          |
| `--env`  | Environment selected from `_shared/env.md`.                     |
| `--mock` | Return recorded responses instead of making real HTTP requests. |
| `[path]` | Project directory containing `api-docs/`.                       |


# Install Reqbook CLI and Desktop
Source: https://docs.markapidown.net/installation

Install Reqbook on macOS, Linux, or Windows using the shell installer, Cargo, npm, Docker, Homebrew, or MSI.

## Requirements

Reqbook ships as a single static binary with no runtime dependencies: no Node, no Python, no JVM required.

| Install method  | Requirement                        |
| --------------- | ---------------------------------- |
| Shell installer | macOS or Linux, `curl`, `sh`       |
| Cargo           | Rust 1.75+                         |
| Homebrew        | macOS, [Homebrew](https://brew.sh) |
| npm             | Node.js 18+                        |
| Docker          | Docker Engine                      |
| Windows MSI     | Windows 10 / Server 2019 or later  |

***

## Install methods

<Tabs>
  <Tab title="Shell installer">
    Recommended for most macOS and Linux users. The installer fetches the latest prebuilt binary and places it in `~/.local/bin`.

    ```bash theme={null}
    curl -fsSL https://markapidown.net/install.sh | sh
    ```

    If `~/.local/bin` is not on your `PATH`, the installer prints the exact line to add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).

    <Note>
      The shell installer script is open-source and auditable at [github.com/ngoclinh93qt/ReqBook](https://github.com/ngoclinh93qt/ReqBook/blob/main/scripts/install.sh).
    </Note>
  </Tab>

  <Tab title="Cargo">
    Install directly from [crates.io](https://crates.io/crates/reqbook). This builds Reqbook from source and places the binary in `~/.cargo/bin`.

    ```bash theme={null}
    cargo install reqbook
    ```

    Requires Rust 1.75 or later. Upgrade your toolchain with `rustup update stable` if needed.
  </Tab>

  <Tab title="Homebrew">
    Install via the official Reqbook tap on macOS (or Linux with Homebrew):

    ```bash theme={null}
    brew install reqbook/tap/rqb
    ```

    Homebrew manages upgrades via `brew upgrade rqb`. No separate tap add step is required; the formula URL handles it.
  </Tab>

  <Tab title="npm">
    Install via npm for Node.js projects. This bundles a prebuilt binary for macOS, Linux, and Windows; no Rust toolchain needed.

    ```bash theme={null}
    npm install -g reqbook
    ```

    The npm package is a thin wrapper around the native binary. You can also pin it as a `devDependency` to lock the version per project:

    ```bash theme={null}
    npm install --save-dev reqbook
    npx rqb validate api-docs/
    ```
  </Tab>

  <Tab title="Docker">
    Use the official image from GitHub Container Registry. Mount your project directory at `/work`:

    ```bash theme={null}
    docker pull ghcr.io/ngoclinh93qt/rqb:latest
    docker run --rm -v "$(pwd)":/work -w /work \
    ghcr.io/ngoclinh93qt/rqb:latest validate api-docs/
    ```

    Replace `validate api-docs/` with any `rqb` subcommand. To execute endpoints against a local server, use `--network=host` or Docker Compose.

    <Tip>
      Pin a specific version in CI to avoid unexpected behavior from `latest`: use a tag like `ghcr.io/ngoclinh93qt/rqb:0.2.5`.
    </Tip>
  </Tab>

  <Tab title="Windows (MSI)">
    Download the `.msi` installer from the [releases page](https://github.com/ngoclinh93qt/ReqBook/releases). Run the installer and `rqb` is added to your system PATH automatically; no manual PATH edits needed.

    <Note>
      Windows support is available from the current Reqbook release. The MSI installer targets Windows 10 and Windows Server 2019 or later.
    </Note>
  </Tab>
</Tabs>

***

## Verify the installation

After installing, confirm the binary is on your PATH and run the built-in diagnostics:

```bash theme={null}
rqb version
# 0.2.5

rqb doctor
```

<Note>
  `rqb doctor` runs a series of checks: it verifies that `api-docs/` exists, that local environment files are listed in `.gitignore`, that all specs in the project are valid, and that any installed AI agent skills match the current binary version.
</Note>

***

## VS Code extension

The VS Code extension uses the same `rqb` binary. Install Reqbook first, then configure the extension if VS Code cannot find `rqb` on its process `PATH`.

```json theme={null}
{
  "reqbook.rqbPath": "/absolute/path/to/rqb",
  "reqbook.env": "dev"
}
```

See the [VS Code extension guide](/guides/vscode-extension) for commands, variable autocomplete, and result panel behavior.

***

## Troubleshooting

### Shell installer returns 404

The shell installer downloads a platform-specific binary from the latest GitHub Release. For example, Apple Silicon macOS expects an asset named `rqb-aarch64-apple-darwin.tar.xz`.

If the install command fails with `curl: (56) The requested URL returned error: 404`, the latest release is missing that binary asset. Re-run the release workflow for the current tag or pin a release tag that has assets:

```bash theme={null}
curl -fsSL https://markapidown.net/install.sh | sh -s -- --version=vX.Y.Z
```

This is unrelated to starting an API server; it happens before `rqb` is installed.

***

## Shell completions

Generate and install completions for your shell so you get tab-completion for subcommands and flags:

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    rqb completion bash >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    rqb completion zsh > "${fpath[1]}/_rqb"
    # Restart your shell or run: exec zsh
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    rqb completion fish > ~/.config/fish/completions/rqb.fish
    ```
  </Tab>
</Tabs>

***

## Upgrading

<Tabs>
  <Tab title="Shell installer">
    Re-run the installer it replaces the existing binary in place:

    ```bash theme={null}
    curl -fsSL https://markapidown.net/install.sh | sh
    ```
  </Tab>

  <Tab title="Cargo">
    ```bash theme={null}
    cargo install reqbook --force
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew upgrade rqb
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g reqbook
    ```
  </Tab>
</Tabs>

<Tip>
  After upgrading, run `rqb doctor --fix` to automatically update any installed AI agent skills (Claude Code, Cursor, Copilot) to the new version. Stale skill files can cause agents to call deprecated flags.
</Tip>


# Executable Markdown API Docs
Source: https://docs.markapidown.net/introduction

Reqbook stores API documentation as runnable markdown specs for developers, CI, local UI, and AI coding agents.

# Agent-native across 6 coding tools, visual debugger, fast CLI, your entire API lives in plain markdown.

Reqbook stores API work as plain markdown files. Send ad-hoc requests from the terminal or browser. Design API contracts. Validate them in CI. Your coding agent can read, write, and run everything. No hosted workspace, no proprietary format just files in your repo.

<CardGroup>
  <Card title="rqb-cli" icon="terminal" href="/cli/overview">
    Terminal interface: `rqb request`, `rqb exec`, `rqb flow`, and more.
  </Card>

  <Card title="rqb-ui" icon="desktop" href="/ui/overview">
    Browser interface: New Request panel, endpoint runner, flow canvas.
  </Card>

  <Card title="Agent integration" icon="robot" href="/guides/ai-agents">
    MCP tools and skills for Claude Code, Cursor, Copilot, and others.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install Reqbook, create a project, and execute your first request in under five minutes.
  </Card>

  <Card title="Agent integration" icon="robot" href="/guides/ai-agents">
    Install skills and MCP tools so Claude Code, Cursor, Copilot, and others can work with specs directly.
  </Card>

  <Card title="Web preview" icon="desktop" href="/guides/web-preview">
    Browse specs, tune parameters, send requests, inspect responses, and edit markdown all in the browser.
  </Card>

  <Card title="Vibe coding guide" icon="wand-magic-sparkles" href="/guides/vibe-coding">
    Use Reqbook in your agent loop: document routes, run endpoints, build flows, and review changes.
  </Card>
</CardGroup>

***

## How it works

Every API operation lives in a markdown file:

```
api-docs/
├── reqbook.md # Project config and defaults
├── _shared/
│ ├── env.template.md # Shared environment template
│ └── env.md # Local environment values
├── apis/
│ ├── users/
│ │ ├── get-user-by-id.md
│ │ └── create-user.md
│ └── orders/
│ └── post-orders.md
└── flows/
 └── checkout.md # Multi-step pipeline
```

The same files are used by:

| Surface      | What it does                                                                              |
| ------------ | ----------------------------------------------------------------------------------------- |
| `rqb exec`   | Sends the HTTP request and diffs the response                                             |
| `rqb serve`  | Renders a browser UI for interactive testing                                              |
| `rqb mock`   | Serves recorded responses without a live backend                                          |
| `rqb flow`   | Runs a pipeline, captures values, injects them into later steps                           |
| Agent skills | Teaches agents the format, file layout, and how to validate changes                       |
| MCP tools    | Lets compatible agents search, execute, author, and summarize specs without shell parsing |
| CI           | Validates all specs and exits non-zero on any failure                                     |

***

## The vibe coding loop

<Steps>
  <Step title="Agent creates or updates specs">
    Ask your agent to document a route, import from curl, or scan the project for missing specs:

    ```text theme={null}
    Scan this project for API routes and add missing Reqbook specs.
    ```

    ```text theme={null}
    Document POST /orders and make it runnable in Reqbook.
    ```
  </Step>

  <Step title="Review in the browser UI">
    ```bash theme={null}
    rqb serve
    # → Preview: http://127.0.0.1:8080
    ```

    Inspect the generated markdown, adjust runtime params, run the request, and compare the response against the expected value.
  </Step>

  <Step title="Build flows">
    Ask the agent to connect specs into a pipeline:

    ```text theme={null}
    Create a checkout flow: create customer → create order, capture orderId → fetch order.
    ```

    The flow is saved as `api-docs/flows/checkout.md` and runnable from both CLI and browser.
  </Step>

  <Step title="Commit reviewable markdown">
    ```bash theme={null}
    rqb validate api-docs/
    ```

    Specs are ordinary markdown. Every change is reviewable, diffable, and revertable in your PR.
  </Step>
</Steps>

***

## Without Reqbook, agents work blind

When an agent needs to test an API endpoint without Reqbook, it reads router files, middleware, env config, constructs a `curl` command, parses raw stdout, and throws everything away. The next session starts from zero.

| Task                         | Without Reqbook                                                   | With Reqbook                                                              |
| ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Test one endpoint            | Read source files, construct curl, parse stdout                   | `rqb_exec spec.md` structured result                                      |
| Diagnose an endpoint failure | Search logs and handlers manually                                 | `rqb_diagnose spec.md` likely cause, inspect targets, and verify commands |
| Debug multi-step flow        | Write a temp script, manually chain requests, no trace on failure | `rqb_flow pipeline.md` per-step state, captured values                    |
| Detect a regression          | Only after a bug report                                           | `rqb check` or `rqb validate` in CI fails before merge                    |
| Agent discovers APIs         | Scan broad source and docs manually                               | `rqb context` and `rqb_search` return bounded API context                 |
| Share tests with team        | "Send me the curl"                                                | Commit markdown, review in PR                                             |
| Mock backend                 | Run live server or hardcode                                       | `rqb mock` from recorded responses                                        |

The setup cost is five minutes (`rqb init`). After that, API docs, tests, CI checks, mock responses, and agent context come from the same reviewable markdown files.

***

## Why not Postman, Insomnia, Bruno, or Hurl?

<CardGroup>
  <Card title="Agents need file-based tools" icon="robot">
    GUI tools store state in app databases or proprietary formats. Agents cannot read or write them reliably. Reqbook specs are plain markdown any agent can read, create, and edit them.
  </Card>

  <Card title="Everything stays in the repo" icon="code-branch">
    Specs live in `api-docs/` alongside your code. Every API change goes through code review. No "export to share" step, no drift between the tool and the repo.
  </Card>

  <Card title="One source, every surface" icon="layer-group">
    The same file runs in the CLI, renders in the browser UI, serves the mock server, and validates in CI. You describe the API once.
  </Card>

  <Card title="No account, no cloud" icon="hard-drive">
    A single Rust binary. No signup, no workspace ID, no internet dependency at runtime. Works offline.
  </Card>
</CardGroup>

Postman is the right choice when a team wants a broad hosted API platform with collaboration, monitoring, and governance. Bruno is the right choice when a team primarily wants a mature Git-native desktop API client. Hurl is the right choice when a team wants a fast plain-text HTTP test runner in CI. Reqbook is for teams that want API docs in the repo to be readable, executable, reviewable in PRs, runnable in CI, and directly usable by coding agents.

***

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run a real API request in five minutes.
  </Card>

  <Card title="Set up agents" icon="robot" href="/agents/setup">
    Install skills, slash commands, and MCP for supported coding agents.
  </Card>

  <Card title="Web preview" icon="desktop" href="/guides/web-preview">
    Start `rqb serve` and explore the browser UI.
  </Card>
</CardGroup>


# Reqbook API Testing Quickstart
Source: https://docs.markapidown.net/quickstart

Install Reqbook, create markdown API specs, open the browser UI, and run an agent-friendly API test in minutes.

# Quickstart

This path is for a developer who wants Reqbook working with a coding agent and a browser UI in a few minutes. The terminal is still there for automation, but it is not the only interface.

***

## 1. Install Reqbook

<Tabs>
  <Tab title="Shell installer">
    ```bash theme={null}
    curl -fsSL https://markapidown.net/install.sh | sh
    ```
  </Tab>

  <Tab title="Cargo">
    ```bash theme={null}
    cargo install reqbook
    ```
  </Tab>

  <Tab title="npm wrapper">
    ```bash theme={null}
    npm install -g reqbook
    ```
  </Tab>
</Tabs>

Verify the install:

```bash theme={null}
rqb version
```

***

## 2. Create a project

```bash theme={null}
mkdir my-api && cd my-api
rqb init --name=my-api --dev-url=https://jsonplaceholder.typicode.com --yes
```

Reqbook creates:

```text theme={null}
api-docs/
├── README.md
├── reqbook.md
├── _shared/
│ ├── env.template.md
│ └── env.md
├── apis/
│ └── posts/
│ └── get-posts.md
└── flows/
.gitignore
```

The generated endpoint uses JSONPlaceholder, so it can run immediately.

The generated `.gitignore` includes `.env.local` and `api-docs/_shared/env.md`, while `api-docs/_shared/env.template.md` stays commit-ready for new contributors.

***

## 3. Open the web UI

```bash theme={null}
rqb serve
```

Open `http://127.0.0.1:8080`.

<img alt="rqb-ui endpoint browser" />

Use the browser UI to:

* browse endpoint files,
* switch environments,
* fill path params such as `postId`,
* add runtime-only headers or body overrides,
* run requests and inspect formatted responses,
* import an endpoint from cURL,
* open the flow canvas.

<Note>
  Runtime fields in the request builder are temporary. They do not change markdown files unless you switch to edit mode and save.
</Note>

***

## 4. Run the same spec from the terminal

```bash theme={null}
rqb exec api-docs/apis/posts/get-posts.md --env=dev
```

Expected output:

```text theme={null}
GET https://jsonplaceholder.typicode.com/posts/1
status: 200
duration: 180ms
```

Dry-run shows the resolved request without sending it:

```bash theme={null}
rqb exec api-docs/apis/posts/get-posts.md --env=dev --dry-run
```

```text theme={null}
GET https://jsonplaceholder.typicode.com/posts/1
status: DRY RUN
duration: 0ms
headers:
 accept: application/json
```

***

## 5. Install agent skills and MCP

```bash theme={null}
rqb skills install
rqb install mcp
```

Or choose one agent:

```bash theme={null}
rqb skills install --agent=claude-code
rqb install mcp --agent=claude-code
rqb skills install --agent=cursor
rqb install mcp --agent=cursor
rqb skills install --agent=copilot
rqb install mcp --agent=copilot
```

Now you can ask your coding agent:

```text theme={null}
Use rqb_context with mode=surgical, brief=true, max_fields=6, then add a Reqbook spec for GET /users/:userId and validate it.
```

Or:

```text theme={null}
Create a flow that gets a post, captures userId, then gets that user.
```

***

## 6. Validate before commit

```bash theme={null}
rqb validate api-docs/
```

Commit the markdown files, not hidden app state.

***

## Next steps

<CardGroup>
  <Card title="VS Code extension" icon="code" href="/guides/vscode-extension">
    Preview, validate, run, and inspect specs from your editor.
  </Card>

  <Card title="Set up agent support" icon="robot" href="/agents/setup">
    Install skills, slash commands, and MCP for supported coding agents.
  </Card>

  <Card title="Web preview" icon="desktop" href="/guides/web-preview">
    Learn the browser UI: request tweaks, mock mode, cURL import, flow canvas.
  </Card>

  <Card title="Vibe coding guide" icon="wand-magic-sparkles" href="/guides/vibe-coding">
    Patterns for using Reqbook as the API layer in your agent loop.
  </Card>
</CardGroup>


# CLI reference
Source: https://docs.markapidown.net/reference/cli

Complete reference for all rqb subcommands, flags, and exit codes.

## Global flags

Every subcommand accepts these flags. Global flags can be placed before or after the subcommand name.

| Flag              | Type | Description                                                                           |
| ----------------- | ---- | ------------------------------------------------------------------------------------- |
| `--config <path>` | path | Path to `api-docs/reqbook.md`. Overrides the default discovery.                       |
| `--no-color`      | bool | Disable ANSI color in output. Also respected if `NO_COLOR` is set in the environment. |
| `-v`, `--verbose` | bool | Enable verbose diagnostic output.                                                     |
| `--yes`           | bool | Accept non-interactive defaults and skip production confirmation after human review.  |

***

## Exit codes

Reqbook returns stable exit codes you can reliably test for in CI scripts. See the [Exit codes reference](/reference/exit-codes) for CI usage examples.

| Code | Name            | Meaning                                                                                |
| ---- | --------------- | -------------------------------------------------------------------------------------- |
| `0`  | Passed          | All checks passed, request matched expected response.                                  |
| `1`  | Test failed     | Response did not match the expected response.                                          |
| `2`  | Invalid spec    | Spec file has a structural, syntax, or missing-variable error.                         |
| `3`  | Engine error    | Internal request build failure; check protocol and request block.                      |
| `4`  | Network error   | Host unreachable, DNS failure, timeout.                                                |
| `5`  | Secret detected | A secret pattern found in a versioned markdown file; exits before any network request. |

***

## rqb init

Scaffold a new `api-docs/` project in the current directory.

```bash theme={null}
rqb init [--name=<name>] [--dev-url=<url>] [--yes]
```

| Flag        | Type   | Default     | Description                                                                                     |
| ----------- | ------ | ----------- | ----------------------------------------------------------------------------------------------- |
| `--name`    | string | interactive | Project name written into `reqbook.md`.                                                         |
| `--dev-url` | string | interactive | Base URL written into `_shared/env.template.md` and `_shared/env.md` for the `dev` environment. |
| `--yes`     | bool   | `false`     | Global flag. Accept all defaults without interactive prompts.                                   |

Without `--yes`, Reqbook prompts for any missing values. `--yes` uses `my-api` and `http://localhost:8080` as defaults when no flags are provided.

<Note>
  `rqb init` does not overwrite existing files. If a file already exists, it exits with an error naming the conflicting file. It creates both `_shared/env.template.md` and `_shared/env.md`, then appends `.env.local` and the generated `<collection>/_shared/env.md` path to `.gitignore` if they are not already present.
</Note>

**Examples**

```bash theme={null}
# Interactive
rqb init

# Non-interactive
rqb init --name=payments-api --dev-url=http://localhost:3000

# Accept all defaults in CI
rqb init --yes
```

**Exit codes**: `0` on success, `3` on filesystem error.

***

## rqb validate

Validate one endpoint file, one pipeline file, or all markdown files under a directory.

```bash theme={null}
rqb validate <path>
```

| Argument | Description                    |
| -------- | ------------------------------ |
| `<path>` | File or directory to validate. |

Reqbook classifies each file by location and name:

* Files named `env.md` or `env.template.md` → validated as environment config.
* Files under `flows/` → validated as pipeline files.
* `reqbook.md` and `README.md` → checked for frontmatter only.
* All other `.md` files → validated as endpoint files.

Each error message includes the file path, line number when known, and a suggested fix.

**Examples**

```bash theme={null}
# Validate the entire project
rqb validate api-docs/

# Validate a single endpoint file
rqb validate api-docs/apis/users/get-user-by-id.md
```

**Exit codes**: `0` if all files are valid, `2` if any spec is invalid, `5` if a secret is detected.

***

## rqb exec

Execute one endpoint file and compare the actual response against the expected response.

```bash theme={null}
rqb exec <file> [--env=<env>] [--output=<format>] [--var key=val]... [--dry-run] [--timeout=<ms>] [--strict-assertions]
```

| Flag                  | Type    | Default   | Description                                                                                    |
| --------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------- |
| `<file>`              | path    | required  | Path to an endpoint markdown file.                                                             |
| `--env`               | string  | `dev`     | Environment name. Must match a heading in `_shared/env.md`.                                    |
| `--output`            | enum    | `console` | Output format: `console`, `junit`, `json`, or `markdown`.                                      |
| `--var`               | string  |           | Inject a variable as `key=value`. Repeatable. CLI variables override all other sources.        |
| `--dry-run`           | bool    | `false`   | Print the resolved request without sending it. Makes no network connection.                    |
| `--timeout`           | integer |           | Override request timeout in milliseconds. Takes precedence over endpoint and project defaults. |
| `--strict-assertions` | bool    | `false`   | Treat failing `## Assertions` rules as execution failures.                                     |

<Note>
  When `--env=prod` or `--env=production` is used in an interactive terminal, Reqbook prompts for confirmation before sending the request. In non-interactive shells, Reqbook refuses to send production requests unless `--yes` is passed after deliberate review.
</Note>

If a referenced variable is not resolved from any source, Reqbook exits with code `2` before making any network request, and prints a suggested fix naming the variable and where to define it.

**Examples**

```bash theme={null}
# Basic execution against the dev environment
rqb exec api-docs/apis/users/get-user-by-id.md

# Override environment and inject a variable
rqb exec api-docs/apis/users/get-user-by-id.md --env=staging --var userId=42

# JUnit XML output for CI test reporters
rqb exec api-docs/apis/users/get-user-by-id.md --output=junit > results.xml

# Dry run inspect the resolved request without sending
rqb exec api-docs/apis/users/create-user.md --dry-run --var email=test@example.com

# Override the timeout for a slow endpoint
rqb exec api-docs/apis/users/get-user-by-id.md --timeout=10000
```

**Exit codes**: `0` response matches, `1` assertion fails, `2` invalid spec, `3` engine error, `4` network error, `5` secret detected.

***

## rqb diagnose

Run one endpoint and print a compact diagnosis for the next debugging step. This is intended for coding agents and developers after `rqb exec` fails.

```bash theme={null}
rqb diagnose <file> [--env=<env>] [--output=<format>] [--var key=val]... [--timeout=<ms>] [--strict-assertions]
```

| Flag                  | Type    | Default   | Description                                               |
| --------------------- | ------- | --------- | --------------------------------------------------------- |
| `<file>`              | path    | required  | Path to an endpoint markdown file.                        |
| `--env`               | string  | `dev`     | Environment name.                                         |
| `--output`            | enum    | `console` | Output format: `console` or `json`.                       |
| `--var`               | string  |           | Inject a variable as `key=value`. Repeatable.             |
| `--timeout`           | integer |           | Override request timeout in milliseconds.                 |
| `--strict-assertions` | bool    | `false`   | Treat failing `## Assertions` rules as contract failures. |

`rqb diagnose` returns `passed`, `status`, `error_type`, `likely_cause`, `next_action`, `inspect`, `verify`, and a compact `diff`. Agents should use it after a failed `rqb exec` before reading backend source broadly.

**Examples**

```bash theme={null}
rqb diagnose api-docs/apis/refunds/post-refund-quote.md --env=dev
rqb diagnose api-docs/apis/refunds/post-refund-quote.md --env=staging --output=json
```

**Exit codes**: `0` if diagnosis completed and printed a diagnosis, even when the endpoint failed. Non-zero exit is reserved for CLI setup errors such as invalid `--var` syntax, production confirmation refusal, or output serialization failure.

***

## rqb flow

Execute a pipeline file. Steps run sequentially by default, with optional parallelism.

```bash theme={null}
rqb flow <file> [--env=<env>] [--output=<format>] [--var key=val]... [--parallel] [--no-parallel] [--dry-run] [--timeout=<ms>] [--strict-assertions]
```

| Flag                  | Type    | Default   | Description                                                                                                                                                      |
| --------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<file>`              | path    | required  | Path to a pipeline markdown file.                                                                                                                                |
| `--env`               | string  | `dev`     | Environment name.                                                                                                                                                |
| `--output`            | enum    | `console` | Output format: `console`, `junit`, `json`, or `markdown`.                                                                                                        |
| `--var`               | string  |           | Inject a variable as `key=value`. Repeatable.                                                                                                                    |
| `--parallel`          | bool    | `false`   | Force parallel execution, overriding the pipeline file's `parallel` setting.                                                                                     |
| `--no-parallel`       | bool    | `false`   | Force sequential execution, overriding the pipeline file's `parallel` setting.                                                                                   |
| `--dry-run`           | bool    | `false`   | Print resolved step requests without sending them. Captures become synthetic placeholders such as `__capture_userId__` so downstream requests can still resolve. |
| `--timeout`           | integer |           | Override timeout in milliseconds for every step in the pipeline.                                                                                                 |
| `--strict-assertions` | bool    | `false`   | Treat failing endpoint `## Assertions` rules as flow step failures.                                                                                              |

<Warning>
  `--parallel` and `--no-parallel` are mutually exclusive. Steps that depend on a captured value from a previous step always wait for that step regardless of parallel mode.
</Warning>

**Examples**

```bash theme={null}
# Run a pipeline against staging
rqb flow api-docs/flows/user-onboarding.md --env=staging

# Force sequential execution for debugging
rqb flow api-docs/flows/user-onboarding.md --no-parallel

# Resolve every step without sending requests
rqb flow api-docs/flows/user-onboarding.md --dry-run --output=json

# JSON output for programmatic consumption
rqb flow api-docs/flows/user-onboarding.md --output=json
```

**Exit codes**: `0` all steps pass (or `continue-on-error` is set), `1` any step fails, `2` pipeline spec invalid, `3` engine error, `4` network error.

***

## rqb index

Regenerate `api-docs/README.md` from the current set of markdown files under `api-docs/`.

```bash theme={null}
rqb index
```

No flags. The generated file contains a linked list of all markdown files grouped by resource. Do not edit `api-docs/README.md` by hand it is overwritten on every `rqb index` run.

<Note>
  `rqb index` is run automatically by `rqb init` and by all `rqb import` subcommands. Run it manually only if you added or renamed files after an import.
</Note>

**Example**

```bash theme={null}
rqb index
```

**Exit codes**: `0` on success, `3` on filesystem error.

***

## rqb import

Convert an existing API spec file into Reqbook markdown endpoint files. All subcommands write endpoint files under `api-docs/`, then run `rqb index` automatically. Complex logic (pre-request scripts, dynamic variables, JavaScript assertions) is imported as `agent-task` blocks for manual review.

**After any import**: run `rqb validate api-docs/` and move any secrets to `.env.local`. See the [Migration guide](/guides/migration) for per-tool concept mapping and post-import checklists.

### rqb import postman

Import a Postman Collection v2.1 JSON export.

```bash theme={null}
rqb import postman <file>
```

| Argument | Description                                  |
| -------- | -------------------------------------------- |
| `<file>` | Path to a Postman Collection v2.1 JSON file. |

```bash theme={null}
rqb import postman my-collection.json
```

### rqb import insomnia

Import an Insomnia v4 JSON export.

```bash theme={null}
rqb import insomnia <file>
```

| Argument | Description                              |
| -------- | ---------------------------------------- |
| `<file>` | Path to an Insomnia v4 JSON export file. |

```bash theme={null}
rqb import insomnia insomnia_export.json
```

### rqb import openapi

Import an OpenAPI 3.x spec in YAML or JSON format.

```bash theme={null}
rqb import openapi <file>
```

| Argument | Description                               |
| -------- | ----------------------------------------- |
| `<file>` | Path to an OpenAPI 3.x YAML or JSON file. |

```bash theme={null}
rqb import openapi openapi.yaml
rqb import openapi openapi.json
```

### rqb import collection

Import a local API client collection directory.

```bash theme={null}
rqb import collection ./local-client-collection
```

### rqb import http

Import a `.http` / REST Client request file.

```bash theme={null}
rqb import http ./requests.http
```

### rqb import curl

Import a single cURL command as a Reqbook endpoint file.

```bash theme={null}
rqb import curl [--file=<path>]
```

| Flag     | Description                                                               |
| -------- | ------------------------------------------------------------------------- |
| `--file` | Path to a file containing the cURL command. If omitted, reads from stdin. |

```bash theme={null}
# From clipboard (macOS)
pbpaste | rqb import curl

# From a file
rqb import curl --file=request.curl
```

**Exit codes (all import subcommands)**: `0` on success, `2` if the input file is not a valid spec for that tool, `3` on filesystem error.

***

## rqb export openapi

Export endpoint specs as OpenAPI 3.x YAML or JSON.

```bash theme={null}
rqb export openapi api-docs/ --out openapi.generated.yaml
rqb export openapi api-docs/ --json --out openapi.generated.json
```

| Flag     | Description                           |
| -------- | ------------------------------------- |
| `--out`  | Write to this file instead of stdout. |
| `--json` | Emit JSON instead of YAML.            |

***

## rqb check

Run PR-focused contract checks for endpoint and flow specs.

```bash theme={null}
rqb check api-docs/ --changed-from origin/main --report markdown
rqb check api-docs/ --changed-from origin/main --report github
rqb check api-docs/ --report junit
rqb check api-docs/ --report json
```

| Flag                  | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| `--changed-from`      | Only evaluate changed endpoint and flow files since this git ref. |
| `--report`            | `markdown`, `github`, `junit`, or `json`.                         |
| `--strict-assertions` | Treat failing `## Assertions` rules as contract failures.         |

***

## rqb context

Print bounded executable API context for coding agents.

```bash theme={null}
rqb context users.create
rqb context users.create --mode surgical --intent implement --brief --max-fields 12 --include variables,request,response,errors,rules,verify
rqb context users.create --include request,response,errors,rules,verify --no-guidance
rqb context users.create --mode schema --output json
rqb context users.create orders.create --mode compact --verbose
rqb context flow signup-login-profile
rqb context --changed-from origin/main --output json
```

| Flag             | Description                                                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--root`         | api-docs root directory. Defaults to `api-docs`.                                                                                                                                |
| `--changed-from` | Summarize only changed specs since this git ref.                                                                                                                                |
| `--token-budget` | Approximate output token budget.                                                                                                                                                |
| `--mode`         | `surgical`, `compact`, or `schema`. Defaults to `surgical` to minimize agent tokens.                                                                                            |
| `--intent`       | Agent task intent, e.g. `implement`, `debug`, `test`, `review`, or `document`.                                                                                                  |
| `--brief`        | Token-optimized output: omits title/guidance and keeps executable contract sections.                                                                                            |
| `--max-fields`   | Maximum request/response fields per section. Defaults to `8`. Use `12` for implement/review/debug tasks that need complete behavior; use `6` only for very narrow lookup tasks. |
| `--include`      | Comma-separated sections: `title`, `variables`, `request`, `response`, `errors`, `assertions`, `rules`, `verify`, `guidance`, or `all`.                                         |
| `--no-guidance`  | Omit agent workflow guidance text while keeping verify commands.                                                                                                                |
| `--verbose`      | Include full request and expected response blocks.                                                                                                                              |
| `--output`       | `markdown` or `json`. JSON wraps the rendered context with env, root, target, and budget metadata for agent automation.                                                         |

Use `--mode surgical --brief --max-fields 12 --include variables,request,response,errors,rules,verify --no-guidance` for most Codex/Claude/Cursor implement, review, and debug tasks. It returns method/path, variables, bounded request/response/error fields, literal error codes, compact business rules, and verify commands without repeated guidance. Use `--max-fields 6` only for a known single-field lookup, and use `--mode schema` when another tool or agent needs machine-readable contract JSON.

***

## rqb agent pack

Write an agent-ready markdown pack containing Reqbook context, guardrails, and suggested verify commands.

```bash theme={null}
rqb agent pack users.create orders.create --verbose --out .reqbook/agent-context.md
rqb agent pack flow signup-login-profile --mode surgical --brief --token-budget 1200
rqb agent pack --changed-from origin/main --out .reqbook/changed-context.md
```

| Flag             | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `--root`         | api-docs root directory. Defaults to `api-docs`.                        |
| `--changed-from` | Build the pack from changed endpoint and flow specs since this git ref. |
| `--out`          | Output markdown file. Defaults to `.reqbook/agent-context.md`.          |
| `--token-budget` | Approximate output token budget. Defaults to `1600`.                    |
| `--mode`         | `surgical`, `compact`, or `schema`. Defaults to `surgical`.             |
| `--intent`       | Agent task intent included in the pack metadata.                        |
| `--brief`        | Token-optimized context pack for coding agents.                         |
| `--max-fields`   | Maximum request/response fields per section. Defaults to `8`.           |
| `--include`      | Comma-separated context sections to include.                            |
| `--no-guidance`  | Omit repeated guidance from the generated pack context.                 |
| `--verbose`      | Include full request, expected response, agent-task, and notes blocks.  |
| `--env`          | Environment used in suggested verify commands. Defaults to `dev`.       |

Use the generated pack as the initial prompt/context file for Codex, Claude, Cursor, or another coding agent. It tells the agent which APIs matter, which commands are safe to run, and how to verify the implementation.

***

## rqb skills

Install, list, or remove Reqbook skill files for AI coding agents. Skills are embedded in the binary no network access required.

### rqb skills install

Install Reqbook skill files into detected AI agent config directories.

```bash theme={null}
rqb skills install [--agent=<name>]
```

| Flag      | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `--agent` | string | Install skills only for a specific agent. Installs for all detected agents if omitted. |

Supported agent names: `claude-code`, `cursor`, `copilot`, `codex-cli`, `antigravity`, `opencode`, `windsurf`.

Reqbook detects agents by checking for their config directories (`.claude/`, `.cursor/`, `.github/`, etc.).

```bash theme={null}
# Install for all detected agents
rqb skills install

# Install only for Claude Code
rqb skills install --agent=claude-code

# Install only for Cursor
rqb skills install --agent=cursor
```

<Tip>
  After upgrading Reqbook, run `rqb doctor --fix` to update installed skills to the new binary version automatically.
</Tip>

### rqb skills list

List detected AI agents and whether Reqbook skills are installed and up-to-date for each.

```bash theme={null}
rqb skills list
```

No flags.

```bash theme={null}
rqb skills list
# claude-code: detected, skills up-to-date
# cursor: not detected
# copilot: not detected
```

### rqb skills uninstall

Remove installed Reqbook skill files.

```bash theme={null}
rqb skills uninstall [--agent=<name>]
```

| Flag      | Type   | Description                                                                       |
| --------- | ------ | --------------------------------------------------------------------------------- |
| `--agent` | string | Uninstall skills for a specific agent only. Uninstalls for all agents if omitted. |

```bash theme={null}
rqb skills uninstall --agent=claude-code
```

**Exit codes (all skills subcommands)**: `0` on success, `3` on filesystem error.

***

## rqb install mcp

Install Reqbook MCP server configuration for one agent or every detected agent.

```bash theme={null}
rqb install mcp [--agent=<name>]
```

| Flag      | Type   | Description                                                                                |
| --------- | ------ | ------------------------------------------------------------------------------------------ |
| `--agent` | string | Install MCP config only for a specific agent. Installs for all detected agents if omitted. |

Supported agent names: `claude-code`, `cursor`, `copilot`, `codex-cli`, `antigravity`, `opencode`, `windsurf`.

| Agent                     | Config written                          |
| ------------------------- | --------------------------------------- |
| Claude Code               | `.mcp.json`                             |
| Codex CLI / IDE           | `.codex/config.toml`                    |
| Cursor                    | `.cursor/mcp.json`                      |
| GitHub Copilot in VS Code | `.vscode/mcp.json`                      |
| OpenCode                  | `opencode.json`                         |
| Antigravity               | `~/.gemini/antigravity/mcp_config.json` |
| Windsurf / Cascade        | `~/.codeium/windsurf/mcp_config.json`   |

After installing, restart the agent or use its MCP reload/list command.

***

## rqb serve

Start the local web preview server.

```bash theme={null}
rqb serve [<path>] [--port=8080] [--host=127.0.0.1] [--env=<env>] [--mock]
```

| Flag / Argument | Type    | Default                 | Description                                                                                                              |
| --------------- | ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `<path>`        | path    | `.` (current directory) | Root directory of the Reqbook project.                                                                                   |
| `--port`        | integer | `8080`                  | TCP port to listen on.                                                                                                   |
| `--host`        | string  | `127.0.0.1`             | Host to bind to. Use `0.0.0.0` to expose on the local network (a warning is printed).                                    |
| `--env`         | string  | `dev`                   | Environment used when executing endpoints from the preview UI.                                                           |
| `--mock`        | bool    | `false`                 | Start in mock mode. The "Send" button returns the recorded `## Expected response` instead of making a real HTTP request. |

The web preview reads the same markdown files as the CLI. No build step is required. The server watches for file changes and refreshes connected browsers automatically.

```bash theme={null}
rqb serve
rqb serve --port=9000 --env=staging
rqb serve --mock
rqb serve /path/to/other-project
```

**Exit codes**: `0` on clean shutdown (Ctrl-C), `3` on startup error.

***

## rqb doctor

Check the project environment for common setup problems.

```bash theme={null}
rqb doctor [--fix]
```

| Flag    | Type | Description                     |
| ------- | ---- | ------------------------------- |
| `--fix` | bool | Automatically apply safe fixes. |

`rqb doctor` checks:

* Whether `api-docs/` exists.
* Whether `.env.local` and `<collection>/_shared/env.md` are listed in `.gitignore`.
* Whether all specs under `api-docs/` are valid.
* Which AI agent config directories are present.
* Whether installed skills match the current binary version.
* Whether an outbound network connection can be made.

`--fix` applies safe fixes automatically: adds missing local environment entries to `.gitignore`, and reinstalls stale skills.

<Note>
  Run `rqb doctor` as the first debugging step when `rqb exec`, `rqb validate`, or an AI agent skill behaves unexpectedly.
</Note>

```bash theme={null}
rqb doctor
rqb doctor --fix
```

**Exit codes**: `0` if all checks pass, `1` if any check fails.

***

## rqb mock

Start a mock HTTP server that replays recorded expected responses.

```bash theme={null}
rqb mock [<path>] [--port=4001] [--latency=<ms>]
```

| Flag / Argument | Type    | Default                 | Description                                 |
| --------------- | ------- | ----------------------- | ------------------------------------------- |
| `<path>`        | path    | `.` (current directory) | Root directory of the Reqbook project.      |
| `--port`        | integer | `4001`                  | TCP port to listen on.                      |
| `--latency`     | integer | `0`                     | Simulated response latency in milliseconds. |

The mock server reads `## Expected response` blocks from your endpoint files and serves their bodies at the corresponding HTTP methods and paths. Useful for frontend development when the live backend is unavailable.

```bash theme={null}
# Start mock server on default port
rqb mock

# Simulate network latency
rqb mock --port=4001 --latency=200
```

***

## rqb mcp

Start a Model Context Protocol server that exposes Reqbook tools to AI agents.

```bash theme={null}
rqb mcp
```

No flags. The MCP server exposes the following tools to any MCP-compatible AI agent:

| Tool             | Description                                                                             |
| ---------------- | --------------------------------------------------------------------------------------- |
| `rqb_exec`       | Execute an endpoint spec                                                                |
| `rqb_diagnose`   | Diagnose a failed endpoint and return next action, inspect targets, and verify commands |
| `rqb_flow`       | Run a pipeline                                                                          |
| `rqb_author`     | Create or update a spec file                                                            |
| `rqb_vars`       | Show variable resolution for a spec                                                     |
| `rqb_search`     | Search specs by method, path, tag, or text                                              |
| `rqb_context`    | Return bounded executable API context for a target, flow, or changed specs              |
| `rqb_history`    | Return recent execution history for a spec                                              |
| `rqb_session`    | Get or set default MCP env and vars                                                     |
| `rqb_exec_batch` | Run multiple specs and return a compact summary                                         |

Install an agent config:

```bash theme={null}
rqb install mcp --agent=codex-cli
```

See [AI agent integration](/guides/ai-agents) for full setup and usage details.

***

## rqb completion

Print a shell completion script to stdout.

```bash theme={null}
rqb completion <shell>
```

| Argument  | Description                                              |
| --------- | -------------------------------------------------------- |
| `<shell>` | One of `bash`, `zsh`, `fish`, `elvish`, or `powershell`. |

<CodeGroup>
  ```bash Bash theme={null}
  rqb completion bash >> ~/.bash_completion
  ```

  ```bash Zsh theme={null}
  rqb completion zsh > ~/.zfunc/_rqb
  echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
  autoload -Uz compinit && compinit
  ```

  ```bash Fish theme={null}
  rqb completion fish > ~/.config/fish/completions/rqb.fish
  ```
</CodeGroup>

**Exit codes**: `0` always.

***

## rqb version

Print the installed version of Reqbook and exit.

```bash theme={null}
rqb version
```

No flags.

```bash theme={null}
rqb version
# 0.1.4
```

**Exit codes**: `0` always.


# Configuration reference
Source: https://docs.markapidown.net/reference/configuration

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`         |


# Exit codes
Source: https://docs.markapidown.net/reference/exit-codes

Reqbook returns stable exit codes so CI pipelines can act on pass, failure, invalid spec, or secret detection independently.

## Overview

Reqbook uses six exit codes. All are stable across versions you can reliably test for them in CI scripts without worrying about changes between releases.

| Code | Name            | When it occurs                                                                                         | CLI commands that can return it                              |
| ---- | --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `0`  | Passed          | All checks passed; response matched the expected response.                                             | All commands.                                                |
| `1`  | Test failed     | Response did not match the expected response.                                                          | `exec`, `flow`, `doctor`                                     |
| `2`  | Invalid spec    | Frontmatter error, missing required section, unresolved variable, or environment mismatch.             | `exec`, `flow`, `validate`                                   |
| `3`  | Engine error    | Request build failed or unsupported protocol.                                                          | `exec`, `flow`, `init`, `index`, `import`, `skills`, `serve` |
| `4`  | Network error   | DNS failure, unreachable host, or timeout exhausted.                                                   | `exec`, `flow`                                               |
| `5`  | Secret detected | A secret pattern was found in a versioned markdown file. Exits immediately before any network request. | `exec`, `flow`, `validate`                                   |

***

## When each code fires

**Exit code 1 Test failed**
The request was sent successfully and a response was received, but one or more assertions in `## Expected response` did not match. Check the diff output to see which fields diverged.

**Exit code 2 Invalid spec**
Reqbook could not build a valid request from the spec. This covers malformed frontmatter, missing required sections, unresolved `{{variable}}` references, and `--env` values that have no matching heading in `env.md`. The error message includes the file path, line number when available, and a suggested fix.

**Exit code 3 Engine error**
An internal failure prevented Reqbook from building the HTTP request. Common causes: unsupported protocol value in frontmatter, filesystem error reading a file, or a corrupted binary. Check the `--verbose` output for details.

**Exit code 4 Network error**
The request was built and sent but no response was received. Covers DNS resolution failure, connection refused, and timeout expiry across all retry attempts.

**Exit code 5 Secret detected**
Reqbook found a pattern matching a secret (JWT token, hex API key, `sk_` prefixed key, etc.) in a markdown/config file. The process exits immediately no request is sent, no spec is executed. Move the value to `.env.local` or a `RQB_*` environment variable.

***

## CI usage examples

**Fail CI on any invalid spec**

```bash theme={null}
rqb validate api-docs/ || exit 1
```

**Inspect the exit code of a single endpoint test**

```bash theme={null}
rqb exec api-docs/apis/health/get-health.md --env=staging
echo "Exit: $?"
```

**Distinguish a network failure from a response mismatch**

```bash theme={null}
rqb exec api-docs/apis/users/get-user-by-id.md --env=staging --var id=usr_123
CODE=$?
if [ $CODE -eq 1 ]; then echo "Response mismatch check spec or API behavior"; fi
if [ $CODE -eq 4 ]; then echo "Network unreachable check VPN or service health"; fi
```

**Full case statement**

```bash theme={null}
rqb exec api-docs/apis/users/get-user.md --env=staging
CODE=$?
case $CODE in
 0) echo "Passed" ;;
 1) echo "Response mismatch check the spec or API behavior" ; exit 1 ;;
 2) echo "Invalid spec run rqb validate to see errors" ; exit 1 ;;
 4) echo "Network error check VPN, service health, or BASE_URL" ; exit 1 ;;
 5) echo "Secret committed to spec file fix before merging" ; exit 1 ;;
 *) echo "Unexpected error (code $CODE)" ; exit 1 ;;
esac
```

***

## GitHub Actions example

```yaml filename=".github/workflows/api-tests.yml" theme={null}
name: API spec tests

on:
 push:
 branches: [main]
 pull_request:
 paths:
 - 'api-docs/**'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install Reqbook
 run: curl -fsSL https://markapidown.net/install.sh | sh

 - name: Validate specs
 run: rqb validate api-docs/

 - name: Run health check
 run: rqb exec api-docs/apis/health/get-health.md --env=staging
 env:
 RQB_BASE_URL: https://staging.example.com
 RQB_AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}
```

<Tip>
  Use `RQB_*` environment variables to pass secrets into CI. They map automatically to camel-case variable names `RQB_AUTH_TOKEN` becomes `{{authToken}}` in your specs.
</Tip>


# New Request
Source: https://docs.markapidown.net/ui/new-request

Send any HTTP request from the browser without creating a spec file first.

## Overview

The **New Request** panel in rqb-ui lets you build and send any HTTP request interactively no spec file required. It's the browser equivalent of `rqb request`.

## Open it

Click **New Request** in the top navigation bar, or navigate to `http://localhost:8080/request`.

<img alt="New Request panel" />

## Layout

The panel has two columns:

* **Left Request builder**: method selector, URL, headers, body, variable overrides, save-as path
* **Right Response viewer**: status, body, headers, raw request

## Features

| Feature             | Details                                                            |
| ------------------- | ------------------------------------------------------------------ |
| Method selector     | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS                       |
| Variable resolution | `{{variable}}` references are resolved from the active environment |
| Variable overrides  | Add per-request overrides without editing env files                |
| Body editor         | Raw text editor; auto-shown for POST/PUT/PATCH                     |
| Save as spec        | Enter a relative path to save the result as a markdown spec        |
| Auto-scratch        | Without a save path, responses are saved to the scratch workspace  |

## Save to collection

Enter a relative path in the **Save as spec** field, e.g. `apis/users/get-users.md`. After sending, the request and response become a spec in your collection ready to run with `rqb exec` or from the endpoint browser.

## Compare with rqb-cli

The browser New Request panel and `rqb request` use the same backend. Both save to the same workspace locations.


# Reqbook Browser UI
Source: https://docs.markapidown.net/ui/overview

Use the local Reqbook browser UI to run endpoint specs, inspect responses, edit markdown, and build API flows.

## What is rqb-ui?

**rqb-ui** is the browser interface to Reqbook, accessed via `rqb serve`. It provides a visual environment for:

* Browsing and searching your API spec collection
* Sending requests with interactive variable overrides
* Building and running multi-step pipelines on a visual canvas
* Editing spec files in-browser with live save-back to disk
* Sending ad-hoc HTTP requests without creating a spec file first
* Running in mock mode against recorded responses

## Launch

```bash theme={null}
rqb serve
# Opens at http://127.0.0.1:8080
```

<img alt="rqb-ui endpoint browser" />

Custom host/port:

```bash theme={null}
rqb serve --host 0.0.0.0 --port 3000
```

## Features

| Feature           | How to access                       |
| ----------------- | ----------------------------------- |
| Browse collection | Home page index                     |
| Run endpoint      | Click an endpoint → Send button     |
| New Request       | "New Request" button in the top bar |
| Build a flow      | Flows → New Flow                    |
| Edit spec source  | Endpoint page → Edit source         |
| Import from curl  | Import curl button in top bar       |
| Scan project      | Scan button in top bar              |
| Mock mode         | `rqb serve --mock`                  |

## Same binary two interfaces

```
rqb serve → opens rqb-ui (this)
rqb exec → runs in the terminal (rqb-cli)
```