Installing the Mintlify CLI

The Mintlify Command Line Interface (CLI) is a development tool designed to preview documentation changes locally before they are published. It allows developers to run a local server that renders the documentation site exactly as it would appear in production, ensuring that all customizations, content, and navigation work as expected. The CLI is an essential part of the development workflow, bridging the gap between writing content and deploying it.

This tool works by reading the project's configuration from the docs.json file to build the site structure, including navigation tabs, groups, and pages. It serves both standard markdown guide pages and API reference pages generated from specifications like OpenAPI. For more information on setting up your project, see the Quickstart Guide.

Sources: README.md:12-14, docs.json

Installation

The Mintlify CLI is distributed as an npm package named mint. Installation requires npm and is done globally to make the mint command accessible from any directory in your terminal.

Sources: README.md:12-14

Installation Command

To install the CLI, run the following command in your terminal:

npm i -g mint

This command downloads the mint package from the npm registry and installs it globally on your system.

Sources: README.md:15-17

Installation Flow

The diagram below illustrates the process of installing the Mintlify CLI using npm.

Usage

Once installed, the CLI can be used to start a local development server, update the tool itself, and troubleshoot common issues.

Starting the Development Server

To preview your documentation locally, navigate to the root directory of your project (the one containing your docs.json file) and run:

mint dev

This command starts a local server, typically at http://localhost:3000, where you can view your documentation. The server watches for file changes and automatically reloads the browser to reflect updates.

Sources: README.md:19-25

The following diagram shows the sequence of events when mint dev is executed.

CLI Commands

The Mintlify CLI provides a few key commands for managing your local development environment.

Sources: README.md:21-22, README.md:30

Project Configuration (docs.json)

The behavior of the mint dev command is entirely dependent on the docs.json configuration file. This file defines the structure and appearance of your documentation site.

Key properties read by the CLI include:

• name: The name of the documentation project.
• navigation: Defines the tabs, groups, and pages for the sidebar navigation. The CLI uses this to build the site's structure.
• colors: Primary, light, and dark theme colors.
• logo: Paths to the light and dark mode logos.
• api-reference: If an OpenAPI file is referenced, the CLI will parse it to generate API reference pages.

*Sources: docs.json:3-80, README.md:21-22, api-reference/openapi.json

The diagram below shows how docs.json structures the documentation served by the CLI.

This chart illustrates that the mint dev command processes docs.json to understand the project's name, navigation structure, and theme, including linking to specific content files like an OpenAPI specification.

Sources: docs.json:1-80, api-reference/openapi.json

Troubleshooting

If you encounter issues while using the Mintlify CLI, refer to the following common problems and solutions.

Sources: README.md:29-32

Summary

The Mintlify CLI is a crucial tool for any developer working with the Mintlify documentation platform. By providing a simple command, mint dev, it enables a fast and efficient local development loop. The CLI's reliance on the docs.json configuration file ensures that the local preview is a faithful representation of the final published site. Proper installation and usage of the CLI are foundational steps for creating and maintaining high-quality documentation with Mintlify.

Sources: README.md