{"id":17811,"library":"mint","title":"Mintlify CLI","description":"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.","status":"active","version":"4.2.527","language":"javascript","source_language":"en","source_url":"https://github.com/mintlify/mint","tags":["javascript","mintlify","mint","cli"],"install":[{"cmd":"npm install mint","lang":"bash","label":"npm"},{"cmd":"yarn add mint","lang":"bash","label":"yarn"},{"cmd":"pnpm add mint","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { mint } from 'mint'","symbol":"mint","correct":"Install globally via npm: `npm i -g mint`. Then use from command line: `mint <command>`"},{"note":"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.","wrong":"const project = new MintlifyProject()","symbol":"Mintlify Project Interaction","correct":"Interact with Mintlify projects via CLI commands like `mint dev` or `mint validate`."},{"note":"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.","wrong":"import { dev } from 'mint'; dev({ port: 3000 });","symbol":"CLI Commands","correct":"Execute specific commands directly in the terminal: `mint dev`, `mint validate`, `mint broken-links`, etc."}],"quickstart":{"code":"{\n// 1. Install the Mintlify CLI globally\n// npm i -g mint\n\n// 2. Navigate to your desired project directory (or create a new one)\n// cd my-new-docs\n\n// 3. Initialize a new Mintlify documentation site\n// mint new\n\n// 4. Start the local development server to preview your documentation\n// This command will open your documentation in a browser at http://localhost:3000 by default.\n// Use --port <number> to specify a different port or --no-open to prevent automatic browser opening.\n// mint dev --port 3333\n\n// 5. To validate your documentation for CI/CD, run:\n// mint validate\n\n// 6. To check for broken internal links:\n// mint broken-links --check-external --check-anchors\n}","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"For comprehensive link checking, always include the relevant flags, e.g., `mint broken-links --check-external --check-anchors --check-snippets`.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`).","cause":"Common causes include an incorrect Node.js version, a missing `docs.json` file in the current directory, or an outdated CLI version.","error":"mint dev is not working"},{"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.","cause":"The `mint` CLI is not installed globally or its installation path is not included in your system's PATH environment variable.","error":"Command not found: mint"},{"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`.","cause":"Running the CLI with an unsupported Node.js version.","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+."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}