Install the CLI

Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site.

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 functionality, 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

1. Locate your repository

   1. Go to the Git settings page of your dashboard.
   2. 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 your repository

   Your own 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 GitHub for more information.

   Mintlify-hosted repository

   You can clone your repository as a private or public repository. Public repositories are visible to anyone who navigates to the repository URL. Private repositories are only visible to people in your organization.

   On the Git settings page of your dashboard, select Clone as private or Clone as public.

Install the CLI

Run the following command to install the CLI:

npm

npm i -g mint

Preview 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.

The local preview:

• Hot-reloads when you save changes to MDX files or docs.json
• Mirrors your production documentation’s appearance and functionality
• Validates your content and displays warnings for issues
• Works offline once initially loaded

Alternatively, if you do not want to install the CLI globally, you can run a one-time script:

npx mint dev

Using npx downloads and runs the CLI without installing it globally. This is useful for trying the CLI or running it in CI/CD environments, but mint dev is faster for regular development.

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:

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.

This is useful when:

• Port 3000 is already in use by another application
• You need to run multiple documentation sites simultaneously
• Your development environment requires specific ports

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

This significantly speeds up the development server startup time when you have large or multiple OpenAPI specifications. Your API documentation pages will show placeholder content instead of generated content.

Use this flag only during content development. Always test with OpenAPI processing enabled before deploying to ensure your API documentation renders correctly.

Preview as a specific group

If you use partial authentication 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:

mint dev --groups admin

This allows you to:

• Test group-specific content visibility
• Verify authentication rules work correctly
• Preview documentation as different user types
• Ensure restricted content displays properly for authorized groups

Create a new project

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

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.

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

The starter kit includes:

• Pre-configured docs.json with common settings
• Sample MDX pages demonstrating components and formatting
• Example navigation structure
• Basic styling and theme configuration
• Ready-to-use folder structure

You can run mint new with the following flags:

• --theme: Set the theme of the new project (options: quill, linden, venus, petal).
• --name: Set the name of the new project.
• --force: Overwrite the current directory if it already exists.

For example, to create a new project in the docs directory with the name my-project and the theme linden, run the following command:

mint new docs --name my-project --theme linden

After creating a new project, run mint dev in the project directory to preview your documentation and start customizing it.

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:

mint update

You should update the CLI when:

• Your local preview doesn’t match production
• New features or components aren’t rendering locally
• You encounter unexpected errors or warnings
• Release notes mention CLI updates

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

npm

npm i -g mint@latest

Check for CLI updates regularly to ensure you have the latest features and bug fixes. Run mint --version to see your current version.

Additional commands

Find broken links

Identify any broken internal links with the following command:

mint broken-links

The command ignores files matching .mintignore patterns. Links that point to ignored files are reported as broken.

This is useful for:

• Catching broken links before deploying to production
• Identifying outdated references after restructuring your documentation
• Ensuring all navigation items point to valid pages

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:

mint a11y

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

The accessibility checker helps you:

• Meet WCAG 2.1 AA standards for color contrast
• Ensure all images and videos have descriptive alt text
• Improve documentation usability for users with visual impairments
• Identify accessibility issues before they reach production

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).

This command validates:

• OpenAPI specification syntax and structure
• Required fields and proper formatting
• Schema definitions and references
• Compatibility with Mintlify’s API documentation features

Use this before deploying to catch specification errors early and ensure your API documentation renders correctly.

Rename files

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

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

This command automatically:

• Renames the specified file
• Updates all internal links pointing to the old filename
• Updates navigation references in docs.json
• Preserves your documentation’s link integrity

This is safer than manually renaming files, which can break internal links and navigation.

Migrate MDX endpoint pages

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

mint migrate-mdx

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.

Benefits of migration:

• Automatically sync API documentation with your OpenAPI spec
• Reduce manual maintenance of endpoint documentation
• Ensure consistency between your API spec and documentation
• Keep custom content while leveraging auto-generation

Get CLI version

Check your current CLI version with the following command:

mint --version

Use this to verify you’re running the latest version or when troubleshooting issues.

Get help

View all available commands and options with the following command:

mint --help

For help with a specific command, use:

mint <command> --help

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

Error: Could not load the "sharp" module using the darwin-arm64 runtime

This may be due to an outdated version of node. Try the following:

1. Remove the currently-installed version of the mint CLI: npm uninstall -g mint
2. Upgrade to Node.js.
3. Reinstall the mint CLI: npm install -g mint

Issue: Encountering an unknown error

Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run mint dev again.

Error: permission denied

This is due to not having the required permissions to globally install node packages.

Solution: Try running sudo npm i -g mint. You will be prompted for your password, which is the one you use to unlock your computer.

The local preview doesn't look the same as my docs do on the web

This is likely due to an outdated version of the CLI.

Solution: Run mint update to get the latest changes.

mintlify vs. mint package

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

2. Clear your npm cache:

  npm cache clean --force

3. Reinstall the new package:

npm i -g mint