CLI reference - Reqbook

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

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.

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.

Examples

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

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

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

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.

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

# 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 protected]

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

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

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.

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.

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

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

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

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 for per-tool concept mapping and post-import checklists.

rqb import postman

Import a Postman Collection v2.1 JSON export.

rqb import postman <file>

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

rqb import postman my-collection.json

rqb import insomnia

Import an Insomnia v4 JSON export.

rqb import insomnia <file>

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

rqb import insomnia insomnia_export.json

rqb import openapi

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

rqb import openapi <file>

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

rqb import openapi openapi.yaml
rqb import openapi openapi.json

rqb import collection

Import a local API client collection directory.

rqb import collection ./local-client-collection

rqb import http

Import a .http / REST Client request file.

rqb import http ./requests.http

rqb import curl

Import a single cURL command as a Reqbook endpoint file.

rqb import curl [--file=<path>]

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

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

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.

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.

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.

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.

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

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

rqb skills list

No flags.

rqb skills list
# claude-code: detected, skills up-to-date
# cursor: not detected
# copilot: not detected

rqb skills uninstall

Remove installed Reqbook skill files.

rqb skills uninstall [--agent=<name>]

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

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.

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.

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.

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.

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.

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

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.

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.

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

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:

rqb install mcp --agent=codex-cli

See AI agent integration for full setup and usage details.

rqb completion

Print a shell completion script to stdout.

rqb completion <shell>

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

rqb completion bash >> ~/.bash_completion

Exit codes: 0 always.

rqb version

Print the installed version of Reqbook and exit.

rqb version

No flags.

rqb version
# 0.1.4

Exit codes: 0 always.

​Global flags

​Exit codes

​rqb init

​rqb validate

​rqb exec

​rqb diagnose

​rqb flow

​rqb index

​rqb import

​rqb import postman

​rqb import insomnia

​rqb import openapi

​rqb import collection

​rqb import http

​rqb import curl

​rqb export openapi

​rqb check

​rqb context

​rqb agent pack

​rqb skills

​rqb skills install

​rqb skills list

​rqb skills uninstall

​rqb install mcp

​rqb serve

​rqb doctor

​rqb mock

​rqb mcp

​rqb completion

​rqb version

Global flags

Exit codes

rqb init

rqb validate

rqb exec

rqb diagnose

rqb flow

rqb index

rqb import

rqb import postman

rqb import insomnia

rqb import openapi

rqb import collection

rqb import http

rqb import curl

rqb export openapi

rqb check

rqb context

rqb agent pack

rqb skills

rqb skills install

rqb skills list

rqb skills uninstall

rqb install mcp

rqb serve

rqb doctor

rqb mock

rqb mcp

rqb completion

rqb version