命令
命令
了解 Fern CLI 命令。
命令
了解 Fern CLI 命令。
使用 fern init 在当前文件夹中初始化新的 Fern 工作区。默认情况下，你会看到 IMDb API 示例。
使用 OpenAPI 初始化时，你的项目结构如下所示：
使用 --openapi 从 OpenAPI 规范初始化项目：
通过添加 --docs，你还会得到一个 API 示例文档网站，包含 API 参考部分。
添加的文件将包含：
要发布 API 文档，运行 fern generate --docs。
通过添加 --mintlify PATH_TO_MINT_CONFIG，CLI 会自动根据 mint.json 文件将你的 Mintlify 文档文件夹转换为 Fern 文档站点。
CLI 将创建一个 fern/ 文件夹，结构如下：
fern init 命令支持导入 Readme 生成的文档站点。这需要本地安装 chromium 浏览器实例。
你可以按照这里的说明从源码安装 fern cli 来确保安装了这个依赖。
通过添加 --readme URL_TO_README_DOCS_SITE，CLI 会自动将 Readme 生成的文档站点转换为 Fern 文档站点。
CLI 将创建一个 fern/ 文件夹，结构如下：
更多关于入门的信息，请查看我们的快速入门指南
使用 fern export 为你的 API 生成 OpenAPI 规范。当你用 OpenAPI 以外的格式（如 Fern Definition）定义 API 并需要将其导出以集成其他工具或服务时，这很有用。
当你在 fern/apis/ 文件夹中定义了多个 API 时，使用 --api 指定要导出哪个 API。
使用 fern generate 运行 Fern 编译器并为你的 API 创建 SDK。
使用 --group <group> 指定要运行哪个生成器组。你可以使用组名或别名。别名在你的 generators.yml 中定义，映射到多个组，允许你通过单个命令并行运行多个组。
你也可以在 generators.yml 中设置别名作为 default-group，这样不带任何参数运行 fern generate 会运行该别名中的所有组。
--group 标志可以与其他标志组合使用，如用于自托管 SDK 生成的 --local、用于本地测试的 --preview 或用于指定 SDK 版本的 --version。
使用 --preview 在发布前本地测试 SDK 更改。这在开发期间特别有用：
.preview/ 文件夹使用 --api <api> 指定用于 SDK 生成的 API。当项目包含多个 API 定义时很有用。API 名称应匹配 fern/apis/ 文件夹中的目录名。
使用 --version 指定 SDK 版本号，通常遵循语义版本控制（semver）格式（MAJOR.MINOR.PATCH）。这在 CI/CD 流水线中发布 SDK 版本时特别有用。
使用 --fernignore 为 SDK 生成指定自定义 .fernignore 文件路径。这允许你临时测试不同的忽略配置，而不修改仓库中提交的 .fernignore。
Fern 将使用指定的文件而不是主分支上的文件，并将新的 .fernignore 作为生成过程的一部分提交到你的仓库。
使用 --local 在你自己的机器上运行 SDK 生成，而不是使用 Fern 的云基础设施。这对于有严格安全或合规要求的组织很有用。设置说明请参阅自托管 SDK。
你的机器上必须运行 Docker 守护进程，因为 SDK 生成在 Docker 容器内运行。
默认情况下，CLI 从 Docker Hub 拉取生成器镜像。要从自定义容器注册表拉取，在 generators.yml 中使用 image 字段而不是 name。详见自定义容器注册表。
使用 --force 在生成期间跳过确认提示。这在 CI/CD 环境中很有用，因为交互式提示会阻塞流水线。
--broken-links 和 --strict-broken-links 标志已弃用。请改用 docs.yml 中的 broken-links 验证规则。
使用 fern check 验证你的 API 定义和 Fern 配置，包括 fern.config.json、generators.yml 和 docs.yml。它检查失效链接、无效的 API 示例、配置错误等。当所有检查通过时，命令不产生输出。
大多数 fern check 规则——包括 broken-links——根据从本地配置构建的导航树进行验证，不会爬取你的实时部署站点或跟踪外部 URL。例外是 missing-redirects 规则，它将本地导航与先前发布的状态进行比较，因此需要 fern login 或 FERN_TOKEN。
你可以使用 check.rules 属性在 docs.yml 文件中配置 fern check 运行的验证规则的严重性。
要检查已发布站点上的链接，请改用 fern docs link check 或 Fern Dashboard 中的链接检查器。
使用 --api <api> 指定要检查的 API。
使用 --warnings 除了错误外还记录警告。
使用 fern generate --docs 为你的 API 创建文档站点。
使用 --instance 指定 docs.yml 中的哪个实例 URL 用于生成文档。
使用 --preview 在发布更改到生产站点之前预览文档更新。
与 --preview 一起使用 --id 创建稳定的命名预览链接。预览 URL 遵循格式 {org}-preview-{id}.docs.buildwithfern.com，因此用相同的 --id 重新运行会就地更新现有预览，而不是创建新的。
这在 CI 工作流中很有用，你希望每个拉取请求有一个预览 URL。详见预览更改。
当重用已存在的 --id 时，Fern 会提示你确认覆盖。使用 --force 跳过确认。这在 GitHub Actions 中会自动检测，但在其他 CI 环境（如 Azure Pipelines）中需要。
使用 fern docs preview list 列出你组织的所有预览部署。
使用 --limit 指定每页显示的预览部署数量。
使用 --page 指定显示哪一页结果。
使用 fern docs preview delete 删除用 fern generate --docs --preview 生成的预览部署。<url> 参数是要删除的完整预览 URL。
使用 fern docs dev 运行本地开发服务器来预览你的文档。
在 Windows 上，fern docs dev 需要启用长路径支持。
要启用长路径支持，在提升的 PowerShell 提示符中运行以下命令，然后重启终端：
如果无法启用长路径支持，请使用 Windows Subsystem for Linux (WSL) 在 Linux 环境中运行 fern docs dev。
使用 --port <port-number> 指定文档预览运行的端口。
使用 fern docs link check 扫描实时文档站点以查找失效链接。该命令爬取已发布的站点，检查每个链接，并报告失效（404）和被阻止（403）的 URL 及其来源页面。
与 fern check 中只验证本地 YAML 导航树中内部链接的 broken-links 规则不同，fern docs link check 检查实时部署站点上的所有链接——内部和外部。
默认情况下，命令从 docs.yml 中的 instances 自动检测你的文档 URL。当所有链接有效时，命令以成功消息退出。
命令首先抓取站点上的每个页面，然后检查找到的每个链接。当发现失效链接时，输出包括摘要和按状态码和源文件路径分组的失效 URL 列表。
使用 --url 指定要检查的文档站点。当你有多个实例或想检查预览部署时很有用。
使用 --output 控制输出格式。支持的值有 text（默认）、json 和 csv。
使用 fern docs md check 验证导航配置中引用的所有文档页面的 MDX 语法，包括 docs.yml、版本化配置文件和产品特定的 YAML 文件。
该命令解析每个 MDX 文件并报告语法错误，包含文件路径和行:列号。命令考虑前言偏移，因此报告的行号对应文件中的实际行。
当所有文件有效时，你会看到成功消息：
使用 fern docs diff 在预览部署和生产文档之间生成可视化差异。此命令旨在用于 GitHub Actions。它捕获两个版本的截图并创建并排比较图像。
传入来自 fern generate --docs --preview 的预览 URL 和一个或多个 MDX 文件路径。差异图像默认保存到 .fern/diff。
使用 --output 为差异图像指定自定义目录。
使用 fern upgrade 将 fern.config.json 中的编译器版本升级到最新版本。它还会将 generators.yml 中的生成器升级到其最低兼容版本。
使用 fern login 通过 GitHub 或 Google 登录 Fern CLI。登录后，你可以加入 GitHub 组织、获得权限并贡献项目。
默认情况下，fern login 打开浏览器进行 GitHub、Google 或 Postman 认证。有两种替代流程可用：
在浏览器无法自动打开的环境中（如 SSH 会话或容器），使用 --device-code 通过设备代码授权登录。
使用 --email 通过企业 SSO 登录。传入与组织 SSO 提供商关联的邮箱地址。
要启用 CI/CD，使用 fern token。
使用 fern logout 退出登录 Fern CLI。这将清除你的认证凭据并撤销对 GitHub 组织和权限的访问。
退出登录后，你需要再次运行 fern login 来访问受保护的功能。
使用 fern token 生成一个用于在 CI/CD 环境中对 Fern CLI 进行身份验证的令牌。该令牌特定于您在 fern.config.json 中定义的组织，并且不会过期。
请参阅发布你的文档了解在自动化发布工作流中使用此令牌的说明。
使用 fern write-overrides 生成基本的 OpenAPI 覆盖文件。覆盖文件允许对 API 规范进行可逆修订，包括为 Fern Docs 中的代码片段添加请求和响应示例。
运行时，此命令在 fern/openapi/ 中创建一个名为 openapi-overrides.yml 的新文件。
如果定义了多个 API，使用 --api 指定要运行命令的 API。
使用 --exclude-models 在生成初始覆盖时排除模型（除了端点）。
使用 fern generator upgrade 将 generators.yml 中的所有生成器更新到最新版本。
这与更新 Fern CLI 版本的 fern upgrade 不同。使用这两个命令来保持整个 Fern 工具链最新。
此命令将：
generators.yml 中指定的所有生成器的更新当有可用更新时，你可能会看到：
使用 --list 查看可用生成器升级的完整列表。
使用 --generator 指定要升级的特定生成器类型。
使用 --group 升级 generators.yml 中特定组内的生成器。如果未指定，指定类型的所有生成器都会被升级。
使用 --include-major 包含主要版本升级。默认跳过主要版本以防止破坏性更改。
从 generators.yml 中指定的 origin 拉取最新的 OpenAPI 规范并更新本地规范。或者，你可以通过设置 GitHub Action 来自动化此过程。
如果 generators.yml 中有多个定义了 origin 的规范，使用 --api 指定要更新的 API。如果不指定 API，所有有 origin 的 OpenAPI 规范都会被更新。
使用 fern api enrich 将 AI 生成的示例或手动编写的 x-fern-examples 转换为任何 OpenAPI 兼容工具都可以使用的可移植 OpenAPI 示例。
该命令将覆盖文件中的示例合并到原生 OpenAPI example 字段中，并从输出中删除 x-fern-examples 键。当端点有多个示例时，每个示例都作为命名条目存储在复数 examples 字段下。
该命令需要两个标志：
-f（或 --file）— 包含 x-fern-examples 的覆盖文件（如 ai_examples_override.yml）。-o（或 --output）— 丰富输出文件的路径。支持 .yml 和 .json 扩展名。每个 x-fern-examples 字段都映射到其标准 OpenAPI 位置：
path-parameters → parameters[].example（其中 in: path）query-parameters → parameters[].example（其中 in: query）headers → parameters[].example（其中 in: header）request → requestBody.content.*.exampleresponse.body → responses.<status>.content.*.example使用 fern docs theme export 从你的 docs.yml 中提取符合主题条件的字段到独立目录。导出的 theme.yml 及其资源然后可以用 fern docs theme upload 上传。
默认情况下，文件被写入 ./fern/theme/。
使用 --output 为导出的主题指定自定义目录。
使用 fern docs theme upload 将主题上传到 Fern 的注册表。该命令从 ./fern/theme/ 读取 theme.yml 并将其与任何引用的文件资源一起上传。
使用 --name 设置主题名称。默认为 default。
使用 --org 覆盖 fern.config.json 中的组织 ID。
使用 fern docs theme list 列出为你组织上传的所有主题。
默认情况下，每行输出一个主题名称。
使用 --json 输出完整列表作为 JSON 数组，包括 updatedAt 时间戳。
使用 --org 覆盖 fern.config.json 中的组织 ID。