Mintlify CLI command reference

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`.
`--host`	Expose the local preview on your network. Without this flag, the preview is only available at `localhost`.
`--no-open`	Do not open the browser automatically.
`--groups`	Space-separated list of user groups to mock for preview. For example, `--groups admin user`.
`--signed-in`	Preview as a signed-in reader with no groups. Use `--groups` to preview as specific groups. Without either flag, the preview shows the signed-out view.
`--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.
`--classic`	Preview with the classic Mintlify client instead of the default client.

Create a new Mintlify account from an interactive 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, signs 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.When an AI agent runs mint signup, or the command runs without an interactive terminal, it prints the agent signup guide instead of creating an account. Agents create sites without an account through Agent signup.

Examples

# Sign up interactively
mint signup

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

`mint deploy`

Create a site without an account and get Git push access to it. For the full flow, see Agent signup.

mint deploy [flags]

Flag	Description
`--subdomain`	Site name. Required for the first deployment, with `--new`, and in GitHub Actions.
`--org-name`	Organization display name.
`--directory`	Documentation directory for the site. Defaults to the current directory.
`--new`	Create another site instead of reusing the site for this directory.
`--email`	Email address to create a claim link for. Can’t be combined with `--github`.
`--github`	Trust the current GitHub repository to deploy the site and write `.github/workflows/mintlify.yml`.
`--force`	With `--github`, overwrite an existing workflow file that has different contents.

Run the command again from the same directory to get a fresh write token for the same site. In GitHub Actions, mint deploy pushes the checked-out commit to a site that trusts the repository. The workflow needs the id-token: write permission.

Examples

# Create a site
mint deploy --subdomain my-docs

# Get a claim link for the current site
mint deploy --email you@example.com

# Deploy from GitHub Actions on every push to the default branch
mint deploy --github --subdomain my-docs

`mint claim`

Claim a site created with mint deploy.

mint claim [flags]

Flag	Description
`--email`	Email address to create a claim link for.
`--code`	Code from the claim page that finishes the claim.
`--directory`	Documentation directory used for `mint deploy`. Defaults to the current directory.

Run mint claim --email to get a claim link. After the site owner opens the link and signs in, run mint claim --code with the code from the claim page. --email and --code can’t be combined.

Examples

# Get a claim link
mint claim --email you@example.com

# Finish the claim
mint claim --code ABCDEFGH

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 sign 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 project 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 project. 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 agent setup`

Set up AI coding agents to work on your Mintlify project. The command installs Mintlify skills and configures the admin MCP for Claude Code, Codex, or Cursor.

mint agent setup [flags]

Flag	Description
`--agent`, `-a`	Space-separated list of agents to configure: `claude-code`, `codex`, or `cursor`. Without this flag, the CLI prompts you to choose agents and preselects the ones it detects on your machine.
`--global`, `-g`	Set up agents for your user account instead of the current project. Defaults to `false`.

mint agent setup requires Node.js 22.20 or later and npm.

Without an interactive terminal, the command configures the agents it detects. If it detects none, pass --agent. The command adds an MCP server named mintlify-admin with the URL https://mcp.mintlify.com to each agent’s configuration file.

Agent	Project file	User account file (`--global`)
Claude Code	`.mcp.json`	`~/.claude.json`
Codex	`.codex/config.toml`	`~/.codex/config.toml`, or `config.toml` in `CODEX_HOME` when set
Cursor	`.cursor/mcp.json`	`~/.cursor/mcp.json`

If your Codex configuration defines mcp_servers as an inline table, setup can’t add an entry to it and stops with an error. Add a mintlify-admin entry with url = "https://mcp.mintlify.com" to the inline table yourself. If CLAUDE_CONFIG_DIR is set, --global setup for Claude Code stops with an error. Add the server with the Claude Code CLI instead:

claude mcp add --scope user --transport http mintlify-admin https://mcp.mintlify.com

Setup keeps your existing configuration and skips an agent that already has a matching mintlify-admin entry. If a mintlify-admin entry has a different configuration, or a configuration file can’t be parsed, setup stops before it installs skills. Rename or remove the conflicting entry, then run the command again. Rerunning the command refreshes the installed skills and replaces any local edits you made to them. The command does not sign you in to the admin MCP or reuse your mint login credentials. After setup, complete the OAuth sign-in in each agent. The command prints the steps for each agent you configured.

Examples

# Choose agents and set up the current project
mint agent setup

# Set up specific agents for the current project
mint agent setup --agent claude-code codex cursor

# Set up Codex for your user account
mint agent setup --agent codex --global

`mint instructions`

Print step-by-step guidance for a task in Mintlify, written for AI coding agents. Each topic covers a common job, such as publishing a new site or adding a custom domain. It lists the steps, the rules agents commonly get wrong, and how to verify the result. Your agent can run the command before it starts a task instead of relying on its training data. The CLI fetches each topic from the live Mintlify documentation, so the guidance stays current without a CLI update.

mint instructions [topic] [subtopic]

Without a topic, the command lists the available topics and when to use each one. With a topic, it prints that topic’s instructions as Markdown. Start with overview.

Topic	Subtopics
`overview`
`new-site`
`write`	`components`
`configure`	`navigation`, `settings`, `customization`
`api-docs`	`sdk`
`publish`	`domain`, `repo`, `analytics`, `assistant`
`access`	`team`
`automate`
`migrate`
`troubleshoot`

The command needs an internet connection. If a topic doesn’t exist, the command exits with an error. Run mint instructions to see valid topics. If your installed CLI doesn’t recognize the command, run mint update or use npx mint@latest instructions.

Examples

# List topics
mint instructions

# Read the overview
mint instructions overview

# Custom domain instructions
mint instructions publish domain

`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. The command checks Markdown links and images, including reference-style links such as [text][id]. It also checks the href of <a> and <Card> components and the src of <img> and <source> tags, whether written as a plain string or as a fixed value in braces, such as href={"/quickstart"}. Values computed from variables are not checked. Links without a leading /, such as quickstart or ../quickstart, resolve from the directory of the page that contains them, the same way a browser resolves them. To link from the root of your site, start the path with /. For links without a leading / and anchor links (#) inside a snippet, the command checks each page that renders the snippet. The command reports one of these links only if it is broken on at least one of those pages. With --check-anchors, headings inside a snippet count as anchors on the pages that render it.

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 that snippet import paths resolve to existing files.

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`

Check your documentation for errors, then validate the build in strict mode. Includes automatic validation of OpenAPI specifications referenced in your docs.json.

mint validate [flags]

mint validate runs a set of rules against your pages, snippets, navigation, and OpenAPI specifications, then runs a strict build. Findings print grouped by file, with the line, column, and rule name for each one when available. The duplicate-h1, katex, and foreign-syntax rules report warnings, so their findings don’t fail the run. The other rules report errors. The strict build runs only when no rule reports an error and at least one selected rule needs the build. If a rule reports an error, the command skips the build and tells you to fix the errors first. Warnings that the build can’t attribute to a rule fail the run as build-failed errors.

Rule	Group	Description
`parse-error`	`content`	Reports files that MDX can’t parse. Other rules skip these files. This check always runs and you can’t disable it.
`void-tags`	`content`	Reports HTML void elements, such as `<br>`, `<img>`, `<source>`, and `<input>`, that aren’t self-closed. MDX can’t parse them unless you write them self-closed, for example `<br />` or `<source />`. `--fix` can self-close them for you.
`duplicate-h1`	`content`	Reports a page whose first heading is an H1 that repeats the frontmatter `title`. Skips pages with `mode` set to `custom` or `frame`. `--fix` removes the heading, unless it has a custom `{#id}` or links in your site point to its anchor. In that case, remove it by hand and update the links.
`unknown-component`	`content`	Reports JSX components on a page that aren’t built in, imported, or exported on that page. `--fix` adds an import when a matching file such as `snippets/<Name>.jsx` or `snippets/<Name>.tsx` exists.
`undefined-variable`	`content`	Reports `{{variableName}}` placeholders in pages and snippets that the `variables` object in `docs.json` doesn’t define. Skips code.
`missing-snippet`	`content`	Reports `<Snippet file="...">` tags whose snippet file doesn’t exist, after Mintlify replaces any `docs.json` variables in the path.
`katex`	`content`	Reports inline or block math that KaTeX can’t render. Ignores currency amounts such as `$5`.
`foreign-syntax`	`content`	Reports syntax from other documentation frameworks that Mintlify doesn’t render, such as `:::` admonitions, Liquid tags, Hugo shortcodes, and `[[wiki links]]`. Each finding names the Mintlify replacement. Runs on files MDX can’t parse and skips code.
`missing-file`	`content`	Reports imported files that don’t exist. Needs the build.
`import-error`	`content`	Reports imports in pages and snippets that don’t resolve. Needs the build.
`missing-nav-page`	`nav`	Reports pages in your navigation that have no file. Needs the build.
`package-import`	`config`	Reports npm package imports that are undeclared or conflict. Needs the build.
`build-failed`	`config`	Reports a strict build failure that no other rule explains. Needs the build.
`openapi-spec`	`openapi`	Reports OpenAPI specifications in `docs.json` or `mint.json` that don’t parse or validate, with overlays applied.
`openapi-build`	`openapi`	Reports OpenAPI pages the build could not generate. Needs the build.

Flag	Description
`--files`	One or more file paths or globs to limit page checks to. Site-wide checks and the build still cover the whole site.
`--disable`	Turn off rules or groups. Pass a comma-separated list, or `all` to turn off every rule. Parse errors are still reported. Use `--disable openapi` to skip OpenAPI checks.
`--enable`	Turn on rules or groups. Pass a comma-separated list. Use it with `--disable all` to run only specific rules.
`--fix`	Write the available automatic fixes to your files, then check again. Only rules that offer a fix (`void-tags`, `duplicate-h1`, and `unknown-component`) change files.
`--format`	Output format: `text` (default) or `json`. With `json`, the command prints one JSON report on stdout and nothing else.
`--no-build`	Skip the strict build, so the command doesn’t download the Mintlify client. Remote OpenAPI specifications are still fetched unless you disable the `openapi` rules.
`--groups`	Space-separated list of user groups to mock for validation. For example, `--groups admin user`.
`--local-schema`	Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production.

With --fix, mint validate runs up to five fix passes, because one fix can unlock another. For example, self-closing a <br> can let a page parse. After the last pass, every rule runs once more and the report shows what remains. The output lists each applied fix as fixed <file>:<line> <rule>: "before" → "after". --fix skips a fix that overlaps another fix in the same file. It also leaves a Markdown or MDX file unchanged if the fixed content would parse worse than before. Without --fix, the output ends with a count of the issues that --fix would fix.

Commit or stash your changes before you run --fix, so you can review its edits.

With --format json, progress output is hidden and other console output goes to stderr, so you can parse stdout directly. The report has these fields:

passed: true when no rule reported an error.
summary: errors and warnings counts, plus byRule with a count for each rule ID.
diagnostics: each finding, with rule, group, severity (error or warning), file, optional line and column, message, and an optional fix.
build: { "ran": true, "passed": <boolean> } if the strict build ran, otherwise { "ran": false, "reason": <reason> } with a reason of disabled, errors found, or no build rules.
fixed: only with --fix. Each applied change, with rule, file, optional line and column, before, and after.

If mint validate can’t run, it prints nothing on stdout and writes Error: <message> to stderr. The command exits with one of these codes:

0: No rule reported an error. Warnings don’t fail the run.
1: At least one rule reported an error.
2: mint validate could not run, for example because of an unknown rule name, a --files value that matches no pages or snippets, or a crash.

# Check pages matching a glob, then build the whole site
mint validate --files "guides/**/*.mdx"

# Check pages matching a glob and apply automatic fixes
mint validate --files "guides/**/*.mdx" --fix

# Skip OpenAPI checks
mint validate --disable openapi

# Run the rule checks without the strict build
mint validate --no-build

# Fast offline check for scripts and agents, listing each finding's file and message
mint validate --no-build --format json | jq '.diagnostics[] | {file, message}'

# Run only the content rules (missing-file and import-error still run the build)
mint validate --disable all --enable content

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

`mint og`

Render the social preview (OG) image for a page to a PNG file. The command uses your docs.json thumbnails settings, page and section thumbnail overrides, and the same rendering code as your live site.

mint og [page] [flags]

Argument	Description
`page`	Optional. Page path, such as `guides/webhooks`. Defaults to `index`.

Flag	Description
`--preset`	Try a preset (`classic`, `headline`, or `minimal`) without editing `docs.json`.
`--surface`	Try a surface (`brand` or `neutral`) without editing `docs.json`.
`--appearance`	Try an appearance (`light` or `dark`) without editing `docs.json`.
`--output`	Where to write the PNG. Defaults to a temporary file.
`--no-open`	Don’t open the image after rendering. The command also skips opening it when the `CI` environment variable is set.

The command prints warnings when the title is too long to fit on two lines, when no logo is configured or the logo fails to load, when the font fails to load, and when text has low contrast on a brand surface. Warnings don’t change the exit code. The command exits with code 1 if docs.json is invalid or the page doesn’t exist.

# Render one page and open it
mint og guides/webhooks

# Try settings on the home page
mint og --preset headline --surface brand

# Render to a file in CI
mint og --output og.png --no-open

`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.
`--base-path`	Path prefix to serve the export under. For example, `--base-path /docs`.
`--client-version`	Mintlify client release to build the export with, downloaded from `releases.mintlify.com`. Defaults to the latest release compatible with your CLI version.
`--classic`	Export with the classic Mintlify client instead of the default client. The archive layout and hosting rules differ. See Offline export.

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 migrate`

Print step-by-step instructions for migrating an existing documentation site to Mintlify or pass the instructions to an AI agent to complete the migration.

mint migrate [flags]

Flag	Description
`--from`	Add the instructions for a specific source platform to the overview. Accepts `confluence`, `docsify`, `document360`, `docus`, `docusaurus`, `fern`, `fumadocs`, `gitbook`, `github-wiki`, `jekyll`, `mdbook`, `mkdocs`, `nextra`, `notion`, `nuxt`, `pdf`, `readme`, `redocly`, `starlight`, `vitepress`, `vuepress`.
`--topic`	Print the detailed instructions for one step of the migration workflow instead of the overview. Accepts `discovery` (inventory the source pages), `conversion` (convert pages to MDX), `navigation` (build `docs.json` navigation and redirects), `api` (migrate an API reference), `changelog` (migrate a changelog), or `verify` (check the finished migration).
`--agent`	Start a coding agent in the current directory and have it run the migration. Accepts `claude`, `codex`, `cursor`, or `gemini`. Combine with `--from` to include a platform guide.
`--claude`	Alias for `--agent claude`.

Without flags, the command prints an overview of the migration workflow followed by the available topics and source platforms. The instructions are written for coding agents, so you can paste them into your agent or let your agent run mint migrate itself. With --agent, the CLI launches the specified agent’s command-line tool with a prompt to run mint migrate and follow the instructions it prints. You must already have the agent’s CLI installed. If the Mintlify CLI can’t find the agent CLI, mint migrate exits with an error that includes the install command.

Examples

# Print the migration overview
mint migrate

# Print the overview plus the GitBook guide
mint migrate --from gitbook

# Migrate a Docusaurus site with Claude Code
mint migrate --agent claude --from docusaurus

`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, architecture, and Node.js version. It also records whether the CLI runs in a CI environment, whether it runs in an interactive terminal, whether this is the first time the CLI has run on your machine, and whether you are signed in. If the CLI detects an AI coding agent running it, telemetry also includes the agent’s name. Each event also includes a session identifier that groups events from the same working session. The CLI stores it in ~/.config/mintlify/telemetry-session.json and replaces it after 30 minutes of inactivity. If you are signed in, telemetry events also include your account email address. Signed-out usage stays anonymous, and signing 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.

​Global flags

​mint dev

​mint signup

​Examples

​mint deploy

​Examples

​mint claim

​Examples

​mint login

​mint logout

​mint status

​mint add-domain

​Examples

​mint analytics

​mint analytics stats

​mint analytics search

​mint analytics feedback

​mint analytics conversation

​mint analytics conversation list

​mint analytics conversation view

​mint analytics conversation buckets list

​mint analytics conversation buckets view

​Examples

​mint agent setup

​Examples

​mint instructions

​Examples

​mint config

​Configuration keys

​mint broken-links

​mint a11y

​mint validate

​mint og

​mint export

​mint score

​Examples

​Checks

​mint format

​mint migrate

​Examples

​mint new

​mint update

​mint version

​Coming soon

​Telemetry

Global flags

`mint dev`

`mint signup`

Examples

`mint deploy`

Examples

`mint claim`

Examples

`mint login`

`mint logout`

`mint status`

`mint add-domain`

Examples

`mint analytics`

`mint analytics stats`

`mint analytics search`

`mint analytics feedback`

`mint analytics conversation`

`mint analytics conversation list`

`mint analytics conversation view`

`mint analytics conversation buckets list`

`mint analytics conversation buckets view`

Examples

`mint agent setup`

Examples

`mint instructions`

Examples

`mint config`

Configuration keys

`mint broken-links`

`mint a11y`

`mint validate`

`mint og`

`mint export`

`mint score`

Examples

Checks

`mint format`

`mint migrate`

Examples

`mint new`

`mint update`

`mint version`

Coming soon

Telemetry