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

# VS Code 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 controls muted playsInline preload="metadata" poster="https://markapidown.net/images/demoapi.png" style={{ width: "100%", borderRadius: "8px" }}>
  <source src="https://markapidown.net/videos/vscode-demo.mp4" 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.