Skip to main content
Prerequisites
  • Node.js version 19 or higher
  • A documentation repository with a docs.json configuration file

​
Install and run Mintlify

Follow these steps to get the Mintlify CLI running on your local machine.
1

Install the Mintlify CLI

Install the CLI globally using npm:
npm i -g mint
This makes the mint command available from anywhere on your system.
2

Start local preview

Navigate to your documentation directory (where your docs.json file is located) and run:
mint dev
Your documentation will be available at http://localhost:3000.
The preview server automatically reloads when you save changes to your files. No manual refresh needed!

​
Advanced configuration

​
Custom ports

By default, Mintlify runs on port 3000. You can specify a different port using the --port flag: 
mint dev --port 3333
If the specified port is already in use, Mintlify automatically tries the next available port: 
Port 3000 is already in use. Trying 3001 instead.
This automatic port selection ensures you can always preview your docs, even if other services are running.

​
Keeping Mintlify up to date

Each CLI release corresponds to a specific Mintlify version. If your local preview doesn’t match production, update the CLI: 
npm mint update
Running outdated CLI versions may cause rendering differences between local and production environments.
The CLI includes a built-in link checker to identify broken links in your documentation: 
mint broken-links
This command:
  • Scans all pages in your documentation
  • Checks internal links between pages
  • Validates external URLs
  • Reports any broken or unreachable links
Run this command before deploying to catch broken links early and maintain documentation quality.

​
Deployment verification

When you push changes to your repository, the Mintlify GitHub app handles deployment automatically. A successful deployment shows:
Screenshot showing deployment confirmation: All checks have passed
You can monitor deployment status in your repository’s Actions tab on GitHub.

​
Development tools

​
Code formatting and syntax

We recommend using IDE extensions for the best MDX development experience:

MDX syntax highlighting

Install the MDX VSCode extension for syntax highlighting and IntelliSense.

Code formatting

Use Prettier to automatically format MDX files on save.

​
Troubleshooting

Common issues and solutions when working with the Mintlify CLI:
This error typically occurs with outdated Node.js versions. To fix it:
1

Remove the current CLI

npm remove -g mint
2

Upgrade Node.js

Upgrade to Node.js version 19 or higher. We recommend using nvm to manage Node versions:
nvm install 20
nvm use 20
3

Reinstall the CLI

npm i -g mint
If you encounter unexpected errors or the CLI behaves erratically:
  1. Navigate to your home directory root
  2. Delete the ~/.mintlify folder:
rm -rf ~/.mintlify
  1. Run mint dev again to regenerate the configuration
This resets your local Mintlify cache. Your documentation content remains unchanged.
If your edits aren’t reflected in the preview:
  1. Check that you’re editing files in the correct directory
  2. Ensure you saved the file (check for unsaved indicators in your editor)
  3. Try stopping the server (Ctrl+C) and running mint dev again
  4. Clear your browser cache and refresh the page
If you see port-related errors:
  • Specify a different port: mint dev --port 4000
  • Or stop the process using port 3000 and try again
  • Use lsof -i :3000 (macOS/Linux) to identify what’s using the port

​
Stay updated

Curious about what changed in the latest CLI version? Check out the CLI changelog on npm to see new features, bug fixes, and improvements.

​
Next steps

Write your first page

Learn how to create documentation pages using MDX and Mintlify components.

Customize navigation

Structure your documentation with groups, tabs, and navigation links.

Build docs developers (and LLMs) love

Get started for freeTalk to us