Redocly CLI 使用指南
查阅 redocly.com/docs/cli 获取最新的命令和选项——优先于训练数据。
Redocly CLI 涵盖 OpenAPI、AsyncAPI、Arazzo 和 Overlay 描述的 API 生命周期：lint、打包、转换、文档化和测试。
它还使用 recheck 检查文档项目的 Markdown。
项目根目录中的 redocly.yaml 是控制平面：每个命令都会读取它，并且规则集、特定 API 设置、装饰器和插件都位于其中。
运行之前
首先读取 redocly.yaml。它会告诉你：
apis下注册了哪些 API——它们的名称（如my-api）可作为命令快捷方式：redocly lint my-api。- 项目
extends了哪个规则集以及它覆盖了哪些规则。 - 哪些装饰器在打包时转换输出。
不带 API 参数运行的命令（如 lint 或 bundle）适用于 apis 中的每个条目。
使用 --config <path> 指向不同的配置文件。
快速参考
安装：npm i @redocly/cli@latest，或无需安装直接运行：npx @redocly/cli@latest <command>。Docker 镜像：redocly/cli。
| 命令 | 用途 | 分组 |
|---|---|---|
lint | 根据配置的规则验证 API 描述 | API 创作 |
split | 将单个文件描述拆分为多文件结构 | API 创作 |
introspect-mcp | 在 x-mcp 中记录实时 MCP 服务器的工具、提示和资源 [实验性] | API 创作 |
build-docs | 将 OpenAPI、AsyncAPI 或 GraphQL 描述渲染为 HTML 页面 (Redoc) | 文档渲染 |
preview | Redocly 项目的本地预览 | 文档渲染 |
recheck | 检查 Markdown 结构、文风和组织标签；--fix 可修复大多数结构性问题 | 文档检查 |
bundle | 将所有 $ref 解析到一个自包含文件中；应用装饰器和覆盖层 | CI 与交付 |
join | 将多个 API 描述合并为一个 [实验性] | CI 与交付 |
respect | 针对实时 API 运行 Arazzo 描述中描述的 API 测试 | API 测试与漂移 |
generate-arazzo | 根据 OpenAPI 描述生成一个 Arazzo 描述 | API 测试与漂移 |
proxy | 将实时 HTTP 流量捕获到 HAR 文件中，可选验证 [实验性] | API 测试与漂移 |
drift | 报告记录的流量与 OpenAPI 描述之间的差异，可选 --coverage [实验性] | API 测试与漂移 |
generate-spec | 从记录的流量推断 OpenAPI 3.2 描述；--openapi-version 3.1 目标为 3.1 [实验性] | API 测试与漂移 |
stats | 统计操作、模式、引用和其他指标 | 质量报告 |
score | 根据 AI 代理准备情况对 OpenAPI 描述评分 [实验性] | 质量报告 |
generate-client | 生成类型化、零依赖的 TypeScript 客户端 [实验性] | SDK 生成 |
eject-generator | 将内置生成器复制到仓库中进行编辑 [实验性] | SDK 生成 |
check-config | 检查 redocly.yaml 本身 | Redocly 配置 |
inspect-node-types | 显示指针处的节点类型，或列出所有节点及其类型 [实验性] | Redocly 配置 |
push | 将 API 描述推送到 Redocly 平台 | 平台 |
push-status | 跟踪正在进行的推送至平台的状态 | 平台 |
project clone | 将 Redocly 托管的项目克隆为 Git 仓库 [早期访问] | 平台 |
project pr create | 为克隆项目的当前分支打开拉取请求 [早期访问] | 平台 |
project pr status | 显示该拉取请求的状态、审查、检查项和预览 URL [早期访问] | 平台 |
skills | 将 Redocly CLI 代理技能安装到 .agents/skills/ 和检测到的代理文件夹中 | 代理设置 |
completion | 生成 Shell 自动补全命令 | Shell 设置 |
退出码：0 成功，1 发现问题或执行失败，2 配置错误。
使用 redocly.yaml 进行配置
extends:
- recommended # 或者：minimal, recommended-strict, spec
apis:
my-api:
root: ./openapi/openapi.yaml
rules:
no-ambiguous-paths: error # 特定 API 覆盖
decorators:
remove-x-internal: on # 仅适用于此 API
rules:
info-license: off
operation-operationId: error
extends 设置基础规则集；稍后同一文件中的 rules、preprocessors 和 decorators 会覆盖它。
规则严重级别：error（验证失败）、warn（报告但仍有效）、off。
可配置规则
当治理需求没有内置规则时，在 redocly.yaml 中的 rule/<name> 下声明一个。
使用 redocly-lint-rules 技能来实现此目的：它会选择最底层的梯级（内置规则、可配置规则或自定义插件），从 redocly inspect-node-types 获取节点类型，并针对夹具验证规则。
使用 recheck 检查 Markdown
recheck <paths> 检查给定路径下的 Markdown 文件的结构（markdownlint 规则集）、文风（禁止术语、拼写、标题大小写、句子长度、可读性）和 Markdoc 标签语法。
预设放在根 extends 中，调整放在 recheck 块中；lint 命令会忽略这两者：
extends:
- recommended
- recheck/markdown # 每条 markdownlint 规则；另有 recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
excludes: [CHANGELOG.md]
rules:
recheck/line-length: off
acme/no-via:
severity: warn
scope: sentence
message: '请使用“通过”代替“经由”。'
assertions:
pattern: { ignoreCase: true, tokens: ['\bvia\b'] }
没有 redocly.yaml 时，该命令使用 recheck/markdown。
如果有 redocly.yaml 但既没有预设也没有块，则它什么也不检查。
对于作为 API 描述的路径，或来自 apis 的别名，该命令会检查该 API 的 description 字段。
现有文件或文件夹的优先级高于同名的别名。
有用的标志：--fix、--rule=<name>（一次处理一条规则）、--format=github-actions|json|sarif、--max-problems=<n>、--generate-baseline（将现有错误记录在 .redocly.recheck-baseline.yaml 中，仅新错误才失败），以及 --readability（获取每个文件的可读性分数）。
使用 <!-- recheck-disable-next-line <rule> --> 静默单行，而不是关闭规则。
recheck-lint 技能涵盖在更改过的文件上运行它，recheck-config 技能涵盖调整该块。
使用装饰器进行转换
装饰器在打包时重写描述——lint 检查源代码的原样；bundle、build-docs 和 push 看到的是装饰后的输出。
内置装饰器包括 remove-x-internal、filter-in / filter-out、info-override、remove-unused-components 以及 *-description-override 系列。
join 会跳过所有装饰器，因此连接所需的转换需要先在每个 API 的 bundle 中运行。
当没有内置装饰器能满足转换需求时，按照 redocly-lint-rules 技能编写插件规则的方式编写一个自定义插件装饰器：从 redocly inspect-node-types 获取节点类型，通过将访问者嵌套在父类型下来限定其作用域（而不是手动遍历整个文档），在钩子中更改节点，并通过 redocly bundle 在一个包含该形状的夹具和一个不包含该形状的夹具上进行验证。
应用覆盖层
bundle 在打包的描述上应用 Overlay 1.0、1.1 和 1.2 文件，在装饰器之前：传递 --overlay <file>（可重复，按顺序应用），或者将它们列在 apis 条目下的 overlays 中，路径相对于 redocly.yaml。
--overlay 会替换已配置的列表。
操作目标针对打包后的输出运行，因此请对照没有覆盖层的 redocly bundle <api> 进行检查；不匹配任何内容的目标不会更改任何内容，也不会报告。
覆盖层值中的文件 $ref 相对于覆盖层文件，并且会被打包；装饰器（如 remove-x-internal）会看到覆盖层的更改。
两个具有相同 root 但不同 overlays 和 output 的 apis 条目会发布一个 API 的两个版本。
使用自定义插件进行扩展
当可配置规则和内置装饰器无法表达需求时，升级为自定义插件：一个导出规则、装饰器、预处理程序或配置的 JavaScript 模块，按文档格式键控：
export default function myPlugin() {
return {
id: 'my-plugin',
rules: {
oas3: {
'operation-id-not-test': () => ({
Operation(operation, { report, location }) {
if (operation.operationId === 'test') {
report({ message: 'operationId 不能为 "test"。', location });
}
},
}),
},
},
};
}
访问者键是节点类型：使用 redocly inspect-node-types <api> 确认它们。
装饰器在 decorators 键下具有相同的形状，redocly-lint-rules 技能涵盖了这两者的访问者模式：钩子、上下文、用于范围的嵌套访问者以及已解析与原始子项。
在 redocly.yaml 中注册它（路径相对于配置文件），并将其规则引用为 <plugin-id>/<rule-name>：
plugins:
- ./plugins/my-plugin.js
rules:
my-plugin/operation-id-not-test: error
生成 TypeScript 客户端
generate-client <api> --output client.ts 将 OpenAPI 描述转换为类型化客户端——一个自包含文件，具有零运行时依赖项（包含认证、重试、中间件、类型化 SSE、分页）。
在 redocly.yaml 中的 client 块下进行持久化配置，而不是使用标志：
client:
generators: [typescript, zod] # 附加项：tanstack-query, swr, mock, transformers；SDKs：python, go, php, java；或插件路径
outputMode: split
pagination: # 仅配置，无 CLI 标志
style: cursor
cursorParam: after
nextCursor: /page/endCursor
items: /items
apis:
my-api:
root: ./openapi/openapi.yaml
clientOutput: ./src/api/client.ts
设置 apis.<name>.clientOutput 后，仅运行 redocly generate-client 会为每个已选择的 API 生成客户端。
成功运行后，--report <file> 还会写入一个 JSON 文件，其中包含每个 API 的操作（id、name）和运行的警告，每个警告都有一个稳定的 kind。
client.telemetry: on（仅配置）使 typescript 生成器还写入 <output>.telemetry.ts（注册 use(telemetry({ sdkName, sdkVersion, client }))），而 go、python 和 php 生成器分别写入 telemetry.go、<module>_telemetry.py 和 <output>.telemetry.php，以计算每次操作的调用次数并每分钟发送一次计数（无请求数据；REDOCLY_SDK_TELEMETRY=off 或 DO_NOT_TRACK=1 禁用发送）。
API 自身的 client 块会整体替换顶层块——在其中重复共享字段。
使用 client.codeSamples: true 时，它还会写入 <output>.code-samples.yaml，这是一个添加 x-codeSamples 的覆盖层；将其添加到 API 的 overlays 中（或传递 --overlay），以便 bundle 将示例放入描述中。
在 Redocly 托管的项目上工作
redocly login 之后，project clone <organization>/<project> 会克隆 Redocly 平台托管的项目。
克隆使用 Redocly CLI 作为其 Git 凭据助手，因此 git pull 和 git push 无需令牌即可工作。
平台拒绝推送到默认分支：推送另一个分支，然后为其打开拉取请求：
git push -u origin fix-typo
redocly project pr create --title "修复了一个拼写错误" --body-file - <<'BODY'
修复了快速入门中的安装命令。
BODY
该命令将打印拉取请求 URL。
平台会在几分钟内构建一个预览；redocly project pr status 随后会显示状态、审查决定、检查项以及部署预览后的预览 URL。
测试实时 API
respect 将 Arazzo 描述作为测试套件针对正在运行的 API 执行，断言实际响应与描述匹配。
从 generate-arazzo <openapi> 开始以搭建工作流，然后手动细化步骤和成功标准。
步骤中遗漏的 parameters 或 requestBody 会从描述的示例中获取。
捕获流量并检查漂移
proxy 命令在 --port 上设置一个捕获代理，向 --target 转发请求。