Prerequisite: Please install Node.js (version 19 or higher) before proceeding.

Step 1: Install the Mintlify CLI:

npm i -g mintlify

Step 2: Navigate to the docs directory (where the docs.json file is located) and execute the following command:

mintlify dev

Alternatively, if you do not want to install the CLI globally, you can use a run a one-time script:

npx mintlify dev

A local preview of your documentation will be available at http://localhost:3000.

​
Updates

Each CLI release is associated with a specific version of Mintlify. If your local preview doesn’t align with the production version, please update the CLI:

npm i -g mintlify@latest

​
Custom Ports

By default, the CLI uses port 3000. You can customize the port using the --port flag. To run the CLI on port 3333, for instance, use this command:

mintlify dev --port 3333

If you attempt to run on a port that’s already in use, it will use the next available port:

Port 3000 is already in use. Trying 3001 instead.

​
Additional Commands

While mintlify dev is the most commonly used command, there are other commands you can use to manage your documentation.

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:

mintlify broken-links

​
Check OpenAPI Spec

You can use the CLI to check your OpenAPI file for errors using the following command:

mintlify openapi-check <openapiFilenameOrUrl>

You can pass in a filename (e.g. ./openapi.yaml) or a URL (e.g. https://petstore3.swagger.io/api/v3/openapi.json).

​
Renaming Files

You can rename files using the following command:

mintlify rename <oldFilename> <newFilename>

This is an improvement over updating the filename normally as it will also update all references to the file, ensuring no broken links.

​
Formatting

While developing locally, we recommend using extensions on your IDE to recognize and format MDX.

If you use Cursor, Windsurf, or VSCode, we recommend the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

If you use JetBrains, we recommend the MDX IntelliJ IDEA plugin for syntax highlighting, and setting up Prettier for code formatting.

​
Troubleshooting