CLI installation

Install the CLI to preview and develop your docs locally

Installing the CLI

Prerequisite: Please install Node.js before proceeding.

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.

Additional commands

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

Finding broken links

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

mint broken-links

Checking OpenAPI spec

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

mint 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 and update all references to files using the following command:

mint rename <oldFilename> <newFilename>

Formatting

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

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

Error: Could not load the "sharp" module using the darwin-arm64 runtime

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

Issue: Encountering an unknown error

Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run mint dev again.

Error: permission denied

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.

The local preview doesn't look the same as my docs do on the web

This is likely due to an outdated version of the CLI.

Solution: Run mint update to get the latest changes.

mintlify vs. mint package

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 have a package named mint and a package named mintlify installed, you should uninstall mintlify.

1. Uninstall the old package:

  npm uninstall -g mintlify

2. Clear your npm cache:

  npm cache clean --force

3. Reinstall the new package:

  npm install -g mint