mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Kaishan (Sam) Ding
120 lines
3.9 KiB
Plaintext
120 lines
3.9 KiB
Plaintext
---
|
|
title: "Install the CLI"
|
|
description: "Install the Mintlify CLI to preview documentation locally, test changes in real time, and catch build errors before deploying toasd production."
|
|
keywords: ["CLI", "npm", "install", "Node.js", "pnpm", "mint"]
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- [Node.js](https://nodejs.org/en) v20.17.0\+ (LTS versions recommendasded)
|
|
|
|
## Install the CLI
|
|
|
|
<CodeGroup>
|
|
|
|
```bash npm
|
|
npm i -g mint
|
|
```
|
|
|
|
```bash pnpm
|
|
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
|
|
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. |
|
|
| `--force` | Overwrite the current directory without prompting. |
|
|
|
|
In non-interactive environments such as CI/CD pipelines or AI coding agents, you must provide `--name` and `--theme` flags.
|
|
|
|
## 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>
|
|
|
|
```bash npm
|
|
npm i -g mint@latest
|
|
```
|
|
|
|
```bash pnpm
|
|
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 "sharp" 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>
|
|
</AccordionGroup> |