Mintlify CLI 命令参考

若要安装 CLI，请参阅安装 CLI。

全局选项

以下选项适用于所有命令。

选项	描述
`--telemetry`, `-t`	启用或禁用使用遥测。
`--help`, `-h`	显示命令帮助。
`--version`, `-v`	显示 CLI 版本。`mint version` 的别名。

`mint dev`

启动文档的本地预览。

mint dev [flags]

选项	描述
`--port`	本地预览使用的端口。默认为 `3000`。
`--no-open`	不自动打开浏览器。
`--groups`	以空格分隔的用户组列表，用于模拟预览。例如 `--groups admin user`。
`--signed-in`	以不属于任何组的已登录读者身份预览。使用 `--groups` 以特定组身份预览。如果两个选项都未使用，预览将显示未登录视图。
`--disable-openapi`	跳过 OpenAPI 文件处理以提高性能。
`--disable-prefetch`	在本地预览中禁用导航预加载。适用于后台预加载会拖慢页面加载的超大型站点。
`--local-schema`	允许通过 HTTP 提供的本地托管 OpenAPI 文件。

`mint index`

为你的编程代理安装 Mintlify 托管的 Index MCP 服务器，以搜索 Mintlify 站点上的所有内容。该服务器提供 context 工具，用于查询库、框架、SDK、API 和 CLI 工具。 Index MCP 服务器不同于Mintlify Docs MCP 服务器，后者用于搜索你的文档站点。

mint index [options]

选项

选项	描述
`--claude`	配置 Claude Code。
`--cursor`	配置 Cursor。
`--vscode`	配置 VS Code。
`--codex`	配置 Codex。
`--opencode`	配置 OpenCode。
`--windsurf`	配置 Windsurf。
`--zed`	配置 Zed。
`--project`	在客户端支持时写入项目配置，而不是全局配置。
`--yes`、`-y`	跳过选择器并配置所有检测到的客户端。

选择客户端

不带客户端选项运行 mint index，即可检测已安装的客户端并打开交互式选择器。选择要配置的客户端，然后确认提示。传入一个或多个客户端选项，可以在不打开选择器的情况下配置指定客户端：

mint index --claude --cursor

使用 --yes 可在不显示提示的情况下配置所有检测到的客户端。如果没有检测到客户端，请传入明确的客户端选项，例如 --claude 或 --cursor。将 --project 与客户端选项一起使用，可将项目配置写入当前目录：

mint index --project --cursor --vscode

配置和规则

该命令会将 mintlify-index 服务器添加到每个选中的客户端，并将其指向 https://index.mintlify.com/mcp。默认情况下，它会更新全局配置。使用 --project 时，如果客户端支持项目配置，则使用该配置。该命令还会为除 Zed 之外的每个选中客户端添加使用规则。该规则会告知客户端使用 Index MCP 的 context 工具查询文档，包括语法、配置、迁移和设置，并优先使用该工具而不是网页搜索，因为训练数据可能已经过时。该规则不适用于通用编程概念或业务逻辑调试。 Windsurf 只有全局 MCP 配置。使用 --project 时，该命令仍会将 MCP 条目写入 Windsurf 的全局配置，并将使用规则写入当前项目。重新运行该命令会更新现有的 mintlify-index 条目及其生成的规则，同时保留其他配置。如果现有 JSON 或 JSONC 配置无效，该命令会显示错误且不会修改该文件。支持的客户端及其标准配置文件如下：

客户端	全局配置	项目配置
Claude Code	`~/.claude.json`	`.mcp.json`
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
VS Code	用户 `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`	仅全局配置
Zed	用户 `settings.json`	`.zed/settings.json`

从终端创建新的 Mintlify 账户。

mint signup [flags]

Flag	描述
`--firstName`	你的名字。
`--lastName`	你的姓氏。
`--company`	你的公司名称。
`--email`	账户的电子邮件地址。

不带任何 flag 运行该命令即可以交互方式输入你的信息。CLI 会提示你输入未通过 flag 传入的值。提交信息后，Mintlify 会向你的邮箱发送一封验证邮件。该命令会一直等待，直到你点击验证链接后，才会创建你的账户、为你登录并保存凭据。完成后，打开控制台来连接你的仓库并开始构建。

在你点击验证链接之前，mint signup 不会返回，而这可能需要几分钟。在脚本或自动化流程中，请以后台进程的方式运行它，而不是同步等待其完成。

示例

# 交互式注册
mint signup

# 一次性提供所有信息进行注册
mint signup \
  --firstName Jane \
  --lastName Doe \
  --company Acme \
  --email jane@acme.com

使用你的 Mintlify 账户进行身份验证。

mint login

打开浏览器窗口完成身份验证。如果浏览器未打开，CLI 会显示一个 URL 供你手动打开，并提示你粘贴授权代码。凭据保存在 ~/.config/mintlify/config.json 中。如果你有多个项目，CLI 会在登录后提示你选择一个默认项目。你可以稍后使用 mint config set subdomain <subdomain> 更改默认项目。

`mint logout`

移除已存储的凭据。

mint logout

`mint status`

显示当前会话的详细信息，包括 CLI 版本、账户邮箱、组织和已配置的子域名。

mint status

`mint add-domain`

从终端为你的项目添加一个自定义域名。需要使用 mint login 进行身份验证。

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

参数	描述
`domain`	要添加的自定义域名，例如 `docs.example.com`。必须是纯主机名。

选项	描述
`--basePath`	将文档托管在域名的子路径下，例如 `/docs`。必须以 `/` 开头，并符合 base path 要求。

该命令使用通过 mint config 配置的子域名。如果未设置，则使用账户中的第一个子域名。域名注册后，CLI 将等待最长 10 秒以生成 DNS 记录，然后打印需要在你的域名提供商处添加的 TXT 和 CNAME 记录：

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

请先添加 TXT 记录，验证记录通过后再添加 CNAME。有关完整的 DNS 配置说明、顶级域名要求和 TLS 配置详情，请参见自定义域名。如果命令报错 Domain is already in use by another deployment in your organization 或 Domain is already claimed by another organization，说明该域名已绑定到另一个 Mintlify 项目。请参见添加域名时报错 “Domain is already claimed by another organization” 以释放并重新添加。

如果命令结束时某些 TXT 记录仍在生成中，请稍后前往控制台的 Custom domain setup 页面查看剩余的值。

传入 --basePath 时，CLI 会在注册域名后保存 base path。新路径会在你的下次部署时生效，在此之前你的站点会继续从当前路径提供服务。CNAME 会把该域名的所有流量都发送到 Mintlify，因此仅在该域名没有托管其他内容时才添加它。否则，请保留现有 DNS，并为该 base path 设置指向 Mintlify 的反向代理。有关按服务商分类的指南，请参见将文档托管在子路径下。

示例

在根路径添加自定义域名：

mint add-domain docs.example.com

添加自定义域名并将文档托管在 /docs：

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

`mint analytics`

从终端查询文档分析数据。需要使用 mint login 进行身份验证。

分析功能需要 Pro 或 Enterprise 计划。

mint analytics <subcommand> [flags]

所有子命令都接受以下共享选项：

选项	描述
`--subdomain`	文档子域名。默认为通过 `mint config set subdomain` 设置的值，或你账户中的第一个项目。
`--from`	起始日期，格式为 `YYYY-MM-DD`。默认为七天前，或通过 `mint config set dateFrom` 设置的值。
`--to`	结束日期，格式为 `YYYY-MM-DD`。默认为今天，或通过 `mint config set dateTo` 设置的值。
`--format`	输出格式：`table`（美化）、`plain`（制表符分隔，可用于管道）、`json`（原始）或 `graph`（条形图）。默认为 `plain`，当 CLI 检测到 AI 或 CI 环境时默认为 `json`。

`mint analytics stats`

显示某个日期范围内的核心 KPI：浏览量、访客数、搜索次数、反馈和 assistant 使用情况。人类流量和 agent 流量分别报告。

mint analytics stats [flags]

选项	描述
`--page`	按指定页面路径过滤。

`mint analytics search`

显示搜索查询，包括命中次数、点击率、点击最多的页面和最后搜索日期。

mint analytics search [flags]

选项	描述
`--query`	按搜索查询子字符串过滤结果。
`--page`	过滤出以给定页面作为点击最多结果的查询。

`mint analytics feedback`

显示用户提交的反馈。默认返回单条反馈条目。传入 --type page 可查看按页面路径聚合的反馈，或传入 --type code 仅包含针对代码片段的反馈。

mint analytics feedback [flags]

选项	描述
`--type`	`code` 表示代码片段反馈，`page` 表示按页面级聚合。省略则返回所有反馈条目。
`--page`	按指定页面路径过滤。

`mint analytics conversation`

查看 assistant 对话分析数据。

`mint analytics conversation list`

列出最近的 assistant 对话，包括时间戳、用户的第一个问题和分类。

mint analytics conversation list [flags]

选项	描述
`--page`	过滤出其来源引用了给定页面路径的对话。

`mint analytics conversation view`

查看单个对话的完整消息线程。

mint analytics conversation view <id> [flags]

参数	描述
`id`	来自 `mint analytics conversation list` 的对话 ID。

`mint analytics conversation buckets list`

列出按主题分组的对话集群，包括每个集群的对话数量和最近的提问日期。

mint analytics conversation buckets list [flags]

`mint analytics conversation buckets view`

列出对话集群中的各个线程。

mint analytics conversation buckets view <id> [flags]

参数	描述
`id`	来自 `mint analytics conversation buckets list` 的集群 ID。

选项	描述
`--limit`	要返回的最大线程数。取值范围为 1 到 100。
`--cursor`	来自上一次响应的分页游标。

示例

# 最近 30 天的 KPI
mint analytics stats --from 2026-07-25 --to 2026-08-24

# 以条形图显示热门搜索查询
mint analytics search --format graph

# 以 JSON 格式聚合页面级反馈，便于管道传递给其他工具
mint analytics feedback --type page --format json

# 查看单个对话线程
mint analytics conversation view conv_123

`mint config`

管理 CLI 命令的持久默认值。配置保存在 ~/.config/mintlify/config.json 中。

mint config <subcommand> <key> [value]

子命令	描述
`set <key> <value>`	设置配置值。
`get <key>`	显示配置值。
`clear <key>`	移除配置值。

配置键

键	描述	使用者
`subdomain`	默认文档子域名。	`mint dev`、`mint analytics`、`mint add-domain`、`mint score`
`dateFrom`	分析查询的默认开始日期。	`mint analytics`
`dateTo`	分析查询的默认结束日期。	`mint analytics`

`mint broken-links`

检查文档中的内部断链。

mint broken-links [flags]

该命令会扫描 .mdx 和 .md 文件中的链接，并排除匹配 .mintignore 模式的文件。OpenAPI 规范文件（.yaml、.yml、.json）中的链接不会被检查。指向被忽略文件的链接会被报告为断链。

选项	描述
`--files`	要检查的一个或多个文件路径或 glob。默认检查整个站点。
`--check-anchors`	同时验证锚链接（例如 `/page#section`）是否与标题 slug 匹配。
`--check-external`	同时检查外部 URL 是否有断链。
`--check-redirects`	同时检查 `docs.json` 中的重定向目标是否解析为有效路径。
`--check-snippets`	同时检查 `<Snippet>` 组件内的链接。

使用 --files 将检查限定为特定页面。适用于验证你刚编辑过的某个页面，或在 CI 中将检查范围缩小到某个目录。当 --files 与 --check-external 一起使用时，仅会检查所选页面上的外部 URL。

# 检查特定页面
mint broken-links --files introduction.mdx

# 检查匹配某个 glob 的页面
mint broken-links --files "guides/**/*.mdx"

# 传入多个路径
mint broken-links --files introduction.mdx "guides/**/*.mdx"

检查文档中的无障碍性问题。

mint a11y [flags]

检查颜色对比度和图片、视频上缺失的替代文本。

选项	描述
`--skip-contrast`	跳过颜色对比度检查。
`--skip-alt-text`	跳过缺失替代文本检查。

`mint validate`

以严格模式验证文档构建。如果存在警告或错误则以错误退出。包括对 docs.json 中引用的 OpenAPI 规范的自动验证。

mint validate [flags]

选项	描述
`--groups`	以空格分隔的用户组列表，用于模拟验证。例如 `--groups admin user`。
`--disable-openapi`	跳过 OpenAPI 文件处理和验证。
`--local-schema`	允许验证通过 HTTP 提供的本地托管 OpenAPI 文件。生产环境仅支持 HTTPS。

请改用 mint validate，而不是已弃用的独立 mint openapi-check 命令。

`mint test`

根据文档中的代码示例生成测试。需要使用 mint login 进行身份验证。

mint test

mint test 会扫描你的内容中的代码块，生成用于验证这些代码块的单元测试，并使用本地编码代理运行这些测试。

前置条件

使用 mint login 进行身份验证。

为你要使用的编码代理安装 SDK：

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

# Codex
npm install @openai/codex-sdk

只有出现在 docs.json 导航中的页面才会显示以供选择。

回顾上一次运行

mint test 会为每次完成的运行保存报告。如果存在已保存的报告，下一次交互式运行会先显示针对该运行的选项：

Update tests：使用相同的代理和模型重新运行相同的页面。
Review last test run：查看已保存的结果，而不运行任何内容。
Start a brand new test：从头选择代理和页面。

输出

mint test 命令会写入项目中的两个位置：

路径	内容
`tests/mint-test/<run-id>/`	生成的测试项目，每个 agent 和页面对应一个目录。
`.mintlify/test/`	运行报告和历史记录，包括每次运行的 `runs/<run-id>.json`。

如果不想提交测试产物，请将这两个路径添加到 .gitignore 中。运行结束后，该命令会打印结果摘要，例如 mint test passed: 8 passed, 0 failed, 0 agent errors。当所有测试都通过时，命令以退出码 0 结束，否则以 1 结束。

`mint export`

将文档导出为独立的 zip 存档，用于离线查看和分发。

mint export [flags]

选项	描述
`--output`	输出文件名。默认为 `export.zip`。
`--groups`	以空格分隔的用户组列表，用于包含受限页面。例如 `--groups admin user`。
`--disable-openapi`	跳过 OpenAPI 处理。

有关详细信息，请参阅离线导出。

`mint score`

对公共文档站点运行代理就绪性检查。需要使用 mint login 进行身份验证。

mint score [url] [flags]

参数	描述
`url`	可选。要检查的文档站点的 URL。如果省略，该命令将对你配置的子域名进行评分（来自 `mint config`，或与你登录账户关联的子域名）。

选项	描述
`--format`	输出格式：`table`（默认，带颜色）、`plain`（可管道传输的 TSV）或 `json`。

该命令显示总体就绪性评分以及各项检查的通过/未通过指标。

示例

# 评分你的默认子域名
mint score

# 评分特定站点
mint score docs.example.com

检查项

评分评估以下方面：

检查项	验证内容
`llmsTxtExists`	代理可以访问站点根目录下的 llms.txt 文件。
`llmsTxtValid`	`llms.txt` 文件遵循预期格式，包含标题、引用摘要和 Markdown 链接。
`llmsTxtSize`	`llms.txt` 文件在大小阈值内，确保代理可以完整消费而不会被截断。
`llmsTxtLinksResolve`	`llms.txt` 中的链接指向有效页面。
`llmsTxtLinksMarkdown`	`llms.txt` 中的链接使用 Markdown 语法。
`llmsTxtDirective`	`llms.txt` 文件包含使用指令。
`llmsTxtFullExists`	提供了 llms-full.txt 文件，供需要完整内容的代理使用。独立于 `llmsTxtExists` 运行。
`llmsTxtFullSize`	`llms-full.txt` 文件大小合理，代理可以处理。
`llmsTxtFullValid`	`llms-full.txt` 文件包含带标题的有效内容。
`llmsTxtFullLinksResolve`	`llms-full.txt` 中的链接指向有效页面。
`skillMd`	代理可以访问 skill.md 文件以供代理工具使用。
`contentNegotiationMarkdown`	当代理通过内容协商请求时，站点返回 Markdown。
`contentNegotiationPlaintext`	当代理通过内容协商请求时，站点返回纯文本。
`mcpServerDiscoverable`	代理可以发现用于基于工具的代理的 MCP 服务器。
`mcpToolCount`	MCP 服务器至少公开一个工具。
`openApiSpec`	在标准路径下有可用的 OpenAPI 或 Swagger 规范。
`robotsTxtAllowsAI`	`robots.txt` 文件没有阻止 AI 爬虫。
`sitemapExists`	有可用的站点地图供页面发现使用。
`structuredData`	主页包含 JSON-LD 结构化数据（`<script type="application/ld+json">`）。报告 JSON-LD 块的数量和发现的架构类型。
`responseLatency`	站点在代理可接受的时间内响应。

某些检查项仅在其依赖的检查项通过时才会运行。如果某个检查项失败，所有依赖它的检查项都不会运行，它们会自动失败。例如，llmsTxtValid 仅在 llmsTxtExists 先通过后才会通过。总分使用加权评分，因此影响更大的检查项对您的分数贡献更多。

`mint format`

mint format 会就地重写文件。运行前请先提交或暂存你的更改，以便审查 diff。

将当前目录中的每个 .mdx 文件格式化为 Mintlify 的规范样式。该命令使用与 Web 编辑器相同的 MDX 解析器解析每个文件，如果规范化输出与原文不同，则就地重写文件。

mint format

在文档项目的根目录中运行该命令。它会遍历所有子目录，跳过 .gitignore 匹配的路径和任何 Mintlify 忽略规则匹配的路径。已经与规范化输出一致的文件将保持不变。

根据项目规模，运行 mint format 可能会产生大量更改。为避免合并冲突以及对其他进行中的工作引入更改，请先处理完所有重要的待合并分支，然后为格式化更改创建一个新分支，并在该分支上运行 mint format。

命令完成后，会打印重新格式化了多少个 MDX 文件以及有多少文件解析失败。如果有任何文件失败，命令将以退出码 1 结束，并打印文件路径和错误信息，这样你就可以在 CI 中运行它以强制执行一致的格式。示例流水线请参见在 CI 中安装。

`mint new`

通过选择主题或从 mintlify/templates 仓库克隆预定义模板来创建新的文档项目。

mint new [directory] [flags]

选项	描述
`--name`	项目名称。在交互模式下未提供时，CLI 会提示输入。
`--theme`	项目主题。在交互模式下未提供时，CLI 会提示选择。
`--template`	预定义模板。在交互模式下未提供时，CLI 会提示选择。
`--force`	无需确认即覆盖目录。

`mint update`

将 CLI 更新到最新版本。

mint update

`mint version`

显示当前 CLI 和客户端版本。

mint version

即将推出

这些命令可以运行但尚未正式启用。运行它们会通过 CLI 遥测记录你的兴趣，并帮助确定下一步开发的优先级。

命令	描述
`mint ai`	AI 驱动的文档工具。
`mint mcp`	文档 MCP 服务器。

遥测

CLI 收集使用遥测数据以帮助改进 Mintlify。遥测数据包括命令名称、CLI 版本、操作系统、架构和 Node.js 版本。遥测数据还会记录 CLI 是否在 CI 环境中运行，以及是否在交互式终端中运行。如果 CLI 检测到有 AI 编码代理在运行它，遥测数据还会包含该代理的名称。如果你已登录，遥测事件还会包含你的账户电子邮件地址。未登录时的使用保持匿名，退出登录会删除已存储的电子邮件。Mintlify 不会收集项目内容或文件路径。默认情况下，CLI 会收集遥测数据。你可以随时使用 --telemetry 选项退出：

# 禁用遥测
mint --telemetry false

# 重新启用遥测
mint --telemetry true

你也可以通过设置以下环境变量来禁用遥测：

变量	值	描述
`MINTLIFY_TELEMETRY_DISABLED`	`1`	禁用 Mintlify CLI 遥测。
`DO_NOT_TRACK`	`1`	使用 Console Do Not Track 标准禁用遥测。

你的偏好保存在 ~/.config/mintlify/config.json 中，在 CLI 会话之间持久有效。

​全局选项

​mint dev

​mint index

​选项

​选择客户端

​配置和规则

​mint signup

​示例

​mint login

​mint logout

​mint status

​mint add-domain

​示例

​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

​示例

​mint config

​配置键

​mint broken-links

​mint a11y

​mint validate

​mint test

​前置条件

​回顾上一次运行

​输出

​mint export

​mint score

​示例

​检查项

​mint format

​mint new

​mint update

​mint version

​即将推出

​遥测

全局选项

`mint dev`

`mint index`

选项

选择客户端

配置和规则

`mint signup`

示例

`mint login`

`mint logout`

`mint status`

`mint add-domain`

示例

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

示例

`mint config`

配置键

`mint broken-links`

`mint a11y`

`mint validate`

`mint test`

前置条件

回顾上一次运行

输出

`mint export`

`mint score`

示例

检查项

`mint format`

`mint new`

`mint update`

`mint version`

即将推出

遥测