Mintlify CLI command reference

Complete reference for Mintlify CLI commands and flags, including mint index, mint dev, mint validate, mint broken-links, and more.

To install the CLI, see Install the CLI.

Global flags

These flags are available on all commands.

Flag	Description
`--telemetry`, `-t`	Enable or disable usage telemetry.
`--help`, `-h`	Display help for the command.
`--version`, `-v`	Display the CLI version. Alias for `mint version`.

`mint dev`

Start a local preview of your documentation.

mint dev [flags]

Flag	Description
`--port`	Port to run the local preview on. Defaults to `3000`.
`--no-open`	Do not open the browser automatically.
`--groups`	Space-separated list of user groups to mock for preview. For example, `--groups admin user`.
`--disable-openapi`	Skip OpenAPI file processing to improve performance.
`--disable-prefetch`	Disable navigation prefetching in the local preview. Useful for very large sites where background prefetching slows down page loads.
`--local-schema`	Allow locally hosted OpenAPI files served over HTTP.

Install the hosted Mintlify Index MCP server for your coding agents to search across all content on Mintlify sites. The server provides a context tool for researching libraries, frameworks, SDKs, APIs, and CLI tools.

The Index MCP server is separate from the Mintlify Docs MCP server, which searches your documentation site.

mint index [options]

Options

Option	Description
`--claude`	Set up Claude Code.
`--cursor`	Set up Cursor.
`--vscode`	Set up VS Code.
`--codex`	Set up Codex.
`--opencode`	Set up OpenCode.
`--windsurf`	Set up Windsurf.
`--zed`	Set up Zed.
`--project`	Write project-level configuration instead of global configuration when the client supports it.
`--yes`, `-y`	Skip the picker and set up all detected clients.

Select clients

Run mint index without client options to detect installed clients and open an interactive picker. Select the clients to configure, then confirm the prompt.

Pass one or more client options to configure specific clients without opening the picker:

mint index --claude --cursor

Use --yes to configure every detected client without prompts. If the CLI can’t detect any clients, pass an explicit client option such as --claude or --cursor.

Use --project with client options to write project configuration in the current directory:

mint index --project --cursor --vscode

Configuration and rules

The command adds the mintlify-index server to each selected client and points it to https://index.mintlify.com/mcp. By default, it updates global configuration. With --project, it uses project configuration where the client supports it.

The command also adds a usage rule for each selected client except Zed. The rule tells the client to use the Index MCP context tool for documentation research, including syntax, configuration, migrations, and setup. It tells the client to prefer the tool over web search because training data can be out of date. The rule excludes general programming concepts and business-logic debugging.

Windsurf has a global MCP configuration only. With --project, the command still writes the MCP entry to the global Windsurf configuration and writes the usage rule in the current project.

Rerunning the command updates an existing mintlify-index entry and its generated rule. The command preserves unrelated configuration. If an existing JSON or JSONC configuration is invalid, the command reports an error without changing that file.

Supported clients and their standard configuration files include:

Client	Global configuration	Project configuration
Claude Code	`~/.claude.json`	`.mcp.json`
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
VS Code	User `mcp.json`	`.vscode/mcp.json`
Codex	`~/.codex/config.toml`	`.codex/config.toml`
OpenCode	`~/.config/opencode/opencode.json`	`opencode.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Global only
Zed	User `settings.json`	`.zed/settings.json`

Create a new Mintlify account from the terminal.

mint signup [flags]

Flag	Description
`--firstName`	Your first name.
`--lastName`	Your last name.
`--company`	Your company name.
`--email`	Email address for the account.

Run the command without flags to enter your details interactively. The CLI prompts for any value you do not pass as a flag.

After you submit your details, Mintlify sends a verification link to your email. The command waits until you click the link, then creates your account, logs you in, and stores your credentials. When it finishes, open the dashboard to connect your repository and start building.

mint signup does not return until you click the verification link, which can take several minutes. In scripts or automations, run it as a background process instead of waiting on it synchronously.

Examples

# Sign up interactively
mint signup

# Sign up with all details provided
mint signup \
  --firstName Jane \
  --lastName Doe \
  --company Acme \
  --email [email protected]

Authenticate with your Mintlify account.

mint login

Opens a browser window to complete authentication. If the browser does not open, the CLI displays a URL to open manually and a prompt to paste the authorization code. Credentials save in ~/.config/mintlify/config.json.

If you have more than one deployment, the CLI prompts you to select a default after you log in. You can change the default project later with mint config set subdomain <subdomain>.

`mint logout`

Remove stored credentials.

mint logout

`mint status`

Display your current session details including CLI version, account email, organization, and configured subdomain.

mint status

`mint add-domain`

Add a custom domain to your deployment from the terminal. Requires authentication with mint login.

mint add-domain <domain> [--basePath <path>]

Argument	Description
`domain`	The custom domain to add, like `docs.example.com`. Must be a bare hostname.

Flag	Description
`--basePath`	Serve your documentation at a subpath on the domain, like `/docs`. Must start with `/` and follow the base path requirements.

The command uses your configured subdomain from mint config. If you do not have a configured subdomain, it uses the first subdomain on your account.

After registering the domain, the CLI waits up to 10 seconds for DNS records to generate, then prints the TXT and CNAME records to add at your domain provider:

TXT _acme-challenge → <value>
TXT _cf-custom-hostname → <value>
CNAME @ → cname.mintlify.builders

Add the TXT records first, then add the CNAME once the verification records validate. See Custom domain for full DNS setup instructions, apex domain requirements, and TLS provisioning details.

If the command fails with Domain is already in use by another deployment in your organization or Domain is already claimed by another organization, the domain is bound to another Mintlify deployment. See Add domain fails with “Domain is already claimed by another organization” to release it and re-add it.

If some TXT records are still generating when the command exits, check the Custom domain setup page in your dashboard for the remaining values.

When you pass --basePath, the CLI saves the base path after registering the domain. The new path takes effect on your next deploy, and your site continues serving from the current path until then. The CNAME sends all traffic on the domain to Mintlify, so only add it if the domain hosts nothing else. Otherwise, keep your existing DNS and set up a reverse proxy to Mintlify for the base path. See Host docs at a subpath for provider-specific guides.

Examples

Add a custom domain at the root:

mint add-domain docs.example.com

Add a custom domain and serve your documentation at /docs:

mint add-domain example.com --basePath /docs

`mint analytics`

Query documentation analytics from the terminal. Requires authentication with mint login.

Analytics require a Pro or Enterprise plan.

mint analytics <subcommand> [flags]

All subcommands accept these shared flags:

Flag	Description
`--subdomain`	Documentation subdomain. Defaults to the value set with `mint config set subdomain`, or the first project on your account.
`--from`	Start date in `YYYY-MM-DD` format. Defaults to seven days ago, or the value set with `mint config set dateFrom`.
`--to`	End date in `YYYY-MM-DD` format. Defaults to today, or the value set with `mint config set dateTo`.
`--format`	Output format: `table` (pretty), `plain` (tab-separated, pipeable), `json` (raw), or `graph` (bar chart). Defaults to `plain`, or `json` when the CLI detects an AI or CI environment.

`mint analytics stats`

Display top-line KPIs for a date range: views, visitors, searches, feedback, and assistant usage. The output reports human and agent traffic separately.

mint analytics stats [flags]

Flag	Description
`--page`	Filter to a specific page path.

`mint analytics search`

Display search queries with hit counts, click-through rates, top clicked page, and last searched date.

mint analytics search [flags]

Flag	Description
`--query`	Filter results by search query substring.
`--page`	Filter results to queries where the given page was the top clicked result.

`mint analytics feedback`

Display user feedback. By default, returns individual feedback entries. Pass --type page to see feedback aggregated by page path, or --type code to only include feedback on code snippets.

mint analytics feedback [flags]

Flag	Description
`--type`	`code` for code snippet feedback, or `page` for page-level aggregation. Omit for all feedback entries.
`--page`	Filter to a specific page path.

`mint analytics conversation`

View assistant conversation analytics.

`mint analytics conversation list`

List recent assistant conversations with timestamp, first user query, and category.

mint analytics conversation list [flags]

Flag	Description
`--page`	Filter to conversations whose sources reference the given page path.

`mint analytics conversation view`

View the full message thread for a single conversation.

mint analytics conversation view <id> [flags]

Argument	Description
`id`	Conversation ID from `mint analytics conversation list`.

`mint analytics conversation buckets list`

List clusters of conversations grouped by topic, with the number of conversations and the most recent question date for each cluster.

mint analytics conversation buckets list [flags]

`mint analytics conversation buckets view`

List the individual threads in a conversation bucket.

mint analytics conversation buckets view <id> [flags]

Argument	Description
`id`	Bucket ID from `mint analytics conversation buckets list`.

Flag	Description
`--limit`	Maximum threads to return. Between 1 and 100.
`--cursor`	Pagination cursor from a previous response.

Examples

# KPIs for the last 30 days
mint analytics stats --from 2026-07-25 --to 2026-08-24

# Top search queries as a bar chart
mint analytics search --format graph

# Page-level feedback aggregated as JSON for piping into other tools
mint analytics feedback --type page --format json

# View a single conversation thread
mint analytics conversation view conv_123

`mint config`

Manage persistent default values for CLI commands. The configuration saves in ~/.config/mintlify/config.json.

mint config <subcommand> <key> [value]

Subcommand	Description
`set <key> <value>`	Set a configuration value.
`get <key>`	Display a configuration value.
`clear <key>`	Remove a configuration value.

Configuration keys

Key	Description	Used by
`subdomain`	Default documentation subdomain.	`mint dev`, `mint analytics`, `mint add-domain`, `mint score`
`dateFrom`	Default start date for analytics queries.	`mint analytics`
`dateTo`	Default end date for analytics queries.	`mint analytics`

`mint broken-links`

Check for broken internal links in your documentation.

mint broken-links [flags]

The command scans .mdx and .md files for links and excludes files matching .mintignore patterns. Links inside OpenAPI specification files (.yaml, .yml, .json) are not checked. Links that point to ignored files report as broken.

Flag	Description
`--files`	One or more file paths or globs to check. Defaults to the whole site.
`--check-anchors`	Also validate anchor links (for example, `/page#section`) against heading slugs.
`--check-external`	Also check external URLs for broken links.
`--check-redirects`	Also check that redirect destinations in `docs.json` resolve to valid paths.
`--check-snippets`	Also check links inside `<Snippet>` components.

Pass --files to limit the check to specific pages. This is useful for validating a single page you just edited or scoping checks to a directory in CI. When --files is set with --check-external, only external URLs on the selected pages are fetched.

# Check a specific page
mint broken-links --files introduction.mdx

# Check pages matching a glob
mint broken-links --files "guides/**/*.mdx"

# Pass multiple paths
mint broken-links --files introduction.mdx "guides/**/*.mdx"

Check for accessibility issues in your documentation.

mint a11y [flags]

Checks color contrast ratios and missing alt text on images and videos.

Flag	Description
`--skip-contrast`	Skip color contrast checks.
`--skip-alt-text`	Skip missing alt text checks.

`mint validate`

Validate your documentation build in strict mode. Exits with an error if there are any warnings or errors. Includes automatic validation of OpenAPI specifications referenced in your docs.json.

mint validate [flags]

Flag	Description
`--groups`	Space-separated list of user groups to mock for validation. For example, `--groups admin user`.
`--disable-openapi`	Skip OpenAPI file processing and validation.
`--local-schema`	Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production.

Use mint validate instead of the deprecated standalone mint openapi-check command.

`mint test`

Generate tests from your code samples in your documentation. Requires authentication with mint login.

mint test

mint test scans your content for code blocks, generates unit tests for validating them, and runs the tests with a local coding agent.

Prerequisites

Authenticate with mint login.

Install the SDK for the coding agent you want to use:

# Claude (default)
npm install @anthropic-ai/claude-agent-sdk @anthropic-ai/sdk @modelcontextprotocol/sdk

# Codex
npm install @openai/codex-sdk

Only pages in your docs.json navigation appear for selection.

The mint test interactive interface with a steps sidebar and a page selection tree listing folders of pages with code block counts.

Revisit a previous run

mint test saves a report for each completed run. When a saved report exists, the next interactive run starts with options for it:

Update tests: Rerun the same pages with the same agent and model.
Review last test run: Browse the saved results without running anything.
Start a brand new test: Select an agent and pages from scratch.

Output

The mint test command writes to two locations in your project:

Path	Contents
`tests/mint-test/<run-id>/`	The generated test projects, one directory per agent and page.
`.mintlify/test/`	Run reports and history, including `runs/<run-id>.json` for each run.

Add both paths to your .gitignore if you do not want to commit test artifacts.

When a run finishes, the command prints a result summary, for example mint test passed: 8 passed, 0 failed, 0 agent errors. The command exits with code 0 when every test passes and 1 otherwise.

`mint export`

Export your documentation as a self-contained zip archive for offline viewing and distribution.

mint export [flags]

Flag	Description
`--output`	Output filename. Defaults to `export.zip`.
`--groups`	Space-separated list of user groups to include restricted pages for. For example, `--groups admin user`.
`--disable-openapi`	Skip OpenAPI processing.

See Offline export for details.

`mint score`

Run agent readiness checks against a public documentation site. Requires authentication with mint login.

mint score [url] [flags]

Argument	Description
`url`	Optional. URL of the docs site to check. If omitted, the command scores your configured subdomain (from `mint config` or the subdomain associated with your logged-in account).

Flag	Description
`--format`	Output format: `table` (default, colored), `plain` (pipeable TSV), or `json`.

The command displays an overall readiness score and a breakdown of individual checks with pass/fail indicators.

Examples

# Score your default subdomain
mint score

# Score a specific site
mint score docs.example.com

Checks

The score evaluates the following areas:

Check	What it verifies
`llmsTxtExists`	Agents can reach an llms.txt file at the site root.
`llmsTxtValid`	The `llms.txt` file follows the expected format with headings, blockquote summary, and Markdown links.
`llmsTxtSize`	The `llms.txt` file is within the size threshold so agents can consume it without truncation.
`llmsTxtLinksResolve`	Links inside `llms.txt` resolve to live pages.
`llmsTxtLinksMarkdown`	Links inside `llms.txt` use Markdown syntax.
`llmsTxtDirective`	The `llms.txt` file contains usage directives.
`llmsTxtFullExists`	An llms-full.txt file is available for agents that need the complete content. Runs independently of `llmsTxtExists`.
`llmsTxtFullSize`	The `llms-full.txt` file is within a reasonable size for agents to process.
`llmsTxtFullValid`	The `llms-full.txt` file contains valid content with headings.
`llmsTxtFullLinksResolve`	Links inside `llms-full.txt` resolve to live pages.
`skillMd`	Agents can reach a skill.md file for agent tool use.
`contentNegotiationMarkdown`	The site returns Markdown when agents request it through content negotiation.
`contentNegotiationPlaintext`	The site returns plain text when agents request it through content negotiation.
`mcpServerDiscoverable`	Agents can discover an MCP server for tool-based agents.
`mcpToolCount`	The MCP server exposes at least one tool.
`openApiSpec`	There is an available OpenAPI or Swagger specification at a standard path.
`robotsTxtAllowsAI`	The `robots.txt` file does not block AI crawlers.
`sitemapExists`	There is a sitemap available for page discovery.
`structuredData`	The homepage contains JSON-LD structured data (`<script type="application/ld+json">`). Reports the number of JSON-LD blocks and the schema types found.
`responseLatency`	The site responds within an acceptable time for agents.

Some checks only run if a check they depend on passes. If a check fails, none of the checks that depend on it run. They automatically fail. For example, llmsTxtValid only passes if llmsTxtExists passes first.

The overall score uses weighted scoring, so higher-impact checks contribute more to your score.

`mint format`

mint format rewrites files in place. Commit or stash your changes before running it so you can review the diff.

Format every .mdx file in the current directory to Mintlify’s canonical style. The command parses each file with the same MDX parser the web editor uses, then rewrites it in place if the canonical output differs.

mint format

Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by .gitignore and any Mintlify ignore rules. Files that already match the canonical output are left untouched.

Running mint format can result in many changes depending on the size of your project. To avoid merge conflicts and introducing changes to other in progress work, first resolve all important pending branches. Then create a new branch for formatting changes and run mint format on that branch.

When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code 1 and prints the file path and error, so you can run it in CI to enforce consistent formatting. See Install in CI for an example pipeline.

`mint new`

Create a new documentation project by picking a theme or cloning a pre-defined template from the mintlify/templates repository.

mint new [directory] [flags]

Flag	Description
`--name`	Project name. The CLI prompts for this if not provided in interactive mode.
`--theme`	Project theme. The CLI prompts for this if not provided in interactive mode.
`--template`	Pre-defined template. The CLI prompts for this if not provided in interactive mode.
`--force`	Overwrite the directory without prompting.

`mint update`

Update the CLI to the latest version.

mint update

`mint version`

Display the current CLI and client versions.

mint version

Coming soon

These commands are available to run but are not yet functional. Running them records your interest through CLI telemetry and helps prioritize what ships next.

Command	Description
`mint ai`	AI-powered documentation tools.
`mint mcp`	MCP server for documentation.

Telemetry

The CLI collects usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, and architecture. If you are logged in, telemetry events also include your account email address. Logged-out usage stays anonymous, and logging out removes your stored email. Mintlify does not collect project content or file paths.

By default, the CLI collects telemetry data. You can opt out at any time using the --telemetry flag:

# Disable telemetry
mint --telemetry false

# Re-enable telemetry
mint --telemetry true

You can also disable telemetry by setting one of these environment variables:

Variable	Value	Description
`MINTLIFY_TELEMETRY_DISABLED`	`1`	Disable Mintlify CLI telemetry.
`DO_NOT_TRACK`	`1`	Disable telemetry using the Console Do Not Track standard.

Your preference saves in ~/.config/mintlify/config.json and persists across CLI sessions.

Mintlify CLI command reference

On this page