Mintlify CLI Command Reference

The Mintlify Command Line Interface (CLI) is a development tool designed to help create and preview documentation locally. It works by reading a docs.json configuration file to build and serve the documentation site on a local server, allowing for real-time feedback on changes before they are published. The CLI is an essential part of the development workflow for any project using Mintlify for its documentation.

The primary function of the CLI is to run a local development server, but it also includes commands for maintenance, such as updating the tool itself. It processes all documentation source files, including Markdown pages (.mdx) and OpenAPI specifications (.json), to generate a complete and interactive documentation preview.

Sources: README.md:12-22, docs.json, api-reference/openapi.json

Installation

The Mintlify CLI is distributed as an npm package named mint. It can be installed globally to be accessible from any location in your terminal.

To install the CLI, run the following command:

npm i -g mint

This command ensures that the mint executable is available in your system's path.

Sources: README.md:12-16, quickstart.mdx

Commands

The CLI provides a set of commands to manage the local documentation development environment.

mint dev

This is the primary command used for local development. It starts a local web server that hosts a live preview of your documentation.

Usage:

mint dev

The command must be executed from the root directory of your documentation project, which is the directory containing the docs.json file. Upon successful execution, the local preview will be available at http://localhost:3000.

Sources: README.md:18-22, development.mdx

The following diagram illustrates the workflow when using the mint dev command.

This diagram shows the process initiated by mint dev, from finding the configuration file to serving the local preview.

Sources: README.md:18-22, README.md:30-31

mint update

This command is used to update the Mintlify CLI to the most recent version. It is recommended to run this command if you encounter issues with the development environment, as it ensures you have all the latest features and bug fixes.

Usage:

mint update

Sources: README.md:28-29

Configuration

The Mintlify CLI's behavior is primarily controlled by the docs.json file located in the root of the documentation project. This file defines the structure, navigation, theme, and other metadata for the documentation site. The CLI reads this file to understand how to build the pages.

Key properties in docs.json include:

• name: The name of the documentation project.
• navigation: Defines the structure of the sidebar, including tabs, groups, and pages.
• colors: Customizes the primary, light, and dark colors of the theme.
• logo: Specifies paths to the light and dark mode logos.

The CLI uses the navigation array to map file paths to the documentation sidebar structure.

Sources: docs.json:1-103

The following diagram shows the relationship between the CLI, the configuration file, and the source documents.

This graph illustrates how the CLI uses docs.json to process and render both standard documentation pages and API reference files.

Sources: README.md:18-22, docs.json:11-70, api-reference/openapi.json

Troubleshooting

Common issues and their solutions are listed below.

Sources: README.md:27-31