Skip to main content
Prerequisites:
  • Node.js version 19 or higher
  • A docs repository with a docs.json file
Follow these steps to install and run Mintlify on your operating system.
1

Install the Mintlify CLI

npm i -g mint
2

Run from the docs folder (recommended)

From the docs directory (where mint.json is located), install and run:
cd docs
npm install
npm run broken-links   # Validate links
npm run dev            # Preview locally (fetches latest OpenAPI from api.truedy.ai)
A local preview will be available at http://localhost:3000 and will use the latest API reference from https://api.truedy.ai/api/public/v1/openapi.json.
3

Or preview with global CLI

Navigate to your docs directory where your mint.json file is located, and run:
mint dev
A local preview of your documentation will be available at http://localhost:3000.

​
Custom ports

By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the --port flag. For example, to run Mintlify on port 3333, use this command: 
mint dev --port 3333
If you attempt to run Mintlify on a port that’s already in use, it will use the next available port: 
Port 3000 is already in use. Trying 3001 instead.

​
Mintlify versions

Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI: 
npm mint update
The CLI can assist with validating links in your documentation. To identify any broken links, use the following command: 
mint broken-links

​
Deployment

If the deployment is successful, you should see the following:
Screenshot of a deployment confirmation message that says All checks have passed.

​
Code formatting

We suggest using extensions on your IDE to recognize and format MDX. If you’re a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

​
Troubleshooting

This may be due to an outdated version of node. Try the following:
  1. Remove the currently-installed version of the CLI: npm remove -g mint
  2. Upgrade to Node v19 or higher.
  3. Reinstall the CLI: npm i -g mint
Solution: Go to the root of your device and delete the ~/.mintlify folder. Then run mint dev again.
Curious about what changed in the latest CLI version? Check out the CLI changelog.