Install the CLI - Mintlify

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.

Prerequisites

• Node.js v20.17.0+ (LTS versions recommended) installed
• Git installed
• Your documentation repository cloned locally

Clone your repository

Run the following command to install the CLI:

Preview locally

Navigate to your documentation directory containing your docs.json file and run:

A local preview of your documentation is available at http://localhost:3000. Alternatively, if you do not want to install the CLI globally, you can run a one-time script:

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:

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 by using the --disable-openapi flag:

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 by using the --groups [groupname] flag. For example, if you have a group named admin, you can preview as a member of that group with the command:

Create a new project

To create a new documentation project, run the following command:

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.

The CLI tool prompts you for a project name and theme to finish setting up your project.

Flags

When running mint new in non-interactive environments like CI/CD pipelines or with AI coding agents, you must provide all required flags (--name and --theme).

Update the CLI

If your local preview is out of sync with what you see on the web in the production version, update your local CLI:

If this mint update command is not available on your local version, re-install the CLI with the latest version:

Additional commands

Find broken links

Identify any broken internal links with the following command:

The command ignores files matching .mintignore patterns. Links that point to ignored files are reported as broken. To also check anchor links like /path/to/page#anchor, use the --check-anchors flag:

mint broken-links --check-anchors

Find accessibility issues

Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command:

Use flags to check for specific accessibility issues.

# Check only for missing alt text
mint a11y --skip-contrast

# Check only for color contrast issues
mint a11y --skip-alt-text

Validate documentation build

Validate your documentation build in strict mode, which exits with an error if there are any warnings or errors. Use this command for CI/CD pipelines to prevent broken documentation deployments.

Use flags to configure the validation command.

• --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 with the following command:

mint openapi-check <OpenAPI filename or URL>

Pass a filename (for example, ./openapi.yaml) or a URL (for example, https://petstore3.swagger.io/api/v3/openapi.json).

Rename files

Rename and update all references to files with the following command:

mint rename <path/to/old-filename> <path/to/new-filename>

Migrate MDX endpoint pages

Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:

This command converts individual MDX endpoint pages to autogenerated pages defined in your docs.json, moves MDX content to the x-mint extension in your OpenAPI specification, and updates your navigation. See Migrating from MDX for detailed information.

Formatting

While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. If you use Cursor, Windsurf, or VS Code, we recommend the MDX VS Code 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