> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI installation

> Install the CLI to preview and develop your docs locally

<img className="block dark:hidden my-0 pointer-events-none" src="https://mintcdn.com/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/installation/local-development-light.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=6525a601adf38652082acfa170797829" width="1184" height="320" data-path="images/installation/local-development-light.png" />

<img className="hidden dark:block my-0 pointer-events-none" src="https://mintcdn.com/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/installation/local-development-dark.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=c3239d807129b6f835400e3d926d964c" width="1184" height="320" data-path="images/installation/local-development-dark.png" />

## Installing the CLI

<Info>
  **Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding.
</Info>

<Steps>
  <Step title="Install the CLI.">
    Run the following command to install the [CLI](https://www.npmjs.com/package/mint):

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

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

  <Step title="Preview locally.">
    Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:

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

    A local preview of your documentation will be available at `http://localhost:3000`.
  </Step>
</Steps>

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

```bash theme={null}
npx mint dev
```

## Updates

If your local preview is out of sync with what you see on the web in the production version, update your local CLI:

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

If this `mint update` command is not available on your local version, re-install 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>

## 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:

```bash theme={null}
mint dev --port 3333
```

If you attempt to run on a port that is already in use, it will use the next available port:

```mdx theme={null}
Port 3000 is already in use. Trying 3001 instead.
```

## Previewing 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 `--group [groupname]` flag.

For example, if you have a group named `admin`, you can preview as a member of that group with the command:

```bash theme={null}
mint dev --group admin
```

## Additional commands

While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.

### Finding broken links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:

```bash theme={null}
mint broken-links
```

### Checking OpenAPI spec

You can use the CLI to check your OpenAPI file for errors using the following command:

```bash theme={null}
mint openapi-check <openapiFilenameOrUrl>
```

You can pass in a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).

### Renaming files

You can rename and update all references to files using the following command:

```bash theme={null}
mint rename <oldFilename> <newFilename>
```

### Migrating MDX endpoint pages

You can migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification using the following command:

```bash theme={null}
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](/api-playground/migrating-from-mdx) for detailed information.

## 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](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.

If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.

## 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. 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`
  </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`. You will be prompted for your password, which is the one 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 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:

    ```bash theme={null}
      npm uninstall -g mintlify
    ```

    2. Clear your npm cache:

    ```bash theme={null}
      npm cache clean --force
    ```

    3. Reinstall the new package:

    ```bash theme={null}
    npm i -g mint
    ```
  </Accordion>
</AccordionGroup>