# Install the CLI (/cli/install)

<!-- agent-signals: reading_time_min: 5 · est_tokens: 1897 · updated: 2026-07-30 -->
Related: [Preview locally](/cli/preview.md), [Mintlify CLI command reference](/cli/commands.md), [Quickstart](/quickstart.md)

## Prerequisites [#prerequisites]

* [Node.js](https://nodejs.org/en) v20.17.0+ (LTS versions recommended)

## Install the CLI [#install-the-cli]

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Tip>
  Using an AI coding tool? Copy the following prompt to have your agent install the CLI and verify it works.
</Tip>

{/* vale off */}

<Prompt description="Install the Mintlify CLI globally and verify the installation." actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  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.
</Prompt>

{/* vale on */}

## Create a new project [#create-a-new-project]

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

```bash
mint new [directory]
```

{/* vale off */}

<Prompt description="Scaffold a new Mintlify project." actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  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.
</Prompt>

{/* vale on */}

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

<Warning>
  Overwriting the current directory deletes any existing files.
</Warning>

| Flag         | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `--name`     | Project name. The CLI prompts for this if not provided.                       |
| `--theme`    | Project [theme](/customize/themes). The CLI prompts for this if not provided. |
| `--template` | Pre-defined template. The CLI prompts for this if not provided.               |
| `--force`    | Overwrite the current directory without prompting.                            |

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:

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

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

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

See available templates in the [mintlify/templates](https://github.com/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.

## Update [#update]

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

```bash
mint update
```

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

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint@latest
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint@latest
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Formatting [#formatting]

For syntax highlighting and code formatting in MDX files, use the following extensions:

* **Cursor, Devin Desktop, VS Code**: [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
* **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm)

## Troubleshooting [#troubleshooting]

<AccordionGroup>
  <Accordion title="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
    This may be due to an outdated version of Node.js. Try the following:

    1. Remove the currently installed version of the mint CLI: `npm uninstall -g mint`
    2. Upgrade to Node.js v20.17.0+.
    3. Reinstall the mint CLI: `npm install -g mint`
  </Accordion>

  <Accordion title="Issue: Encountering an unknown error">
    **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
  </Accordion>

  <Accordion title="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`. When prompted, enter the password that you use to unlock your computer.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="mintlify versus mint package">
    If you have any problems with the CLI package, first run `npm ls -g` to see what packages are globally installed. If you don't use npm, try `which mint` to locate the installation.

    If you have both a `mint` and a `mintlify` package installed, uninstall `mintlify`:

    ```bash
    npm uninstall -g mintlify
    npm cache clean --force
    npm i -g mint
    ```
  </Accordion>

  <Accordion title="Client version shows 'none' after installation">
    If you run `mint version` and the client version displays as `none`, the CLI may be unable to download the client application due to a corporate firewall or VPN.

    **Solution**: Ask your IT administrator to add `releases.mintlify.com` to your network allowlist.
  </Accordion>

  <Accordion title="CLI connects to localhost instead of production when using npx">
    In versions before `4.0.1125`, running `npx mint dev` or other commands from a docs
    repository could cause the CLI to incorrectly detect itself as a local development
    build. This made the CLI point to `localhost` URLs instead of the Mintlify production
    API, resulting in connection errors or unexpected behavior.

    **Solution**: Update to the latest CLI version:

    ```bash
    npm i -g mint@latest
    ```
  </Accordion>
</AccordionGroup>