Skip to main content
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 features, 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.

​
System requirements

Before installing the CLI, ensure your system meets these requirements:

Node.js

Version 20.17.0 or higher (LTS versions recommended)

Git

Git installed for repository management
Need to install Node.js? Download it from nodejs.org. We recommend using an LTS (Long Term Support) version for stability.

​
Clone your repository

Before using the CLI, clone your documentation repository locally:
1

Locate your repository

Go to the Git settings page of your dashboard.Note your repository location. It is one of these formats:
  • mintlify-community/docs-{org-name}-{id} (Mintlify-hosted repository)
  • your-org/your-repo (your own GitHub repository)
2

Clone the repository

Replace your-org/your-repo with your actual repository details from Git settings.
git clone https://github.com/your-org/your-repo
cd your-repo
GitHub App required. To enable automatic deployments when you push changes, you must install the GitHub app. See the deployment documentation for more information.

​
Install the CLI

Install the Mintlify CLI globally using your preferred package manager: 
npm i -g mint
If you encounter permission errors on macOS or Linux, try running the command with sudo: sudo npm i -g mint

​
Preview your docs locally

Navigate to your documentation directory containing your docs.json file and run: 
mint dev
A local preview of your documentation is available at http://localhost:3000.
Changes you make to your documentation files automatically refresh in the browser. No need to restart the development server.
Alternatively, if you do not want to install the CLI globally, you can run a one-time script: 
npx mint dev

​
Custom ports

By default, the CLI uses port 3000. You can customize the port using the --port flag: 
mint dev --port 3333
If you attempt to run on a port that is already in use, the CLI uses the next available port: 
Port 3000 is already in use. Trying 3001 instead.

​
Skip OpenAPI processing

If you have many OpenAPI files, skip OpenAPI file processing during local development to improve performance: 
mint dev --disable-openapi

​
Preview as a specific group

If you use group-based access control to restrict access to your documentation, you can preview as a specific authentication group: 
mint dev --groups admin

​
Update the CLI

Keep your CLI up to date to ensure your local preview matches your production site: 
mint update
If the mint update command is not available on your local version, reinstall the CLI with the latest version: 
npm i -g mint@latest

​
Additional CLI commands

The CLI includes several utilities to help maintain and validate your documentation: Identify broken links in your documentation: 
mint broken-links
The command ignores files matching .mintignore patterns. Links that point to ignored files are reported as broken. By default, only internal links are checked. Use flags to expand the scope:
FlagDescription
--check-anchorsAlso validate anchor links (for example, /page#section) against heading slugs
--check-externalAlso check external links for broken URLs
--check-snippetsAlso check links inside <Snippet> components

​
Find accessibility issues

Test the color contrast ratios and search for missing alt text on images and videos: 
mint a11y
Use flags to check for specific accessibility issues: 
mint a11y --skip-contrast

​
Validate documentation build

Validate your documentation build in strict mode, which exits with an error if there are any warnings or errors: 
mint validate
This command is useful for CI/CD pipelines to prevent broken documentation deployments. Available flags:
  • --groups [groupname]: Mock user groups for validation (useful when testing group-based access control)
  • --disable-openapi: Disable OpenAPI file generation during validation

​
Check OpenAPI spec

Check your OpenAPI file for errors: 
mint openapi-check <OpenAPI filename or URL>
Pass a filename or a URL: 
mint openapi-check ./openapi.yaml

​
Rename files

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

​
Create a new project

Create a new documentation project from the starter template: 
mint new [directory]
This command clones the starter kit into a specified directory. If you do not specify a directory, the CLI tool prompts you to create a new subdirectory or overwrite the current directory.
Overwriting the current directory deletes any existing files.

​
Flags for non-interactive environments

When running mint new in non-interactive environments like CI/CD pipelines or with AI coding agents, you must provide all required flags:
FlagDescriptionRequired
--nameSet the name of the new projectYes
--themeSet the theme of the new projectYes
--forceOverwrite the current directory without promptingNo
The CLI automatically detects non-interactive environments. If required flags are missing, it outputs usage instructions instead of hanging on prompts.

​
Development tools

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

​
VS Code / Cursor / Windsurf

MDX VS Code extension

Syntax highlighting for MDX files

Prettier

Code formatting for consistent style
Install from the VS Code marketplace:

​
JetBrains IDEs

MDX IntelliJ IDEA plugin

Syntax highlighting for MDX files

Prettier

Code formatting for consistent style
Install the MDX IntelliJ IDEA plugin and set up Prettier for code formatting.

​
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 or higher
  3. Reinstall the mint CLI: npm install -g mint
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, 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
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 blocking the download.Solution: Ask your IT administrator to add releases.mintlify.com to your network allowlist to enable local development with the CLI.

​
Next steps

Start building

Now that you have the CLI installed, follow the quickstart guide to create your first documentation site.

Build docs developers (and LLMs) love

Get started for freeTalk to us