Command Line

@rapidoc/cli gives you the rapidoc command. It builds and runs developer portals, and the commands on this page also work on plain OpenAPI files, wherever you use <rapi-doc>:

• preview shows a spec as you edit it.
• validate and lint check it.
• bundle joins a spec split over several files into one.
• mock serves its API with example responses.
• mcp turns it into tools for AI agents.

npm install -D @rapidoc/cli
npx rapidoc --help            # every command
npx rapidoc validate --help   # one command's options and examples

Preview a spec

npx rapidoc preview openapi.yaml --open

Shows the spec in <rapi-doc> on http://localhost:4000 and reloads it whenever a file in its folder changes, so you can edit the YAML and watch the page. Relative $refs to other files work. --theme picks a <rapi-doc> theme; a URL works too (npx rapidoc preview https://example.com/openapi.json), without reloading.

Validate a spec

npx rapidoc validate openapi.yaml
npx rapidoc validate https://example.com/openapi.json

rapidoc validate checks a spec strictly against the OpenAPI Specification (2.0, 3.0, 3.1 and 3.2): required fields such as info.version, types, path parameters that are used but not defined, and $refs that point to nothing. Files reached through a relative $ref are checked too. Each error names the file, line and column:

🔍 openapi.yaml: openapi.yaml
   ❌ 1 error(s):
      openapi.yaml:3:1  must have required property 'version'  (#/info)

Option	Meaning
--format pretty | json | sarif	json for scripts, sarif for GitHub code scanning (problems shown on the pull request).
--strict	Fail on warnings too.
--remote	Also fetch remote $refs.

It exits with code 1 when the spec has errors, so it can guard a pull request:

.github/workflows/api.yml

# in a job's steps:
- run: npx rapidoc validate openapi.yaml

Lint a spec

npx rapidoc lint openapi.yaml
npx rapidoc lint openapi.yaml --rule operation-description=warn --strict

A valid spec can still make a poor reference page. rapidoc lint runs validate’s check and then rules for what <rapi-doc>, Try and MCP tools need: an operationId on every operation (stable anchors and tool names), unique and URL-safe; a summary (the sidebar label); tags declared in the top-level list; a success response; a security requirement on write operations; an example on request and response bodies (Try’s sample body); no unused components; no example.com servers. Each finding comes with file:line:col and the rule name, in the same pretty, JSON or SARIF output as validate. Most rules default to warn, so a first run doesn’t fail CI; --strict makes warnings fail, --rule name=off turns one off, and --rules lists them all.

Bundle a spec split over files

npx rapidoc bundle openapi.yaml -o dist/openapi.json
npx rapidoc bundle openapi.yaml --dereference > flat.yaml

rapidoc bundle writes a spec and every file its $refs reach as one document, for tools that can’t follow $refs across files. A $ref to another file becomes a component (./schemas/Order.yaml → #/components/schemas/Order, holding a copy; definitions in Swagger 2.0), named after the file or the pointer’s last part, and in-file $refs stay. --dereference inlines everything instead, and stops on a recursive schema. The result is validated before it’s written (--no-validate skips that); -o picks JSON or YAML by the extension, and without it the document goes to stdout.

Mock the API

npx rapidoc mock openapi.yaml                    # http://localhost:4010/openapi
npx rapidoc mock ./specs --port 4011             # every OpenAPI file in the folder

rapidoc mock answers every operation of the spec over HTTP, from its examples or with generated data. It validates requests and can check OAuth tokens against your OpenID Connect issuer. It needs @rapidoc/mock. See Mock Server for the options, and the overview for how it compares with the in-browser mock.

Turn it into an MCP server

npx rapidoc mcp export openapi.yaml --out-dir orders-mcp   # the server project
npx rapidoc mcp serve openapi.yaml                         # run it over stdio, no files

mcp export writes the same project as <rapi-doc>’s Export MCP Server button. mcp serve runs it directly, so an agent’s config can start it with npx rapidoc mcp serve <spec> (it needs @modelcontextprotocol/sdk installed). Credentials come from the environment, one variable per security scheme; --base-url points the calls at rapidoc mock, and --arazzo adds workflows as tools.

Everything else

rapidoc doctor checks your setup (Node, package versions) and prints a report for bug reports. The other commands (init, dev, build, serve, migrate) create and run a developer portal: OpenAPI references next to Markdown and Markdoc guides, with search and optional single sign-on. The full reference, with every option, is in the RapiDoc Portal docs.

In a terminal, rapidoc asks for what the options don’t say and shows a menu when run alone; piped, in CI or with --yes it never asks. Exit codes: 0 success, 1 problems in the input, 2 a wrong command line. rapidoc completion zsh|bash|fish prints a completion script for commands, options and their values.