> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the CLI

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

## Prerequisites

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

## Install the CLI

<CodeGroup>
  ```bash npm theme={null}
  npm i -g mint
  ```

  ```bash pnpm theme={null}
  pnpm add -g mint
  ```
</CodeGroup>

## Create a new project

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

```bash theme={null}
mint new [directory]
```

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 theme={null}
mint new my-docs --template <template-name>
```

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

```bash theme={null}
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

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

```bash theme={null}
mint update
```

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

<CodeGroup>
  ```bash npm theme={null}
  npm i -g mint@latest
  ```

  ```bash pnpm theme={null}
  pnpm add -g mint@latest
  ```
</CodeGroup>

## Formatting

For syntax highlighting and code formatting in MDX files, we recommend using the following extensions:

* **Cursor, Windsurf, 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

<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 theme={null}
    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 theme={null}
    npm i -g mint@latest
    ```
  </Accordion>
</AccordionGroup>


## Related topics

- [Quickstart](/docs/quickstart.md)
- [Introduction](/docs/index.md)
- [Mintlify CLI](/docs/cli/index.md)