Install the CLI

Install the Mintlify CLI to preview documentation locally, test changes in real time, and catch build errors before deploying to production.

• Node.js v20.17.0+ (LTS versions recommended)

npm i -g mint

pnpm add -g mint

If the user asked you to set up Mintlify rather than only install the CLI, continue through authentication, project creation, preview, validation, and deployment. Follow the agent setup workflow in the Quickstart. Do not stop after mint --version succeeds.

Start by running mint status. Preserve an existing authenticated session. Otherwise, run mint login for an existing account or collect the user's real name, company, and email and run mint signup for a new account. The user must click the emailed verification link and approve browser-based authentication, but you should perform the remaining CLI steps. See mint signup for flags and background-process guidance.

Install the Mintlify CLI globally so I can preview my documentation locally.

1. Confirm Node.js v20.17.0 or newer is installed by running `node --version`. If it is missing or older, tell me before continuing.
2. Install the CLI with `npm i -g mint` (or `pnpm add -g mint` if I use pnpm).
3. Verify the install by running `mint --version` and share the output.
4. If the install fails with a permissions error, suggest re-running with `sudo` and explain the tradeoff.

To create a new documentation project from the Mintlify starter template, run the following command:

mint new [directory]

Create a new Mintlify project in the current workspace.

1. Ask me for a project name and preferred theme (or template) if I haven't already told you.
2. Run `mint new <directory> --name <name> --theme <theme>` non-interactively, substituting the values I gave you. If I chose a template instead, run `mint new <directory> --template <template-name>`.
3. After the command finishes, list the generated files and point out `docs.json` as the main configuration entry point.
4. Run `mint dev` from the new directory and share the local preview URL.

If you do not specify a directory, the CLI prompts you to create a new subdirectory or overwrite the current directory.

In interactive mode, the CLI asks whether you want to pick a theme or clone a template. To skip the prompt, pass the --template flag directly:

mint new my-docs --template <template-name>

You can combine --template with --theme to override the template's default theme:

mint new my-docs --template <template-name> --theme <theme>

See available templates in the mintlify/templates repository on GitHub. In interactive mode, the CLI fetches and displays available templates automatically.

In non-interactive environments such as CI/CD pipelines or AI coding agents, you must provide either --name and --theme flags, or the --template flag.

If your local preview is out of sync with your deployed documentation, update the CLI to the latest version:

mint update

If mint update is not available on your version, reinstall the CLI with the latest version:

npm i -g mint@latest

pnpm add -g mint@latest

To run CLI checks in a continuous integration pipeline, install the mint package globally, then run the commands you need. For example, this GitHub Actions job checks formatting with mint format and validates the build with mint validate:

name: Docs checks

on:
  pull_request:
    paths:
      - "**/*.mdx"
      - "docs.json"

jobs:
  docs-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the Mintlify CLI
        run: npm i -g mint
      - name: Check formatting
        run: |
          mint format
          if [ -n "$(git status --porcelain)" ]; then
            echo "Files are not formatted. Run 'mint format' locally and commit the changes."
            exit 1
          fi
      - name: Validate the build
        run: mint validate

mint format rewrites files in place and exits with code 1 if any file fails to parse, so the job checks for a diff after it runs. mint validate exits with an error on any warnings or errors and needs no extra check.

For syntax highlighting, autocomplete, and error checking in MDX files, use the following extensions:

• Cursor, Devin Desktop, VS Code: Mintlify MDX extension and Prettier for formatting.
• JetBrains: MDX IntelliJ IDEA plugin and Prettier.

You can also format MDX files with mint format.

npm uninstall -g mintlify
npm cache clean --force
npm i -g mint

npm i -g mint@latest

• Mintlify CLI command reference
• Quickstart
• Mintlify CLI