Mintlify CLI

4.2.527 verified Thu Apr 23 auth: no javascript

The `mint` package provides the official Command Line Interface (CLI) for Mintlify, a platform for building and publishing documentation. It enables developers to scaffold new documentation sites, preview changes locally, validate documentation builds in strict mode (useful for CI/CD), check for broken internal and external links, validate OpenAPI specifications, and perform accessibility audits. The current stable version is 4.2.527. As a CLI tool, its release cadence is typically tied to the evolution of the Mintlify platform itself, receiving regular updates to support new features and address issues. Key differentiators include its tight integration with the Mintlify ecosystem, specialized commands for documentation validation (e.g., `broken-links`, `openapi-check`, `a11y`), and a streamlined local development workflow with `mint dev`. It is designed for direct command-line execution rather than programmatic import.

Common errors

error mint dev is not working ↓

cause Common causes include an incorrect Node.js version, a missing `docs.json` file in the current directory, or an outdated CLI version.

fix

1. Verify docs.json exists in the current directory. 2. Run mint update to get the latest CLI. 3. Ensure your Node.js version is 20.17 or higher (but not 25+). 4. Delete the contents of the .mintlify folder in your home directory (~/.mintlify).

error Command not found: mint ↓

cause The `mint` CLI is not installed globally or its installation path is not included in your system's PATH environment variable.

fix

Install the CLI globally using npm i -g mint. If it's already installed, ensure your system's PATH environment variable includes the npm global binaries directory.

error Node.js vX.Y.Z is not supported by the Mintlify CLI. Please use Node.js version 20.17 or higher, but not 25+. ↓

cause Running the CLI with an unsupported Node.js version.

fix

Install and switch to a supported Node.js LTS version (e.g., Node.js 20 or 22) using a version manager like nvm or fnm. Example: nvm install 20 && nvm use 20.

Warnings

breaking Strict Node.js version requirements are enforced. The CLI requires Node.js version 20.17 or higher. Node.js versions 18.x and earlier, as well as Node.js 25 and newer, are explicitly not supported. Using an unsupported Node.js version may lead to unexpected errors or complete failure of CLI commands. ↓

fix Ensure your development environment uses Node.js LTS versions between 20.17 and 24.x. Use `nvm` or `fnm` to manage Node.js versions and switch to a supported version: `nvm install 20 && nvm use 20` or `nvm install 22 && nvm use 22`.

gotcha The `mint dev` command and other validation commands (like `mint validate`) require being run within a directory that contains a `docs.json` file, which signifies the root of a Mintlify project. Running these commands outside a valid project directory will cause them to fail or not function as expected. ↓

fix Ensure you are in the root directory of your Mintlify project before running commands like `mint dev`. If starting a new project, use `mint new` first.

gotcha The `mint broken-links` command by default only checks internal links within the project. To include checks for external URLs, anchor links (like `#section`), or links within `<Snippet>` components, you must explicitly enable these checks using the `--check-external`, `--check-anchors`, and `--check-snippets` flags, respectively. ↓

fix For comprehensive link checking, always include the relevant flags, e.g., `mint broken-links --check-external --check-anchors --check-snippets`.

Install

npm install mint

yarn add mint

pnpm add mint

Imports

mint
wrong
```
import { mint } from 'mint'
```
correct
```
Install globally via npm: `npm i -g mint`. Then use from command line: `mint <command>`
```
The `mint` package is a global Command Line Interface (CLI) tool and is not intended for programmatic import into JavaScript/TypeScript applications. It is installed globally and executed directly from the terminal. Attempting to import it will result in runtime errors.
Mintlify Project Interaction
wrong
```
const project = new MintlifyProject()
```
correct
```
Interact with Mintlify projects via CLI commands like `mint dev` or `mint validate`.
```
The CLI operates on a Mintlify project structure on the filesystem (e.g., finding `docs.json`). There is no exposed JavaScript API within the `mint` package for programmatically interacting with or creating Mintlify projects from within your own code.
CLI Commands
wrong
```
import { dev } from 'mint'; dev({ port: 3000 });
```
correct
```
Execute specific commands directly in the terminal: `mint dev`, `mint validate`, `mint broken-links`, etc.
```
Individual commands like `dev`, `validate`, `broken-links`, etc., are subcommands of the `mint` CLI. They are invoked as `mint <command>` in the terminal and are not exposed as individual functions or objects for direct programmatic import.

Quickstart

Demonstrates how to install the Mintlify CLI globally, initialize a new documentation project, run a local development preview server on a custom port, and perform basic documentation validation and link checking.

{
// 1. Install the Mintlify CLI globally
// npm i -g mint

// 2. Navigate to your desired project directory (or create a new one)
// cd my-new-docs

// 3. Initialize a new Mintlify documentation site
// mint new

// 4. Start the local development server to preview your documentation
// This command will open your documentation in a browser at http://localhost:3000 by default.
// Use --port <number> to specify a different port or --no-open to prevent automatic browser opening.
// mint dev --port 3333

// 5. To validate your documentation for CI/CD, run:
// mint validate

// 6. To check for broken internal links:
// mint broken-links --check-external --check-anchors
}