> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI4N2E5MzAzZC0wMjMyLTQ3N2UtOGY1NC02Mzc2ZDhiYWU4YTAiLCJleHAiOjE3NzgzNjI2NTcsImlhdCI6MTc3ODM2MjM1N30.wKcOCeTEjOJIdm1UKRNAbrA48sLFK7bXSY14lqv6cwE
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 命令

> Fern CLI 所有命令的完整参考，用于生成 SDK 和开发者文档。

| 命令                                    | 描述                                           |
| ------------------------------------- | -------------------------------------------- |
| [`fern init`](#fern-init)             | 从 OpenAPI 规范或从头开始创建新的 Fern 项目                |
| [`fern check`](#fern-check)           | 验证 API 定义和配置                                 |
| [`fern upgrade`](#fern-upgrade)       | 将 Fern CLI 和生成器更新到最新版本                       |
| [`fern login`](#fern-login)           | 通过 GitHub、Google、Postman 或企业 SSO 登录 Fern CLI |
| [`fern logout`](#fern-logout)         | 从 Fern CLI 注销                                |
| [`fern export`](#fern-export)         | 导出 API 的 OpenAPI 规范                          |
| [`fern api update`](#fern-api-update) | 手动更新 OpenAPI 规范                              |
| [`fern api enrich`](#fern-api-enrich) | 将覆盖文件中的 `x-fern-examples` 合并到原生 OpenAPI 示例中  |

## 文档命令

| 命令                                                                               | 描述                         |
| -------------------------------------------------------------------------------- | -------------------------- |
| [`fern docs dev`](#fern-docs-dev)                                                | 运行本地文档预览服务器                |
| [`fern docs diff`](#fern-docs-diff) <Badge intent="warning" minimal>Beta</Badge> | 生成预览和生产文档之间的视觉差异           |
| [`fern generate --docs`](#fern-generate---docs)                                  | 构建并发布文档更新                  |
| [`fern docs preview list`](#fern-docs-preview-list)                              | 列出所有预览部署                   |
| [`fern docs preview delete`](#fern-docs-preview-delete)                          | 删除预览部署                     |
| [`fern docs md check`](#fern-docs-md-check)                                      | 验证文档文件中的 MDX 语法            |
| [`fern docs theme export`](#fern-docs-theme-export)                              | 从 `docs.yml` 导出主题兼容字段到独立目录 |
| [`fern docs theme upload`](#fern-docs-theme-upload)                              | 上传主题到 Fern 注册表             |
| [`fern docs theme list`](#fern-docs-theme-list)                                  | 列出组织的所有主题                  |

## SDK 生成命令

| 命令                                                  | 描述                                                                         |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| [`fern generate`](#fern-generate)                   | 构建并发布 SDK 更新                                                               |
| [`fern write-definition`](#fern-write-definition)   | 将 OpenAPI 规范转换为 [Fern Definition](/learn/api-definitions/ferndef/overview) |
| [`fern write-overrides`](#fern-write-overrides)     | 创建 OpenAPI 自定义                                                             |
| [`fern generator upgrade`](#fern-generator-upgrade) | 将 SDK 生成器更新到最新版本                                                           |

## 详细命令文档

<AccordionGroup>
  <Accordion title="fern init">
    使用 `fern init` 在当前文件夹中初始化新的 Fern 工作空间。默认情况下，您将看到 IMDb API 示例。

    <CodeBlock title="terminal">
      ```bash
      fern init [--docs] [--openapi <path/url>]
      ```
    </CodeBlock>

    使用 OpenAPI 初始化时，您的项目结构将如下所示：

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="generators.yml" comment="您使用的生成器" />

        <Folder name="openapi" defaultOpen>
          <File name="openapi.json" comment="您的 OpenAPI 规范" />
        </Folder>
      </Folder>
    </Files>

    对于 Fern Definition 初始化（不使用 OpenAPI），您将看到以下结构：

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="generators.yml" comment="您使用的生成器" />

        <Folder name="definition" defaultOpen>
          <File name="api.yml" comment="API 级别配置" />

          <File name="imdb.yml" comment="端点、类型和错误" />
        </Folder>
      </Folder>
    </Files>

    ### openapi

    使用 `--openapi` 从 OpenAPI 规范初始化项目：

    ```bash
    # 从本地文件初始化
    fern init --openapi ./path/to/openapi.yml

    # 从 URL 初始化
    fern init --openapi https://link.buildwithfern.com/petstore-openapi
    ```

    ### docs

    通过添加 `--docs`，您还将获得一个包含 API Reference 部分的示例文档网站。

    ```bash
    fern init --docs
    ```

    添加的文件将包含：

    ```yaml docs.yaml
    instances:
      - url: https://your-organization.docs.buildwithfern.com
    title: Your Organization | Documentation
    navigation:
      - api: API Reference
    colors:
    accent-primary: '#ffffff'
    background: '#000000'
    ```

    要发布 API 文档，请运行 [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs)。

    ### mintlify

    通过添加 `--mintlify PATH_TO_MINT_CONFIG`，CLI 将根据 `mint.json` 文件自动将您的 Mintlify 文档文件夹转换为 Fern 文档网站。

    ```bash
    fern init --mintlify PATH_TO_MINT_CONFIG
    ```

    CLI 将创建一个具有以下结构的 `fern/` 文件夹：

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" comment="根级配置" />

        <File name="docs.yml" comment="文档配置" />

        <File name="..." comment="文档中需要的任何其他文件/页面" />
      </Folder>
    </Files>

    ### readme

    `fern init` 命令支持导入 Readme 生成的文档网站。这需要安装本地 chromium 浏览器实例。
    您可以通过从源代码安装 `fern` cli 来确保已安装，请按照[这里](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md)的说明进行操作。

    通过添加 `--readme URL_TO_README_DOCS_SITE`，CLI 将自动将 Readme 生成的文档网站转换为 Fern 文档网站。

    ```bash
    fern init --readme URL_TO_README_DOCS_SITE
    ```

    CLI 将创建一个具有以下结构的 `fern/` 文件夹：

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" comment="根级配置" />

        <File name="docs.yml" comment="文档配置" />

        <File name="..." comment="文档中需要的任何其他文件/页面" />
      </Folder>
    </Files>

    <Tip>
      有关入门的更多信息，请查看我们的[快速入门指南](/learn/docs/getting-started/quickstart)
    </Tip>
  </Accordion>

  <Accordion title="fern export">
    使用 `fern export` 为您的 API 生成 OpenAPI 规范。

    当您以 OpenAPI 以外的格式（例如 [Fern Definition](/api-definitions/ferndef/overview)）定义了 API 并需要将其导出为 OpenAPI 规范以与其他工具或服务集成时，此命令非常有用。

    <CodeBlock title="terminal">
      ```bash
      fern export [--api <api>] path/to/openapi.yml
      fern export [--api <api>] path/to/openapi.json
      ```
    </CodeBlock>

    ### api

    当您在 `fern/apis/` 文件夹中定义了多个 API 时，使用 `--api` 指定要导出的 API。

    <CodeBlock title="terminal">
      ```bash
      fern export --api public-api path/to/openapi.yml
      fern export --api public-api path/to/openapi.json
      ```
    </CodeBlock>
  </Accordion>

  <Accordion title="fern generate">
    使用 `fern generate` 运行 Fern 编译器并为您的 API 创建 SDK。

    <CodeBlock title="terminal">
      ```bash
      fern generate [--group <group>] [--api <api>] [--version <version>] [--preview] [--fernignore <path>] [--local] [--force]
      ```
    </CodeBlock>

    ### group

    使用 `--group <group>` 指定要运行的生成器组。您可以使用组名或别名。别名在您的 [`generators.yml`](/learn/sdks/reference/generators-yml#aliases) 中定义并映射到多个组，允许您通过单个命令并行运行多个组。

    ```bash
    # 运行特定组
    fern generate --group python-sdk

    # 运行在"all"别名中定义的所有组
    fern generate --group all

    # 运行在"frontend"别名中定义的所有组
    fern generate --group frontend

    # 本地运行特定组（自托管）
    fern generate --group python-sdk --local
    ```

    您还可以在 `generators.yml` 中将别名设置为 `default-group`，这样运行不带任何参数的 `fern generate` 将运行该别名中的所有组。

    `--group` 标志可以与其他标志组合使用，如用于[自托管 SDK 生成](/learn/sdks/deep-dives/self-hosted)的 `--local`、用于本地测试的 `--preview` 或用于指定 SDK 版本的 `--version`。

    ### preview

    使用 `--preview` 在发布前本地测试 SDK 更改。这在开发期间特别有用：

    * 将 SDK 生成到本地 `.preview/` 文件夹
    * 允许在 Fern 定义上快速迭代
    * 不会将更改发布到包管理器或 GitHub

    ```bash
    # 预览所有 SDK
    fern generate --preview

    # 预览特定 SDK 组
    fern generate --group python-sdk --preview
    ```

    ### api

    使用 `--api <api>` 为 SDK 生成指定 API。当项目包含多个 API 定义时这很有用。API 名称应与 `fern/apis/` 文件夹中的目录名称匹配。

    ```bash
    fern generate --api public-api
    ```

    ### version

    使用 `--version` 指定 SDK 版本号，通常遵循语义版本控制（semver）格式（`MAJOR.MINOR.PATCH`）。这在发布 SDK 版本的 CI/CD 流水线中特别有用。

    ```bash
    # 使用版本 2.11.0 生成所有 SDK
    fern generate --version 2.11.0

    # 为支付 API 的 Python SDK 生成版本 1.2.3
    fern generate --api payments-api --group python-sdk --version 1.2.3
    ```

    ### fernignore

    使用 `--fernignore` 为 SDK 生成指定自定义 `.fernignore` 文件路径。这允许您临时测试不同的忽略配置，而无需修改存储库中已提交的 `.fernignore`。

    Fern 将使用指定的文件而不是主分支上的文件，并将新的 `.fernignore` 作为生成过程的一部分提交到您的存储库。

    ```bash
    fern generate --fernignore ./custom-fernignore
    ```

    ### local

    使用 `--local` 在您自己的机器上运行 SDK 生成，而不是使用 Fern 的云基础设施。这对于有严格安全或合规要求的组织很有用。请参阅[自托管 SDK](/learn/sdks/deep-dives/self-hosted) 获取设置说明。

    ```bash
    # 本地生成所有 SDK
    fern generate --local

    # 本地生成特定 SDK 组
    fern generate --group python-sdk --local
    ```

    <Note>
      您的机器上必须运行 Docker 守护进程，因为 SDK 生成在 Docker 容器内运行。
    </Note>

    默认情况下，CLI 从 Docker Hub 拉取生成器镜像。要从自定义容器注册表拉取，请在您的 `generators.yml` 中使用 [`image` 字段](/learn/sdks/reference/generators-yml#image) 而不是 `name`。请参阅[自定义容器注册表](/learn/sdks/deep-dives/self-hosted#optional-configure-a-custom-container-registry)了解详细信息。

    ### force

    使用 `--force` 跳过生成过程中的确认提示。这在会阻塞流水线的交互式提示的 CI/CD 环境中很有用。

    ```bash
    # 不带确认提示生成
    fern generate --group python-sdk --force
    ```
  </Accordion>

  <Accordion title="fern check">
    <Warning>
      `--broken-links` 和 `--strict-broken-links` 标志已弃用。请在 `docs.yml` 中使用 [`broken-links` 验证规则](/learn/docs/configuration/site-level-settings#check-configuration)。

      您还可以使用 [Fern Dashboard](https://dashboard.buildwithfern.com/) 验证实时发布网站上的内部和外部链接。
    </Warning>

    使用 `fern check` 验证您的 API 定义和 Fern 配置，包括 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson)、`generators.yml` 和 `docs.yml`。它检查损坏的链接、无效的 API 示例、配置错误等。当所有检查通过时，该命令不产生输出。

    <CodeBlock title="terminal">
      ```bash
      fern check [--api <api>] [--warnings]
      ```
    </CodeBlock>

    您可以在 `docs.yml` 文件中[使用 `check.rules` 属性](/learn/docs/configuration/site-level-settings#check-configuration)配置 `fern check` 运行的验证规则的严重性。

    ```yaml docs.yml
    check:
      rules:
        broken-links: error
        example-validation: warn
        missing-redirects: error
    ```

    ### api

    使用 `--api <api>` 指定要检查的 API。

    ```bash
    fern check --api public-api
    ```

    ### warnings

    使用 `--warnings` 除了记录错误外还记录警告。

    ```bash
    fern check --warnings
    ```

    ## 在 GitHub Action 中使用

    <CodeBlock title=".github/workflows/fern-check.yml">
      ```yml maxLines=14 
      name: Fern Validation Check

      on:
        pull_request:
        push:
          branches:
            - main

      jobs:
        validate-fern-api:
          name: Validate using Fern's linter
          runs-on: ubuntu-latest
          steps:
            - name: Checkout repository
              uses: actions/checkout@v4

            - name: Install Fern CLI
              run: npm install -g fern-api

            - name: Validate API with Fern
              run: fern check

      ```
    </CodeBlock>
  </Accordion>

  <Accordion title="fern generate --docs">
    使用 `fern generate --docs` 为您的 API 创建文档网站。

    <CodeBlock title="terminal">
      ```bash
      fern generate --docs [instance <instance-url>] [--preview] [--id <name>] [--force]
      ```
    </CodeBlock>

    ### instance

    使用 `--instance` 指定要为 `docs.yml` 中的哪个实例 URL 生成文档。

    ```bash
    fern generate --docs --instance your-organization.docs.buildwithfern.com
    ```

    ### preview

    使用 `--preview` 在将更改发布到生产网站之前预览文档更新。

    ```bash
    fern generate --docs --preview
    ```

    ### id

    使用 `--id` 与 `--preview` 一起创建稳定的命名预览链接。预览 URL 遵循格式 `{org}-preview-{id}.docs.buildwithfern.com`，因此使用相同的 `--id` 重新运行会就地更新现有预览，而不是创建新预览。

    ```bash
    fern generate --docs --preview --id my-feature
    # -> https://your-org-preview-my-feature.docs.buildwithfern.com
    ```

    这在您希望每个拉取请求有一个预览 URL 的 CI 工作流程中很有用。请参阅[预览更改](/learn/docs/preview-publish/preview-changes#preview-links)了解详细信息。

    ### force

    当重用已存在的 `--id` 时，Fern 会提示您确认覆盖。使用 `--force` 跳过确认。这在 GitHub Actions 中会自动检测到，但在其他 CI 环境（如 Azure Pipelines）中需要。

    ```bash
    fern generate --docs --preview --id my-feature --force
    ```
  </Accordion>

  <Accordion title="fern docs preview list">
    使用 `fern docs preview list` 列出您组织的所有预览部署。

    <CodeBlock title="terminal">
      ```bash
      fern docs preview list [--limit <number>] [--page <number>]
      ```
    </CodeBlock>

    ### limit

    使用 `--limit` 指定每页显示的预览部署数量。

    ```bash
    fern docs preview list --limit 20
    ```

    ### page

    使用 `--page` 指定要显示结果的页面。

    ```bash
    fern docs preview list --page 2
    ```
  </Accordion>

  <Accordion title="fern docs preview delete">
    使用 `fern docs preview delete` 删除使用 `fern generate --docs --preview` 生成的预览部署。`<url>` 参数是要删除的完整预览 URL。

    <CodeBlock title="terminal">
      ```bash
      fern docs preview delete <url>
      ```
    </CodeBlock>
  </Accordion>

  <Accordion title="fern docs dev">
    使用 `fern docs dev` 运行本地开发服务器来预览您的文档。

    <CodeBlock title="terminal">
      ```bash
      fern docs dev [--port <port-number>]
      ```
    </CodeBlock>

    <Warning title="Windows: 启用长路径支持">
      在 Windows 上，`fern docs dev` 需要启用[长路径支持](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later)。

      要启用长路径支持，请在提升的 PowerShell 提示符中运行以下命令，然后重启您的终端：

      ```powershell
      New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force
      ```

      如果您无法启用长路径支持，请使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 在 Linux 环境中运行 `fern docs dev`。
    </Warning>

    ### port

    使用 `--port <port-number>` 指定文档预览运行的端口。

    ```bash
    fern docs dev --port 57908
    ```
  </Accordion>

  <Accordion title="fern docs md check">
    使用 `fern docs md check` 验证导航配置中引用的所有文档页面的 MDX 语法，包括 `docs.yml`、版本配置文件和产品特定的 YAML 文件。

    <CodeBlock title="terminal">
      ```bash
      fern docs md check
      ```
    </CodeBlock>

    该命令解析每个 MDX 文件并报告语法错误，包含文件路径和行:列号。该命令考虑 frontmatter 偏移量，因此报告的行号与文件中的实际行对应。

    ```plaintext
    fern/pages/quickstart.mdx:12:5
      Unexpected closing tag, expected corresponding closing tag for `<CodeBlock>`

    fern/pages/guide.mdx:45:1
      Expected a closing tag for `<Note>` before the end of `paragraph`
    ```

    当所有文件都有效时，您将看到成功消息：

    ```plaintext
    ✓ All 42 MDX files are valid
    ```
  </Accordion>

  <Accordion title="fern docs diff">
    <Badge intent="warning" minimal>
      Beta
    </Badge>

    使用 `fern docs diff` 在预览部署和生产文档之间生成视觉差异。此命令旨在用于 [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml)。它捕获两个版本的截图并创建并排比较图像。

    <CodeBlock title="terminal">
      ```bash
      fern docs diff <preview-url> <files..> [--output <output-dir>]
      ```
    </CodeBlock>

    传递来自 `fern generate --docs --preview` 的预览 URL 和一个或多个 MDX 文件路径。差异图像默认保存到 `.fern/diff`。

    ```bash
    fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx fern/pages/quickstart.mdx
    ```

    ### output

    使用 `--output` 为差异图像指定自定义目录。

    ```bash
    fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx --output ./my-diffs
    ```
  </Accordion>

  <Accordion title="fern upgrade">
    使用 `fern upgrade` 将 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中的编译器版本升级到最新版本。它还将 `generators.yml` 中的生成器升级到其最低兼容版本。

    <CodeBlock title="terminal">
      ```bash
      fern upgrade
      ```
    </CodeBlock>
  </Accordion>

  <Accordion title="fern login">
    使用 `fern login` 通过 GitHub 或 Google 登录 Fern CLI。登录允许您加入 GitHub 组织、获得权限并为项目做出贡献。

    <CodeBlock title="terminal">
      ```bash
      fern login
      fern login --device-code
      fern login --email <email>
      ```
    </CodeBlock>

    默认情况下，`fern login` 打开浏览器进行 GitHub、Google 或 Postman 身份验证。有两种替代流程可用：

    ### device-code

    在无法自动打开浏览器的环境中（例如 SSH 会话或容器），使用 `--device-code` 通过设备代码授权登录。

    ```bash
    fern login --device-code
    ```

    ### email

    使用 `--email` 通过企业 SSO 登录。传递与您组织的 SSO 提供商关联的电子邮件地址。

    ```bash
    fern login --email user@example.com
    ```

    <Note>
      要启用 CI/CD，请使用 [`fern token`](/learn/cli-api/cli-reference/commands#fern-token)。
    </Note>
  </Accordion>

  <Accordion title="fern logout">
    使用 `fern logout` 从 Fern CLI 注销。这将清除您的身份验证凭据并撤销对您的 GitHub 组织和权限的访问。

    <CodeBlock title="terminal">
      ```bash
      fern logout
      ```
    </CodeBlock>

    注销后，您需要再次运行 [`fern login`](#fern-login) 来访问受保护的功能。
  </Accordion>

  <Accordion title="fern token">
    使用 `fern token` 生成一个用于在 CI/CD 环境中对 Fern CLI 进行身份验证的令牌。该令牌特定于您在 [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) 中定义的组织，并且不会过期。

    <CodeBlock title="terminal">
      ```bash
      fern token
      ```
    </CodeBlock>

    请参阅[发布您的文档](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions)，了解在自动化发布工作流程中使用此令牌的说明。
  </Accordion>

  <Accordion title="fern write-definition">
    使用 `fern write-definition` 将您的 OpenAPI 规范转换为 Fern Definition。您必须有一个包含 `.json` 或 `.yaml` 格式的 OpenAPI 规范文件的 `fern/openapi/` 文件夹。

    <CodeBlock title="terminal">
      ```bash
      fern write-definition [--api <api>]
      ```
    </CodeBlock>

    运行此命令时，会在 `fern/` 内创建一个名为 `.definition/` 的新文件夹。

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="generators.yml" />

        <Folder name="openapi" defaultOpen>
          <File name="openapi.json" />
        </Folder>

        <Folder name=".definition" defaultOpen comment="您的 Fern Definition" highlighted>
          <File name="api.yml" highlighted />

          <File name="__package__.yml" highlighted />
        </Folder>
      </Folder>
    </Files>

    <Warning>
      如果您没有看到 `.definition/` 文件夹，请使用适当的命令或配置来查看隐藏文件夹（在 `bash` 和 `zsh` 中使用 `ls -a`）。
    </Warning>

    如果您的 `fern/` 文件夹同时包含 `openapi/` 和 `definition/` 文件夹，Fern 默认读取您的 OpenAPI 规范。要使用您的 Fern Definition 作为输入，您必须：

    * 将 `.definition/` 文件夹重命名为 `definition/`。
    * 删除或重命名 `openapi/` 文件夹。例如，您可以将其重命名为 `.openapi/`。

    ### api

    如果您在 `fern/apis/` 文件夹中定义了多个 API，请使用 `--api` 指定要为其编写定义的 API。

    ```bash
    fern write-definition --api public-api
    ```
  </Accordion>

  <Accordion title="fern write-overrides">
    使用 `fern write-overrides` 生成基本的 OpenAPI 覆盖文件。覆盖文件允许对 API 规范进行可逆修改，包括为 Fern Docs 中的代码片段添加请求和响应示例。

    <CodeBlock title="terminal">
      ```bash
      fern write-overrides [--api <api>] [--exclude-models]
      ```
    </CodeBlock>

    运行此命令时，会在 `fern/openapi/` 内创建一个名为 `openapi-overrides.yml` 的新文件。

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="generators.yml" />

        <Folder name="openapi" defaultOpen>
          <File name="openapi-overrides.yaml" comment="您的覆盖文件" highlighted />

          <File name="openapi.json" />
        </Folder>
      </Folder>
    </Files>

    ### api

    如果定义了多个 API，请使用 `--api` 指定要对其运行命令的 API。

    ```bash
    fern write-overrides --api public-api
    ```

    ### exclude-models

    使用 `--exclude-models` 在生成初始覆盖时存根模型（除了端点）。

    ```bash
    fern write-overrides --exclude-models
    ```
  </Accordion>

  <Accordion title="fern generator upgrade">
    使用 `fern generator upgrade` 将 `generators.yml` 中的所有生成器更新到其最新版本。

    <Note>
      这与更新 Fern CLI 版本的 `fern upgrade` 不同。使用这两个命令来保持整个 Fern 工具链的最新状态。
    </Note>

    <CodeBlock title="terminal">
      ```bash
      fern generator upgrade [--list] [--generator <generator-name>] [--group <group>] [--include-major]
      ```
    </CodeBlock>

    此命令将：

    * 检查 `generators.yml` 中指定的所有生成器的更新
    * 将生成器版本更新到其最新兼容版本
    * 保持与当前 Fern 编译器版本的兼容性

    当有可用更新时，您可能会看到：

    ```plaintext
    ┌───────────────────────────────────────────────────────────────────────────────────┐
    │                                                                                   │
    │                                Upgrades available                                 │
    │                                                                                   │
    │                                                                                   │
    │             C# SDK (API: openapi, Group: csharp-sdk) 1.9.11 → 1.9.15              │
    │              Java SDK (API: openapi, Group: java-sdk) 2.2.0 → 2.11.3              │
    │           Python SDK (API: openapi, Group: python-sdk) 4.3.10 → 4.3.11            │
    │                                                                                   │
    │              Run fern generator upgrade to upgrade your generators.               │
    │   Run fern generator upgrade --list to see the full list of generator upgrades    │
    │                                    available.                                     │
    │                                                                                   │
    └───────────────────────────────────────────────────────────────────────────────────┘
    ```

    ### list

    使用 `--list` 查看可用生成器升级的完整列表。

    ```bash
    fern generator upgrade --list
    ```

    ### generator

    使用 `--generator` 指定要升级的特定生成器类型。

    ```bash
    fern generator upgrade --generator fernapi/fern-typescript-sdk
    fern generator upgrade --generator fernapi/fern-python-sdk
    ```

    ### group

    使用 `--group` 升级 `generators.yml` 中特定组内的生成器。如果未指定，将升级指定类型的所有生成器。

    ```bash
    fern generator upgrade --group public
    ```

    ### include-major

    ```bash
    fern generator upgrade --include-major
    ```

    使用 `--include-major` 包括主要版本升级。默认跳过主要版本以防止破坏性更改。
  </Accordion>

  <Accordion title="fern api update">
    从 `generators.yml` 中指定的 `origin` 拉取最新的 OpenAPI 规范并更新本地规范。或者，您可以[通过设置 GitHub Action 来自动化此过程](/api-definitions/openapi/sync-your-open-api-specification)。

    <CodeBlock title="terminal">
      ```bash
      fern api update [--api <api>]
      ```
    </CodeBlock>

    ### api

    如果 `generators.yml` 中有多个定义了 `origin` 的规范，请使用 `--api` 指定要更新的 API。如果您不指定 API，所有有 `origin` 的 OpenAPI 规范都将被更新。

    <CodeBlock title="terminal">
      ```bash
      fern api update --api public-api
      ```
    </CodeBlock>
  </Accordion>

  <Accordion title="fern api enrich">
    使用 `fern api enrich` 将 [AI 生成的示例](/learn/docs/ai-features/ai-examples)或手动创作的 [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) 转换为任何兼容 OpenAPI 的工具都可以使用的可移植 OpenAPI 示例。

    <CodeBlock title="terminal">
      ```bash
      fern api enrich <openapi> -f <overrides-file> -o <output-file>
      ```
    </CodeBlock>

    该命令将覆盖文件中的示例合并到原生 OpenAPI `example` 字段中，并从输出中剥离 `x-fern-examples` 键。当端点有多个示例时，每个示例都作为命名条目存储在复数 `examples` 字段下。

    该命令需要两个标志：

    * `-f`（或 `--file`）— 包含 `x-fern-examples` 的覆盖文件（例如，`ai_examples_override.yml`）。
    * `-o`（或 `--output`）— 丰富输出文件的路径。支持 `.yml` 和 `.json` 扩展名。

    ```bash
    # 输出为 YAML
    fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml

    # 输出为 JSON
    fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.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.*.example`
    * `response.body` → `responses.<status>.content.*.example`
  </Accordion>

  <Accordion title="fern docs theme export">
    使用 `fern docs theme export` 将 `docs.yml` 中的[主题兼容字段](/learn/docs/customization/global-themes)提取到独立目录中。导出的 `theme.yml` 及其资源然后可以通过 `fern docs theme upload` 上传。

    <CodeBlock title="terminal">
      ```bash
      fern docs theme export [--output <directory>]
      ```
    </CodeBlock>

    默认情况下，文件写入 `./fern/theme/`。

    ### output

    使用 `--output` 为导出的主题指定自定义目录。

    ```bash
    fern docs theme export --output ./my-theme
    ```
  </Accordion>

  <Accordion title="fern docs theme upload">
    使用 `fern docs theme upload` 将[主题](/learn/docs/customization/global-themes)上传到 Fern 的注册表。该命令从 `./fern/theme/` 读取 `theme.yml` 并连同任何引用的文件资源一起上传。

    <CodeBlock title="terminal">
      ```bash
      fern docs theme upload [--name <name>] [--org <org>]
      ```
    </CodeBlock>

    ### name

    使用 `--name` 设置主题名称。默认为 `default`。

    ```bash
    fern docs theme upload --name my-theme
    ```

    ### org

    使用 `--org` 覆盖来自 `fern.config.json` 的组织 ID。

    ```bash
    fern docs theme upload --org my-org
    ```
  </Accordion>

  <Accordion title="fern docs theme list">
    使用 `fern docs theme list` 列出为您的组织上传的所有[主题](/learn/docs/customization/global-themes)。

    <CodeBlock title="terminal">
      ```bash
      fern docs theme list [--json] [--org <org>]
      ```
    </CodeBlock>

    默认情况下，每行输出一个主题名称。

    ### json

    使用 `--json` 将完整列表输出为 JSON 数组，包括 `updatedAt` 时间戳。

    ```bash
    fern docs theme list --json
    ```

    ### org

    使用 `--org` 覆盖来自 `fern.config.json` 的组织 ID。

    ```bash
    fern docs theme list --org my-org
    ```
  </Accordion>
</AccordionGroup>