跳转到主要内容
若要安装 CLI,请参阅安装 CLI。

全局选项

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

mint dev

启动文档的本地预览。

mint signup

从交互式终端创建新的 Mintlify 账户。
不带任何 flag 运行该命令即可以交互方式输入你的信息。CLI 会提示你输入未通过 flag 传入的值。 提交信息后,Mintlify 会向你的邮箱发送一封验证邮件。该命令会一直等待,直到你点击验证链接后,才会创建你的账户、为你登录并保存凭据。完成后,打开控制台来连接你的仓库并开始构建。
在你点击验证链接之前,mint signup 不会返回,而这可能需要几分钟。当 AI agent 运行 mint signup,或该命令在非交互式终端中运行时,它会输出 agent 注册指南,而不会创建账户。Agent 可以通过 Agent 注册 在没有账户的情况下创建站点。

示例


mint deploy

无需账户即可创建站点,并获取对其的 Git 推送权限。有关完整流程,请参阅代理注册。
在同一目录中再次运行该命令,可为同一站点获取新的写入令牌。在 GitHub Actions 中,mint deploy 会将检出的提交推送到信任该仓库的站点。工作流需要 id-token: write 权限。

示例


mint claim

认领通过 mint deploy 创建的站点。
运行 mint claim 获取认领链接。站点所有者打开链接,使用任意账户登录并点击 Confirm;站点随即移至其账户中的一个新组织。--email 和 --code 不能同时使用。

示例


mint login

使用你的 Mintlify 账户进行身份验证。
打开浏览器窗口完成身份验证。如果浏览器未打开,CLI 会显示一个 URL 供你手动打开,并提示你粘贴授权代码。CLI 会将你的凭据存储在操作系统的凭据存储中,例如 macOS 上的钥匙串。 如果你有多个项目,CLI 会在登录后提示你选择一个默认项目。你可以稍后使用 mint config set subdomain <subdomain> 更改默认项目。

mint logout

移除已存储的凭据。

mint status

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

mint add-domain

从终端为你的项目添加一个自定义域名。需要使用 mint login 进行身份验证。
该命令使用通过 mint config 配置的子域名。如果未设置,则使用账户中的第一个子域名。 域名注册后,CLI 将等待最长 10 秒以生成 DNS 记录,然后打印需要在你的域名提供商处添加的 TXT 和 CNAME 记录:
请先添加 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 的反向代理。有关按服务商分类的指南,请参见将文档托管在子路径下。

示例

在根路径添加自定义域名:
添加自定义域名并将文档托管在 /docs:

mint analytics

从终端查询文档分析数据。需要使用 mint login 进行身份验证。
分析功能需要 Pro 或 Enterprise 计划。
所有子命令都接受以下共享选项:

mint analytics stats

显示某个日期范围内的核心 KPI:浏览量、访客数、搜索次数、反馈和 assistant 使用情况。人类流量和 agent 流量分别报告。
显示搜索查询,包括命中次数、点击率、点击最多的页面和最后搜索日期。

mint analytics feedback

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

mint analytics conversation

查看 assistant 对话分析数据。

mint analytics conversation list

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

mint analytics conversation view

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

mint analytics conversation buckets list

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

mint analytics conversation buckets view

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

示例


mint agent setup

设置 AI 编码代理以处理你的 Mintlify 项目。该命令会安装 Mintlify 技能,并为 Claude Code、Codex 或 Cursor 配置管理员 MCP。
mint agent setup 需要 Node.js 22.20 或更高版本以及 npm。CLI 无法在 Node.js 25 上运行。
在没有交互式终端的情况下,该命令会配置它检测到的代理。如果未检测到任何代理,请传入 --agent。 该命令会将名为 mintlify、URL 为 https://mcp.mintlify.com 的 MCP 服务器添加到每个代理的配置文件中。 如果你的 Codex 配置将 mcp_servers 定义为内联表,设置无法向其中添加条目,并会报错停止。请自行在该内联表中添加一个带有 url = "https://mcp.mintlify.com" 的 mintlify 条目。 如果设置了 CLAUDE_CONFIG_DIR,针对 Claude Code 的 --global 设置会报错停止。请改用 Claude Code CLI 添加该服务器:
设置过程会保留你现有的配置,并跳过已存在匹配的 mintlify 条目的代理。如果某个 mintlify 条目的配置不同,或者某个配置文件无法解析,设置会在安装技能之前停止。请重命名或删除冲突的条目,然后再次运行该命令。 设置只会查找名为 mintlify 的条目。如果某个代理已经以其他名称(例如 mintlify-admin)连接到管理员 MCP,设置会再添加一个条目。请删除其中一个,以免代理两次连接到管理员 MCP。 重新运行该命令会刷新已安装的技能,并覆盖你对它们所做的任何本地修改。 该命令不会让你登录管理员 MCP,也不会复用你的 mint login 凭据。设置完成后,请在每个代理中完成 OAuth 登录。该命令会为你配置的每个代理打印相应步骤。

示例


mint instructions

输出在 Mintlify 中完成某项任务的分步指导,专为 AI 编程 Agent 编写。每个主题涵盖一项常见工作,例如发布新站点或添加自定义域名。它会列出步骤、Agent 常犯错误的规则,以及如何验证结果。你的 Agent 可以在开始任务前运行该命令,而不是依赖其训练数据。 CLI 会从在线的 Mintlify 文档中获取每个主题,因此无需更新 CLI,指导内容也能保持最新。
不带主题时,该命令会列出可用主题以及各自的适用场景。带主题时,它会以 Markdown 格式输出该主题的指导内容。请从 overview 开始。 该命令需要联网。如果主题不存在,命令会以错误退出。运行 mint instructions 查看有效主题。 如果你安装的 CLI 无法识别该命令,请运行 mint update 或使用 npx mint@latest instructions。

示例


mint config

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

配置键


检查文档中的内部断链。
该命令会扫描 .mdx 和 .md 文件中的链接,并排除匹配 .mintignore 模式的文件。OpenAPI 规范文件(.yaml、.yml、.json)中的链接不会被检查。指向被忽略文件的链接会被报告为断链。 该命令会检查 Markdown 链接和图片,包括 [text][id] 这类引用式链接。它还会检查 <a> 和 <Card> 组件的 href,以及 <img> 和 <source> 标签的 src,无论它们是写成普通字符串,还是写成花括号中的固定值(例如 href={"/quickstart"})。由变量计算得出的值不会被检查。 不以 / 开头的链接(例如 quickstart 或 ../quickstart)会从包含它们的页面所在目录进行解析,与浏览器的解析方式相同。若要从站点根目录进行链接,请以 / 作为路径开头。 保留 .mdx 扩展名的根相对链接(例如 /quickstart.mdx)会被报告为失效,因为 Mintlify 提供的页面不带扩展名。请删除扩展名,或添加从 .mdx 路径到该页面的重定向。Markdown 链接和 href 值中的相对链接(例如 ./quickstart.mdx)没有问题,因为 Mintlify 会删除扩展名;但引用式链接定义(例如 [id]: ./quickstart.mdx)会保留扩展名,并被报告为失效。 对于代码片段中不以 / 开头的链接和锚点链接(#),该命令会检查每个渲染该代码片段的页面。只有当此类链接在其中至少一个页面上失效时,该命令才会报告它。使用 --check-anchors 时,代码片段中的标题会被视为渲染该代码片段的页面上的锚点。 使用 --files 将检查限定为特定页面。适用于验证你刚编辑过的某个页面,或在 CI 中将检查范围缩小到某个目录。当 --files 与 --check-external 一起使用时,仅会检查所选页面上的外部 URL。

mint a11y

检查文档中的无障碍性问题。
检查颜色对比度和图片、视频上缺失的替代文本。

mint validate

检查文档中的错误,然后以严格模式验证构建。包括对 docs.json 中引用的 OpenAPI 规范的自动验证。
mint validate 会针对你的页面、代码片段、导航和 OpenAPI 规范运行一组规则,然后执行严格构建。检查结果按文件分组输出,并在可用时显示每条结果的行号、列号和规则名称。 duplicate-h1、katex、foreign-syntax 和 url-collision 规则报告的是警告,因此它们的结果不会导致运行失败。其他规则报告的是错误。 只有在没有任何规则报告错误,且至少有一条所选规则需要构建时,才会执行严格构建。如果某条规则报告了错误,该命令会跳过构建,并提示你先修复错误。构建无法归因于某条规则的警告会以 build-failed 错误的形式导致运行失败。 使用 --fix 时,mint validate 最多执行五轮修复,因为一个修复可能会使另一个修复成为可能。例如,将 <br> 自闭合后,页面可能就能被解析。最后一轮结束后,所有规则会再运行一次,报告会显示剩余的问题。输出会以 fixed <file>:<line> <rule>: "before" → "after" 的格式列出每个已应用的修复。 --fix 会跳过与同一文件中另一个修复重叠的修复。如果修复后的内容解析情况比之前更差,它也会保持该 Markdown 或 MDX 文件不变。不使用 --fix 时,输出末尾会显示 --fix 可修复的问题数量。
在运行 --fix 之前,请先提交或暂存(stash)你的更改,以便审查它所做的修改。
使用 --format json 时,进度输出会被隐藏,其他控制台输出会写入 stderr,因此你可以直接解析 stdout。报告包含以下字段:
  • passed:没有任何规则报告错误时为 true。
  • summary:errors 和 warnings 的数量,以及包含每个规则 ID 计数的 byRule。
  • diagnostics:每条检查结果,包含 rule、group、severity(error 或 warning)、file、可选的 line 和 column、message,以及可选的 fix。
  • build:如果执行了严格构建,则为 { "ran": true, "passed": <boolean> };否则为 { "ran": false, "reason": <reason> },其中原因为 disabled、errors found 或 no build rules。
  • fixed:仅在使用 --fix 时出现。每个已应用的更改,包含 rule、file、可选的 line 和 column、before 和 after。
如果 mint validate 无法运行,它不会在 stdout 上输出任何内容,并会将 Error: <message> 写入 stderr。 该命令以下列退出码之一退出:
  • 0:没有任何规则报告错误。警告不会导致运行失败。
  • 1:至少有一条规则报告了错误。
  • 2:mint validate 无法运行,例如规则名称未知、--files 的值未匹配任何页面或代码片段,或程序崩溃。
请改用 mint validate,而不是已弃用的独立 mint openapi-check 命令。

mint og

将页面的社交预览图(OG 图片)渲染为 PNG 文件。该命令使用 docs.json 中的 thumbnails 设置、页面和分区的 thumbnail 覆盖配置,以及与线上站点相同的渲染代码。
当标题过长、两行无法容纳,未配置 logo 或 logo 加载失败,字体加载失败,或文本在 brand 背景上对比度较低时,该命令会打印警告。警告不会改变退出码。如果 docs.json 无效或页面不存在,命令以退出码 1 结束。

mint export

将文档导出为独立的 zip 存档,用于离线查看和分发。
有关详细信息,请参阅离线导出。

mint score

对公共文档站点运行代理就绪性检查。需要使用 mint login 进行身份验证。
该命令显示总体就绪性评分以及各项检查的通过/未通过指标。

示例

检查项

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

mint format

mint format 会就地重写文件。运行前请先提交或暂存你的更改,以便审查 diff。
将当前目录中的每个 .mdx 文件格式化为 Mintlify 的规范样式。该命令使用与 Web 编辑器相同的 MDX 解析器解析每个文件,如果规范化输出与原文不同,则就地重写文件。
在文档项目的根目录中运行该命令。它会遍历所有子目录,跳过 .gitignore 匹配的路径和任何 Mintlify 忽略规则匹配的路径。已经与规范化输出一致的文件将保持不变。
根据项目规模,运行 mint format 可能会产生大量更改。为避免合并冲突以及对其他进行中的工作引入更改,请先处理完所有重要的待合并分支,然后为格式化更改创建一个新分支,并在该分支上运行 mint format。
命令完成后,会打印重新格式化了多少个 MDX 文件以及有多少文件解析失败。如果有任何文件失败,命令将以退出码 1 结束,并打印文件路径和错误信息,这样你就可以在 CI 中运行它以强制执行一致的格式。示例流水线请参见 在 CI 中安装。

mint migrate

打印将现有文档站点迁移到 Mintlify 的分步说明,或将这些说明交给 AI 代理来完成迁移。
不带选项时,该命令会打印迁移工作流的概览,随后列出可用的主题和源平台。这些说明是为编码代理编写的,因此你可以将其粘贴到你的代理中,或让代理自行运行 mint migrate。 使用 --agent 时,CLI 会启动指定代理的命令行工具,并附带一个提示词,让其运行 mint migrate 并按照打印出的说明操作。你必须事先安装该代理的 CLI。如果 Mintlify CLI 找不到代理的 CLI,mint migrate 会以错误退出,错误信息中包含安装命令。

示例


mint new

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

mint update

将 CLI 和本地预览客户端更新到最新版本。

mint version

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

mint feedback

向 Mintlify 团队发送反馈。你无需登录。切勿在消息中包含 API 密钥、令牌、密码或其他机密信息。

示例


即将推出

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

遥测

CLI 收集使用遥测数据以帮助改进 Mintlify。遥测数据包括命令名称、CLI 版本、操作系统、架构和 Node.js 版本。遥测数据还会记录 CLI 是否在 CI 环境中运行、是否在交互式终端中运行、是否是 CLI 首次在你的机器上运行,以及你是否已登录。如果 CLI 检测到有 AI 编码代理在运行它,遥测数据还会包含该代理的名称。每个事件还包含一个会话标识符,用于将同一工作会话中的事件归为一组。CLI 将其存储在 ~/.config/mintlify/telemetry-session.json 中,并在闲置 30 分钟后更换。如果你已登录,遥测事件还会包含你的账户电子邮件地址。未登录时的使用保持匿名,退出登录会删除已存储的电子邮件。Mintlify 不会收集项目内容或文件路径。 默认情况下,CLI 会收集遥测数据。你可以随时使用 --telemetry 选项退出:
你也可以通过设置以下环境变量来禁用遥测: 你的偏好保存在 ~/.config/mintlify/config.json 中,在 CLI 会话之间持久有效。