mintlify/README.md

The Mintlify CLI

<div align="center">
  <a href="https://mintlify.com">
    <img
      src="https://res.cloudinary.com/mintlify/image/upload/v1665385627/logo-rounded_zuk7q1.svg"
      alt="Mintlify Logo"
      height="64"
    />
  </a>
  <br />
  <p>
    <h3>
      <b>
        Mintlify CLI
      </b>
    </h3>
  </p>
  <p>
    The Mintlify CLI is the easiest way to build Mintlify apps from the command line.
  </p>
  <p>

[![Website](https://img.shields.io/website?url=https%3A%2F%2Fmintlify.com&logo=mintlify)](https://mintlify.com) [![Tweet](https://img.shields.io/twitter/url?url=https%3A%2F%2Fmintlify.com%2F)](https://twitter.com/intent/tweet?url=&text=Check%20out%20%40mintlify)

  </p>
  <p>
    <sub>
      Built with ❤︎ by
      <a href="https://mintlify.com">
        Mintlify
      </a>
    </sub>
  </p>
</div>

### Installation

```
npm i -g mintlify
```

Requires Node 20.17 or higher. LTS versions recommended. Node 25+ is not supported.

### Local preview

#### `mintlify dev`

Run at the root of your Mintlify project to preview changes locally. Opens in the browser by default.

```
mintlify dev
```

**Options**

| Flag                  | Description                             | Default |
| --------------------- | --------------------------------------- | ------- |
| `--port <number>`     | Port to run the preview on              | `3000`  |
| `--no-open`           | Skip opening the preview in the browser | —       |
| `--groups <group...>` | Mock user groups for local testing      | —       |
| `--disable-openapi`   | Disable OpenAPI file generation         | —       |

**Custom port**

```
mintlify dev --port 3333
```

If the specified port is already in use, the CLI automatically tries the next available port.

**Troubleshooting**

If `mintlify dev` is not working, try these steps in order:

1. Make sure you are running in a folder with a `docs.json` file.
2. Run `mintlify update` to get the latest version of the CLI.
3. Make sure you are using Node 20.17 or higher.
4. Delete the contents of the `.mintlify` folder in your home directory.

### Validate and check

#### `mintlify validate`

Validate the documentation build in strict mode. Exits with a non-zero code on any warning or error — useful in CI.

```
mintlify validate
```

**Options**

| Flag                  | Description                     |
| --------------------- | ------------------------------- |
| `--groups <group...>` | Mock user groups for validation |
| `--disable-openapi`   | Disable OpenAPI file generation |

#### `mintlify broken-links`

Check for broken internal links in your project.

```
mintlify broken-links
```

**Options**

| Flag               | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `--check-anchors`  | Also validate anchor links like `link-path#section` against heading slugs |
| `--check-external` | Also check external links for broken URLs                                 |
| `--check-snippets` | Also check links inside `<Snippet>` components                            |

#### `mintlify openapi-check <filename>`

Check an OpenAPI spec for errors. Accepts a local file path or a URL.

```
mintlify openapi-check ./openapi.yaml
mintlify openapi-check https://petstore3.swagger.io/api/v3/openapi.json
```

#### `mintlify a11y`

Check for accessibility issues in your documentation. Also available as `mintlify accessibility`, `mintlify accessibility-check`, and `mintlify a11y-check`.

```
mintlify a11y
```

**Options**

| Flag              | Description                               |
| ----------------- | ----------------------------------------- |
| `--skip-contrast` | Skip color contrast checks                |
| `--skip-alt-text` | Skip alt text checks on images and videos |

### Create and manage content

#### `mintlify new [directory]`

Create a new Mintlify documentation site. Defaults to the current directory.

```
mintlify new
mintlify new my-docs
```

**Options**

| Flag             | Description                         |
| ---------------- | ----------------------------------- |
| `--theme <name>` | Theme for the documentation site    |
| `--name <name>`  | Name of the documentation project   |
| `--force`        | Initialize in a non-empty directory |

#### `mintlify rename <from> <to>`

Rename a file and update all internal references to it throughout the project.

```
mintlify rename introduction.mdx overview.mdx
```

**Options**

| Flag      | Description                  |
| --------- | ---------------------------- |
| `--force` | Rename files and skip errors |

#### `mintlify scrape <url>`

Scrape an entire documentation site and convert it to Mintlify MDX files. Also available as `mintlify scrape site <url>`.

```
mintlify scrape https://example.com/docs
```

**Options**

| Flag              | Description                                                                      |
| ----------------- | -------------------------------------------------------------------------------- |
| `--filter <path>` | Only scrape URLs matching this path (e.g. `/docs` matches `/docs` and `/docs/*`) |

#### `mintlify scrape page <url>`

Scrape a single documentation page and convert it to an MDX file.

```
mintlify scrape page https://example.com/docs/introduction
```

#### `mintlify scrape openapi <location>`

Generate MDX files from an OpenAPI spec. Accepts a local file path or a URL.

```
mintlify scrape openapi ./openapi.yaml
mintlify scrape openapi https://petstore3.swagger.io/api/v3/openapi.json
```

**Options**

| Flag              | Description                         | Default |
| ----------------- | ----------------------------------- | ------- |
| `--outDir <path>` | Folder to write the generated files | —       |
| `--overwrite`     | Overwrite existing files            | `false` |

#### `mintlify migrate-mdx`

Migrate MDX OpenAPI endpoint pages to `x-mint` extensions and `docs.json`.

#### `mintlify upgrade`

Upgrade `mint.json` to `docs.json`. Creates a `docs.json` from your existing `mint.json`.

#### `mintlify workflow`

Add a workflow to your documentation repository.

### Export

#### `mintlify export`

Export a static site as a zip file for air-gapped deployment.

```
mintlify export
mintlify export --output docs.zip
```

**Options**

| Flag                  | Description                     | Default      |
| --------------------- | ------------------------------- | ------------ |
| `--output <path>`     | Output zip file path            | `export.zip` |
| `--groups <group...>` | Mock user groups for export     | —            |
| `--disable-openapi`   | Disable OpenAPI file generation | —            |

### CLI management

#### `mintlify update`

Update the CLI to the latest version.

#### `mintlify version`

Display the current version of the CLI and client. Also available as `mintlify v`.

### Get Started

[Create an account](https://mintlify.com/start) to start using Mintlify for your documentation.