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.

These flags are available on all commands.

Start a local preview of your documentation.

mint dev [flags]

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]

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

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:

Create a new Mintlify account from the terminal.

mint signup [flags]

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.

# Sign up interactively
mint signup

# Sign up with all details provided
mint signup \
  --firstName Jane \
  --lastName Doe \
  --company Acme \
  --email jane@acme.com

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 project, 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>.

Remove stored credentials.

mint logout

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

mint status

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

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

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 project. See Add domain fails with "Domain is already claimed by another organization" to release it and re-add it.

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.

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

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

mint analytics <subcommand> [flags]

All subcommands accept these shared flags:

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]

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

mint analytics search [flags]

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]

View assistant conversation analytics.

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

mint analytics conversation list [flags]

View the full message thread for a single conversation.

mint analytics conversation view <id> [flags]

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]

List the individual threads in a conversation bucket.

mint analytics conversation buckets view <id> [flags]

# 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

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

mint config <subcommand> <key> [value]

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.

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.

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]

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.

• 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.

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.

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

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.

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

mint export [flags]

See Offline export for details.

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

mint score [url] [flags]

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

# Score your default subdomain
mint score

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

The score evaluates the following areas:

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.

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.

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.

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

mint new [directory] [flags]

Update the CLI to the latest version.

mint update

Display the current CLI and client versions.

mint version

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.

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:

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

• Mintlify CLI
• Quickstart
• API playground overview