> ## 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. # CLI reference > 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 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=] [--dev-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. `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 `/_shared/env.md` path to `.gitignore` if they are not already present. **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 ``` | Argument | Description | | -------- | ------------------------------ | | `` | 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 [--env=] [--output=] [--var key=val]... [--dry-run] [--timeout=] [--strict-assertions] ``` | Flag | Type | Default | Description | | --------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------- | | `` | 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. | 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. 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 [--env=] [--output=] [--var key=val]... [--timeout=] [--strict-assertions] ``` | Flag | Type | Default | Description | | --------------------- | ------- | --------- | --------------------------------------------------------- | | `` | 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 [--env=] [--output=] [--var key=val]... [--parallel] [--no-parallel] [--dry-run] [--timeout=] [--strict-assertions] ``` | Flag | Type | Default | Description | | --------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | 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. | `--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. **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. `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. **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 ``` | Argument | Description | | -------- | -------------------------------------------- | | `` | 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 ``` | Argument | Description | | -------- | ---------------------------------------- | | `` | 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 ``` | Argument | Description | | -------- | ----------------------------------------- | | `` | 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=] ``` | 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=] ``` | 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 ``` After upgrading Reqbook, run `rqb doctor --fix` to update installed skills to the new binary version automatically. ### 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=] ``` | 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=] ``` | 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 [] [--port=8080] [--host=127.0.0.1] [--env=] [--mock] ``` | Flag / Argument | Type | Default | Description | | --------------- | ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `` | 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 `/_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. Run `rqb doctor` as the first debugging step when `rqb exec`, `rqb validate`, or an AI agent skill behaves unexpectedly. ```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 [] [--port=4001] [--latency=] ``` | Flag / Argument | Type | Default | Description | | --------------- | ------- | ----------------------- | ------------------------------------------- | | `` | 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 ``` | Argument | Description | | --------- | -------------------------------------------------------- | | `` | One of `bash`, `zsh`, `fish`, `elvish`, or `powershell`. | ```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 ``` **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.