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