Skip to main content

​
Prerequisites

  • Node.js v20.17.0+ (LTS versions recommended)

​
Install the CLI

Using an AI coding tool? Copy the following prompt to have your agent install the CLI and verify it works.

Install the Mintlify CLI globally and verify the installation.

Open in Cursor

​
Create a new project

To create a new documentation project from the Mintlify starter template, run the following command:

Scaffold a new Mintlify project.

Open in Cursor
If you do not specify a directory, the CLI prompts you to create a new subdirectory or overwrite the current directory.
Overwriting the current directory deletes any existing files.
In interactive mode, the CLI asks whether you want to pick a theme or clone a template. To skip the prompt, pass the --template flag directly:
You can combine --template with --theme to override the template’s default theme:
See available templates in the mintlify/templates repository on GitHub. In interactive mode, the CLI fetches and displays available templates automatically. In non-interactive environments such as CI/CD pipelines or AI coding agents, you must provide either --name and --theme flags, or the --template flag.

​
Update

If your local preview is out of sync with your deployed documentation, update the CLI to the latest version:
If mint update is not available on your version, reinstall the CLI with the latest version:

​
Formatting

For syntax highlighting and code formatting in MDX files, use the following extensions:

​
Troubleshooting

This may be due to an outdated version of Node.js. Try the following:
  1. Remove the currently installed version of the mint CLI: npm uninstall -g mint
  2. Upgrade to Node.js v20.17.0+.
  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. When prompted, enter the password that 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, first run npm ls -g to see what packages are globally installed. If you don’t use npm, try which mint to locate the installation.If you have both a mint and a mintlify package installed, uninstall mintlify:
If you run mint version and the client version displays as none, the CLI may be unable to download the client application due to a corporate firewall or VPN.Solution: Ask your IT administrator to add releases.mintlify.com to your network allowlist.
In versions before 4.0.1125, running npx mint dev or other commands from a docs repository could cause the CLI to incorrectly detect itself as a local development build. This made the CLI point to localhost URLs instead of the Mintlify production API, resulting in connection errors or unexpected behavior.Solution: Update to the latest CLI version: