DOCSEARCHbyAlgolia
Submit Docs

Redocly CLI Documentation

repository·main·Indexed 23 days ago

https://github.com/redocly/redocly-cli

An all-in-one utility for the API lifecycle, providing tools to build documentation, lint specifications against guidelines, bundle multi-file specs, perform contract testing, and generate typed clients. The CLI supports configurable rules for OpenAPI specifications, including API health checks, Azure API Management (APIM) compatibility, JSON Schema validation, and RESTful principle enforcement.

Tokens
280K
Snippets
801
Records
1.3K
Agent score
76%

What's inside Redocly CLI

  1. Overview of Redocly CLI capabilities

    main

    Redocly CLI is an open source command-line tool designed for managing the API lifecycle. It provides capabilities for:

    • API Documentation: Create clear documentation using Redoc (open source) or hosted tools, including local previews and static builds.
    • File Management: Split OpenAPI descriptions into logical chunks, bundle chunks into a single file, or join existing definitions.
    • OpenAPI Transformation: Use decorators to enhance OpenAPI files by adding, changing, or removing content, or to publish specific subsets of endpoints.
    • API Governance: Perform API linting using built-in or configurable rulesets to ensure APIs meet specific standards.
    • SDK Generation: Generate typed, zero-dependency TypeScript clients from OpenAPI descriptions, including support for auth, retries, pagination, Zod schemas, TanStack Query hooks, and mocks.

  2. Overview of @redocly/client-generator

    main

    The @redocly/client-generator package converts OpenAPI descriptions into typed TypeScript clients.

    Key characteristics:

    • Zero runtime dependencies: The generated code relies exclusively on web-standard APIs such as fetch, AbortController, and URLSearchParams.
    • Environment agnostic: Because it uses web standards, the generated client can run in browsers, Node.js, Bun, Deno, and various edge runtimes.
    • CLI Integration: This package powers the redocly generate-client CLI command.

  3. Choose between Redocly API reference and Redoc

    main

    Redocly provides two distinct paths for generating web-based API reference documentation depending on your hosting and customization needs:

    Redocly API reference (Managed Platform)

    Ideal for teams requiring hassle-free hosting, extensive theme customization, and built-in CI/CD integration. It allows for automatic updates whenever your OpenAPI description changes and includes interactive features like code examples and 'try it out' capabilities.

    How to get started:

    • Sign up for Workflows and add your OpenAPI description to the registry.
    • Use the Redocly CLI for local previews.
    • Use the Redocly VS Code extension for OpenAPI editing and configuration autocomplete.

    Redoc (Open Source)

    Ideal for teams that want to self-host their documentation or prefer an open source solution. It has fewer features and theming options compared to the managed platform but integrates with Redocly CLI.

    How to get started:

  4. Redocly CLI command categories

    main

    The Redocly CLI provides a suite of commands categorized by their primary function:

    Documentation

    • preview: Start a local preview of a Redocly project.
    • translate: Generate translation keys for Redocly projects (Realm, Reef, or Revel).
    • eject: Eject and modify components from the core theme.
    • build-docs: Build API descriptions into HTML files.

    API Management

    • bundle: Bundle API descriptions.
    • generate-client: [Experimental] Generate a typed TypeScript client from an OpenAPI description.
    • join: [Experimental] Join API descriptions.
    • score: Score an API for integration simplicity and AI agent readiness.
    • split: Split API descriptions into a multi-file structure.
    • stats: Gather statistics for a document.

    Linting

    • lint: Lint API descriptions.
    • check-config: Lint the Redocly configuration file.

    Testing (Respect)

    • respect: Execute API tests described in an Arazzo description.
    • generate-arazzo: Generate an Arazzo description from an OpenAPI description.
    • drift: [Experimental] Detect drift between recorded HTTP traffic and an OpenAPI description.
    • proxy: [Experimental] Capture live HTTP traffic through a reverse proxy into a HAR file.
    • generate-spec: [Experimental] Infer an OpenAPI description from recorded HTTP traffic.

    Redocly Platform

    • login: Log in to Reunite.
    • logout: Clear stored credentials.
    • push: Push an API description to Reunite.
    • push-status: Track an in-progress push operation to Reunite.

    Supporting

    • completion: Generate autocomplete commands.

  5. Understand and use built-in linting rules

    main

    Redocly CLI includes a suite of built-in rules designed to enforce API best practices and specification compliance. You can use these rules to lint various API description formats, including OpenAPI, AsyncAPI, Arazzo, Open-RPC, and Overlay.

    To use a built-in rule, you typically decide its severity level: error, warn, or off. Some rules allow for additional configuration to tailor them to your specific API design standards.

  6. Redocly CLI command overview

    main

    The Redocly CLI provides a suite of commands categorized by their primary function. Use these commands to manage documentation, manipulate API descriptions, perform linting, execute tests, and interact with the Redocly platform.

    Documentation commands

    • preview: Start a local preview of a Redocly project.
    • translate: Generate translation keys for Redocly projects (Realm, Reef, or Revel).
    • eject: Eject and modify components from the core theme.
    • preview-docs: Preview API reference docs for a specified API description.
    • build-docs: Build an API description into an HTML file.

    API management commands

    • stats: Gather statistics for a document.
    • bundle: Bundle an API description.
    • split: Split an API description into a multi-file structure.
    • join: Join API descriptions [experimental].

    Linting commands

    • lint: Lint an API description.
    • check-config: Lint the Redocly configuration file.

    Testing commands

    • respect: Execute API tests described in an Arazzo description.
    • generate-arazzo: Generate an Arazzo description from an OpenAPI description.

    Redocly platform commands

    • login: Log in to Reunite or the Redocly API registry using an access token.
    • logout: Clear stored credentials.
    • push: Push an API description to the Redocly API registry.
    • push-status: Track an in-progress push operation to Reunite.

    Supporting commands

    • completion: Generate autocomplete commands.

  7. Limitations of redocly proxy

    main

    When using the proxy command, be aware of the following technical limitations:

    • Reverse Proxy Only: The proxy does not support CONNECT mode or inbound TLS termination. Clients must target the proxy directly.
    • Encoding: The accept-encoding header is stripped from forwarded requests so that captured bodies are stored decoded. Binary response bodies are stored as base64-encoded strings within the HAR file.
    • Shutdown Requirement: Captured exchanges are streamed to a temporary file (<har>.entries.tmp). The final HAR file is only assembled and written upon a graceful shutdown. If the process is killed abruptly (e.g., SIGKILL), the final HAR file will not be created.

  8. Extend Redocly CLI with Custom Plugins

    main

    Custom plugins provide the highest level of extensibility for the Redocly CLI. They consist of two main components:

    Decorators

    Decorators are used to transform or modify the API description. Common tasks include:

    • Sorting: Alphabetizing tags, methods, properties, or enum values.
    • Cleaning: Removing unused tags, removing specific OpenAPI Extensions, or stripping features unsupported by platforms like Azure APIM.
    • Updating: Substituting datetime placeholders in examples with current dates or setting/overwriting servers URLs.
    • Mapping: Swapping summary and description fields or applying root-level security to operations.

    Rules

    Rules are used to validate the API description. Common tasks include:

    • Markdown Validation: Checking that description fields contain valid Markdown.
    • Code Sample Checks: Ensuring a required list of languages is present in x-code-samples for every operation.
    • Enum Validation: Checking that a schema's default value is part of its enum list.

  9. Understand the Spec ruleset severity

    main
    The spec ruleset is designed for strict adherence to specifications. In this ruleset, all rules are configured with a severity of error. This means that any violation of the rules listed in this ruleset will cause linting processes to fail, which is useful for enforcing strict API contract compliance.

  10. Use SSE (Server-Sent Events) in generated clients

    main

    Server-Sent Events (SSE) operations are no longer contained in a separate sse.* namespace. Instead, they are implemented as flat async-generator methods.

    An operation is identified as an SSE operation if it has kind: 'sse' in its Ops definition. You can consume these by iterating over the async generator returned by the client method.

  11. Understand the Spec ruleset

    main
    The spec ruleset is a collection of linting rules designed to ensure strict adherence to API specifications. In this ruleset, all rules are configured with a severity of error. This means that any violation of these rules will cause the Redocly CLI linting process to fail, which is useful for enforcing high-quality API contracts in CI/CD pipelines.

  12. Customize the generated client at runtime

    main
    To avoid losing changes during regeneration, do not attempt to hand-edit the generated client code. Instead, use the provided runtime extension surface to shape requests and responses. Customization is achieved by composing consumer-owned modules using the ClientConfig or the client.use() method. This allows you to add headers, attach trace/idempotency keys, swap transport layers, implement retries, or map errors to domain types without affecting the core generated code.