Mintlify CLI

4.2.531 verified Sat Apr 25 auth: no javascript

Command-line interface for building and previewing Mintlify documentation sites. v4.2.531 requires Node >=18 (20.17+ recommended, Node 25+ unsupported). Released ~weekly by Mintlify. Differentiates from other doc tools via cloud-hosted platform with built-in analytics, search, and design; the CLI provides local preview, validation, broken link checking, accessibility checks, and OpenAPI validation.

Common errors

error Error: Must be run in a folder with a docs.json file. ↓

cause 'mintlify dev' executed in a directory without a Mintlify project.

fix

Change to the correct project root that contains docs.json.

error Error: The port 3000 is already in use. Trying next port. ↓

cause Default port 3000 occupied by another process.

fix

Use 'mintlify dev --port <available-port>' to specify a free port.

error Error: Node.js version 25.x is not supported. Please use Node 20.17 or higher, but not 25+. ↓

cause Running Node 25+ which is not supported by Mintlify CLI v4.2.531.

fix

Install Node 20.17 or 22.x LTS via nvm or your system package manager.

error Error: openapi-check: Cannot find module '/path/to/openapi.yaml' ↓

cause The file path provided to 'mintlify openapi-check' does not exist or is incorrect.

fix

Provide an absolute or correct relative path to the OpenAPI spec file.

Warnings

breaking Requires Node 20.17 or higher. Node 25+ is not supported. ↓

fix Use Node 20.17 or 22.x LTS. Avoid Node 25+.

gotcha Running in a folder without a docs.json file will cause 'mintlify dev' to fail. ↓

fix Ensure you run the command in a Mintlify project root that contains a docs.json file.

gotcha If the specified port is already in use, the CLI automatically tries the next available port, which may be unexpected. ↓

fix Use --port to specify a free port explicitly, or check which port the server actually started on.

deprecated The old 'mintlify scripts' command is deprecated in favor of 'mintlify dev' or other subcommands. ↓

fix Use 'mintlify dev' for local preview.

gotcha After updating Mintlify CLI, you may need to run 'mintlify update' to get the latest version; the installed global version may not auto-update. ↓

fix Run 'mintlify update' or reinstall with 'npm i -g mintlify@latest'.

breaking The '--groups' flag for mock user groups is case-sensitive and must match exactly the group names in your docs.json. ↓

fix Check the exact casing of user groups in your project configuration.

Install

npm install mintlify

yarn add mintlify

pnpm add mintlify

Quickstart

Install globally, start a local dev server on port 3333, validate docs, and run various checks.

npm i -g mintlify
cd /path/to/mintlify-project
mintlify dev --port 3333
# Opens http://localhost:3333 in browser
mintlify validate
mintlify broken-links --check-external --check-anchors
mintlify openapi-check ./openapi.yaml