{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"build-static-api-reference-documentation","__idx":0},"children":["Build static API reference documentation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"benefits-of-using-static-api-reference-documentation","__idx":1},"children":["Benefits of using static API reference documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Static API documentation produces static HTML and CSS files based on your API definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Redocly JS CDN builds the documentation on each page load. There is a performance penalty for doing that, which is magnified based on the size of the API definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Static API documentation benefits from SEO-friendly routes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have a large API definition and page-load speed is really important."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You are using layout scope sections to give you SEO-friendly URLs and content."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have an existing CI script for deployments which makes using a CLI tool a natural fit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You cannot use Redocly's Workflows due to your organizational internal policies."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly uses this tool within our own ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workflows"]}," product."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-reference-docs-cli","__idx":2},"children":["What is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference-docs"]}," CLI?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference-docs"]}," CLI tool creates static API documentation (HTML, JS and CSS files) which opens instantly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you update your API definition, you need to rebuild your documentation. For this purpose, you can set up a build step for each API definition change. This is exactly what our Workflows product does."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This feature is only available in our Enterprise plans."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"install-reference-docs-cli","__idx":3},"children":["Install ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference-docs"]}," CLI"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To obtain a license key, refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/guides/on-premise"},"children":["on-premise license key"]}," topic."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the CLI tool with npm:"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"npm install @redocly/reference-docs --global\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["or with yarn"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"yarn global add @redocly/reference-docs\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do not want to install the CLI tool, you can use ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b"},"children":["npx"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-static-documentation","__idx":4},"children":["Create static documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create static documentation, run this command:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"reference-docs build <path or url to api definition>\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This pre-renders static files into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly-static"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"advanced-customization-options","__idx":5},"children":["Advanced customization options"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"\nreference-docs build <api definition>\n\nbundle definition into zero-dependency HTML-file [aliases: bundle]\n\nPositionals:\n  definition  path or URL to your OpenAPI Definition or config\n\nOptions:\n  --help          Show help                                            [boolean]\n  --version       Show version number                                  [boolean]\n  --options       Redoc options, use dot notation, e.g. options.nativeScrollbars\n                  or pass JSON value e.g. --options '{\"nativeScrollbars\": true}'\n  -o, --output    Output dir                [string] [default: \"redocly-static\"]\n  --title         Page Title           [string] [default: \"Redoc documentation\"]\n  -u, --definition-url  API definition URL, URL for a download button,\n                  uses API definition URL by default                    [string]\n  -t, --template  Path to handlebars page template, see <https://git.io/vh8fP>\n                  for the example                                       [string]\n  -q, --query     Query params to use for downloading resources         [string]\n  --prefix-paths  Overwrite routingBasePath Redoc setting\n                                                          [string] [default: \"\"]\n  --from-folder   Render all OpenAPI definitions in the folder\n                                                          [string] [default: \"\"]\n  --group-by      JSON pointer to grouping property inside the definition, e.g.\n                  \"info.x-domain\"                         [string] [default: \"\"]\n  --serve         Serve build artifacts after bundle  [boolean] [default: false]\n  -p              Server port                           [number] [default: 3000]\n\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need version 1.1.3 or later for this to work."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"reference-docs --version\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-with-try-it-console-enabled","__idx":6},"children":["Example with Try It console enabled"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# sample Redocly configuration file\n\ntheme:\n  openapi:\n    licenseKey: <insert your license key>\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"reference-docs build openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"REDOCLY_LICENSE_KEY=<insert your license key> reference-docs build openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-json-theme-file","__idx":7},"children":["Example JSON theme file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add your custom theme settings to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.openapi.theme"]}," object in the Redocly configuration file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using Redocly CLI, you can pass one or more theming options to the CLI tool with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--options"]}," parameter. To make it more practical, you can also save your custom theme as a JSON file and pass it to the CLI tool with the same parameter, like in the following example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference-docs build example-openapi.yaml --options=theme.json"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example theme.json file"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"theme\": {\n    \"breakpoints\": {\n      \"small\": \"10rem\",\n      \"medium\": \"40rem\",\n      \"large\": \"85rem\"\n    },\n    \"colors\": {\n      \"primary\": {\n        \"main\": \"rgba(246, 20, 63, 1)\",\n        \"light\": \"rgba(246, 20, 63, 0.42)\"\n      },\n      \"success\": {\n        \"main\": \"rgba(28, 184, 65, 1)\",\n        \"light\": \"#81ec9a\",\n        \"dark\": \"#083312\",\n        \"contrastText\": \"#000\"\n      },\n      \"text\": {\n        \"primary\": \"rgba(0, 0, 0, 1)\",\n        \"secondary\": \"#4d4d4d\"\n      },\n      \"http\": {\n        \"get\": \"rgba(0, 200, 219, 1)\",\n        \"post\": \"rgba(28, 184, 65, 1)\",\n        \"put\": \"rgba(255, 187, 0, 1)\",\n        \"delete\": \"rgba(254, 39, 35, 1)\"\n      }\n    },\n    \"typography\": {\n      \"fontSize\": \"16px\",\n      \"fontFamily\": \"Fira Sans, Roboto, sans-serif\",\n      \"optimizeSpeed\": true,\n      \"smoothing\": \"antialiased\",\n      \"headings\": {\n        \"fontWeight\": \"bold\",\n        \"lineHeight\": \"1em\"\n      },\n      \"code\": {\n        \"fontWeight\": \"600\",\n        \"color\": \"rgba(92, 62, 189, 1)\",\n        \"wrap\": true\n      },\n      \"links\": {\n        \"color\": \"rgba(246, 20, 63, 1)\",\n        \"visited\": \"rgba(246, 20, 63, 1)\",\n        \"hover\": \"#fa768f\"\n      }\n    },\n    \"sidebar\": {\n      \"width\": \"300px\",\n      \"textColor\": \"#000000\"\n    },\n    \"rightPanel\": {\n      \"backgroundColor\": \"rgba(55, 53, 71, 1)\",\n      \"textColor\": \"#ffffff\"\n    }\n  }\n}\n","lang":"json"},"children":[]}]},"frontmatter":{"excludeFromSearch":true,"seo":{"title":"Use the Reference docs CLI tool"}},"tagList":["admonition"],"title":"Use the Reference docs CLI tool","lastModified":"2025-08-10T02:58:02.000Z"}