Skip to main content
Decorative graphic representing the CLI. Use the CLI to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site’s appearance and functionality, and catch issues like broken links or accessibility problems. The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats.

​
Install the CLI

Prerequisite: The CLI requires Node.js v19 or higher.
1

Install the CLI

Run the following command to install the CLI:
npm i -g mint
2

Preview locally

Navigate to your docs directory (where your docs.json file is located) and execute the following command:
mint dev
A local preview of your documentation will be available at http://localhost:3000.
Alternatively, if you do not want to install the CLI globally, you can run a one-time script: 
npx mint dev

​
Updates

If your local preview is out of sync with what you see on the web in the production version, update your local CLI: 
mint update
If this mint update command is not available on your local version, re-install the CLI with the latest version: 
npm i -g mint@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: 
mint dev --port 3333
If you attempt to run on a port that is already in use, it will use the next available port: 
Port 3000 is already in use. Trying 3001 instead.

​
Preview as a specific group

If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the --groups [groupname] flag. For example, if you have a group named admin, you can preview as a member of that group with the command: 
mint dev --groups admin

​
Additional commands

Identify any broken internal links with the following command: 
mint broken-links

​
Find accessibility issues

Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command: 
mint a11y

​
Check OpenAPI spec

Check your OpenAPI file for errors with the following command: 
mint openapi-check <OpenAPI filename or URL>
Pass a filename (for example, ./openapi.yaml) or a URL (for example, https://petstore3.swagger.io/api/v3/openapi.json).

​
Rename files

Rename and update all references to files with the following command: 
mint rename <path/to/old-filename> <path/to/new-filename>

​
Migrate MDX endpoint pages

Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: 
mint migrate-mdx
This command converts individual MDX endpoint pages to autogenerated pages defined in your docs.json, moves MDX content to the x-mint extension in your OpenAPI specification, and updates your navigation. See Migrating from MDX for detailed information.

​
Formatting

While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. If you use Cursor, Windsurf, or VS Code, we recommend the MDX VS Code 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

This may be due to an outdated version of node. Try the following:
  1. Remove the currently-installed version of the mint CLI: npm uninstall -g mint
  2. Upgrade to Node.js.
  3. Reinstall the mint CLI: npm install -g mint
Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run mint dev again.
This is due to not having the required permissions to globally install node packages.Solution: Try running sudo npm i -g mint. You will be prompted for your password, which is the one you use to unlock your computer.
This is likely due to an outdated version of the CLI.Solution: Run mint update to get the latest changes.
If you have any problems with the CLI package, you should first run npm ls -g. This command shows what packages are globally installed on your machine.If you don’t use npm or don’t see it in the -g list, try which mint to locate the installation.If you have a package named mint and a package named mintlify installed, you should uninstall mintlify.
  1. Uninstall the old package:
  npm uninstall -g mintlify
  1. Clear your npm cache:
  npm cache clean --force
  1. Reinstall the new package:
npm i -g mint
⌘I