From 7d89dcdf1c6f2aad79bc14932fa3e23e0cf381c6 Mon Sep 17 00:00:00 2001 From: Devin Date: Wed, 19 Aug 2026 20:58:42 +0000 Subject: [PATCH 1/3] Split CLI commands page into docs and SDK command references --- fern/docs.yml | 4 +- .../api-def/ferndef/export-openapi.mdx | 2 +- fern/products/api-def/openapi/automation.mdx | 2 +- .../api-def/openapi/extensions/examples.mdx | 2 +- fern/products/api-def/pages/overrides.mdx | 2 +- .../api-def/pages/project-structure.mdx | 2 +- .../cli-api-reference/cli-api-reference.yml | 8 +- .../pages/cli-get-started.mdx | 2 +- .../pages/cli-version-policy.mdx | 12 +- .../cli-api-reference/pages/docs-commands.mdx | 390 +++++++++++++ .../pages/{commands.mdx => sdk-commands.mdx} | 534 +++--------------- fern/products/docs/pages/ai/agent-setup.mdx | 2 +- fern/products/docs/pages/ai/ai-examples.mdx | 2 +- fern/products/docs/pages/ai/markdown.mdx | 2 +- fern/products/docs/pages/ai/mcp-server.mdx | 2 +- fern/products/docs/pages/ai/writer.mdx | 2 +- .../api-references/generate-graphql-ref.mdx | 2 +- .../pages/api-references/library-docs.mdx | 2 +- .../docs/pages/ask-fern/api-get-started.mdx | 2 +- .../docs/pages/changelog/2026-05-14.mdx | 2 +- .../writing-content/markdown-basics.mdx | 2 +- .../pages/customization/global-themes.mdx | 8 +- .../docs/pages/developer-tools/gitlab.mdx | 2 +- .../getting-started/self-service-setup.mdx | 2 +- .../pages/navigation/site-level-settings.mdx | 2 +- .../preview-changes-locally.mdx | 10 +- .../preview-publish/publishing-your-docs.mdx | 2 +- .../docs/pages/seo/configuring-slugs.mdx | 2 +- fern/products/docs/pages/seo/redirects.mdx | 2 +- fern/products/sdks/custom-code.mdx | 2 +- fern/products/sdks/deep-dives/self-hosted.mdx | 2 +- .../generators/csharp/publishing-to-nuget.mdx | 2 +- .../sdks/generators/csharp/quickstart.mdx | 2 +- .../go/publishing-to-go-package-manager.mdx | 2 +- .../sdks/generators/go/quickstart.mdx | 2 +- .../java/publishing-to-maven-central.mdx | 2 +- .../sdks/generators/java/quickstart.mdx | 2 +- .../php/publishing-to-packagist.mdx | 2 +- .../sdks/generators/php/quickstart.mdx | 2 +- .../generators/python/publishing-to-pypi.mdx | 2 +- .../sdks/generators/python/quickstart.mdx | 2 +- .../ruby/publishing-to-rubygems.mdx | 2 +- .../sdks/generators/ruby/quickstart.mdx | 2 +- .../rust/publishing-to-crates-io.mdx | 2 +- .../typescript/publishing-to-npm.mdx | 2 +- .../sdks/generators/typescript/quickstart.mdx | 2 +- fern/products/sdks/replay-migration.mdx | 4 +- 47 files changed, 532 insertions(+), 516 deletions(-) create mode 100644 fern/products/cli-api-reference/pages/docs-commands.mdx rename fern/products/cli-api-reference/pages/{commands.mdx => sdk-commands.mdx} (70%) diff --git a/fern/docs.yml b/fern/docs.yml index c70a97ca8a..68ff603aad 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -751,6 +751,8 @@ redirects: destination: /learn/cli-api-reference/cli-reference/:slug* - source: /learn/api/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview + - source: /learn/cli-api-reference/cli-reference/commands + destination: /learn/cli-api-reference/cli-reference/sdk-commands # /learn/cli-reference/* (legacy) - source: /learn/cli-reference/cli-overview @@ -760,7 +762,7 @@ redirects: - source: /learn/cli-reference/get-started destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-reference/commands - destination: /learn/cli-api-reference/cli-reference/commands + destination: /learn/cli-api-reference/cli-reference/sdk-commands - source: /learn/cli-reference/options destination: /learn/cli-api-reference/cli-reference/options - source: /learn/cli-reference/changelog/:slug* diff --git a/fern/products/api-def/ferndef/export-openapi.mdx b/fern/products/api-def/ferndef/export-openapi.mdx index 52b3698989..53393f8c46 100644 --- a/fern/products/api-def/ferndef/export-openapi.mdx +++ b/fern/products/api-def/ferndef/export-openapi.mdx @@ -7,7 +7,7 @@ noindex: true -To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/learn/cli-api-reference/cli-reference/commands#fern-export). +To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/learn/cli-api-reference/cli-reference/sdk-commands#fern-export). The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec. diff --git a/fern/products/api-def/openapi/automation.mdx b/fern/products/api-def/openapi/automation.mdx index 12baeaf86f..905f8500ca 100644 --- a/fern/products/api-def/openapi/automation.mdx +++ b/fern/products/api-def/openapi/automation.mdx @@ -20,7 +20,7 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y ``` - Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. + Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. ```yml title=".github/workflows/sync-openapi.yml" name: Sync OpenAPI Specs # can be customized diff --git a/fern/products/api-def/openapi/extensions/examples.mdx b/fern/products/api-def/openapi/extensions/examples.mdx index b91794d77d..c7830883e0 100644 --- a/fern/products/api-def/openapi/extensions/examples.mdx +++ b/fern/products/api-def/openapi/extensions/examples.mdx @@ -116,4 +116,4 @@ paths: ## Convert to native OpenAPI examples -To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/commands#fern-api-enrich) to convert them into native OpenAPI example fields. +To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-enrich) to convert them into native OpenAPI example fields. diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx index c42e98ffb9..7f02998e61 100644 --- a/fern/products/api-def/pages/overrides.mdx +++ b/fern/products/api-def/pages/overrides.mdx @@ -22,7 +22,7 @@ Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications. -[Create an `overrides.yml` file](/learn/cli-api-reference/cli-reference/commands#fern-write-overrides) in the folder that contains your API definition: +[Create an `overrides.yml` file](/learn/cli-api-reference/cli-reference/sdk-commands#fern-write-overrides) in the folder that contains your API definition: ```bash {6} fern/ diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 59bf19e4b2..7e802e08aa 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -65,7 +65,7 @@ For [OpenAPI](/learn/api-definitions/openapi/overview), [AsyncAPI](/learn/api-de There are four common ways to manage your API definition: - **Commit directly into your Fern repository (recommended).** Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don't maintain the definition elsewhere. -- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). +- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). - **Host at a public URL.** Serve the definition from a publicly accessible endpoint and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference. - **Reference from a remote git repository.** Point [`openapi`](/learn/sdks/reference/generators-yml#openapi), [`asyncapi`](/learn/sdks/reference/generators-yml#asyncapi), or proto [`root`](/learn/sdks/reference/generators-yml#root) to a file in an external git repository using the `git` sub-object. The CLI shallow-clones the repository at generation time, using your local git credential configuration. This is useful when spec files live in a private repo you don't want to copy. diff --git a/fern/products/cli-api-reference/cli-api-reference.yml b/fern/products/cli-api-reference/cli-api-reference.yml index 331957b256..b9c9ef8321 100644 --- a/fern/products/cli-api-reference/cli-api-reference.yml +++ b/fern/products/cli-api-reference/cli-api-reference.yml @@ -7,8 +7,12 @@ navigation: - page: Global options path: ./pages/global-options.mdx slug: options - - page: Commands - path: ./pages/commands.mdx + - page: Docs Commands + path: ./pages/docs-commands.mdx + slug: docs-commands + - page: SDK Commands + path: ./pages/sdk-commands.mdx + slug: sdk-commands - page: CLI version policy path: ./pages/cli-version-policy.mdx slug: version-policy diff --git a/fern/products/cli-api-reference/pages/cli-get-started.mdx b/fern/products/cli-api-reference/pages/cli-get-started.mdx index 3b846034d8..04c31072a9 100644 --- a/fern/products/cli-api-reference/pages/cli-get-started.mdx +++ b/fern/products/cli-api-reference/pages/cli-get-started.mdx @@ -83,7 +83,7 @@ npm fern generate The Fern CLI manages both documentation and SDK workflows. Below is a brief overview of the common commands for each. All commands support [global options](/learn/cli-api-reference/cli-reference/options) like `--log-level` for debugging. -For complete CLI documentation, see the [command reference](/learn/cli-api-reference/cli-reference/commands). +For complete CLI documentation, see the [command reference](/learn/cli-api-reference/cli-reference/sdk-commands). diff --git a/fern/products/cli-api-reference/pages/cli-version-policy.mdx b/fern/products/cli-api-reference/pages/cli-version-policy.mdx index b7082ca40f..2c8dad6bf5 100644 --- a/fern/products/cli-api-reference/pages/cli-version-policy.mdx +++ b/fern/products/cli-api-reference/pages/cli-version-policy.mdx @@ -42,7 +42,7 @@ A policy never blocks a command. When the CLI can't read your organization's bou ## Set the policy -[`fern org set cli-version`](/learn/cli-api-reference/cli-reference/commands#fern-org-set-cli-version) writes the bounds. It requires an organization admin and an authenticated session from [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login). The organization is read from `fern.config.json`; pass `--org` to target a different one. +[`fern org set cli-version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-set-cli-version) writes the bounds. It requires an organization admin and an authenticated session from [`fern login`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-login). The organization is read from `fern.config.json`; pass `--org` to target a different one. ```bash # Pin an exact version @@ -69,11 +69,11 @@ fern org get fern org get --json ``` -[`fern org get`](/learn/cli-api-reference/cli-reference/commands#fern-org-get) prints the policy in one line — `Fern CLI must be between 5.40.0 and 5.50.0`, or the equivalent for a minimum, maximum, or exact pin — and reports when no policy is set. `--json` returns the raw `cliVersionMin` and `cliVersionMax` fields instead. +[`fern org get`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-get) prints the policy in one line — `Fern CLI must be between 5.40.0 and 5.50.0`, or the equivalent for a minimum, maximum, or exact pin — and reports when no policy is set. `--json` returns the raw `cliVersionMin` and `cliVersionMax` fields instead. ## Clear the policy -[`fern org unset cli-version`](/learn/cli-api-reference/cli-reference/commands#fern-org-unset-cli-version) clears the bounds, and like setting them it requires an organization admin. +[`fern org unset cli-version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-unset-cli-version) clears the bounds, and like setting them it requires an organization admin. ```bash # Remove both bounds @@ -88,7 +88,7 @@ fern org unset cli-version --max ## Interaction with `fern upgrade` -A policy changes the version that runs, not the version on disk, so a project stays out of range until it's upgraded. [`fern upgrade`](/learn/cli-api-reference/cli-reference/commands#fern-upgrade) brings the file itself into range: it applies the bounds to the upgrade target before writing it. +A policy changes the version that runs, not the version on disk, so a project stays out of range until it's upgraded. [`fern upgrade`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-upgrade) brings the file itself into range: it applies the bounds to the upgrade target before writing it. | Command | Policy | Version written | |---|---|---| @@ -96,8 +96,8 @@ A policy changes the version that runs, not the version on disk, so a project st | `fern upgrade` | Pinned to `5.45.0` | `5.45.0` | | `fern upgrade --version 5.35.0` | Minimum `5.40.0` | `5.40.0` | -A plain `fern upgrade` resolves to the latest release, which is never below the minimum, so only the maximum changes what it writes. The minimum applies when you request an older version with [`--version`](/learn/cli-api-reference/cli-reference/commands#fern-upgrade): the bounds win over the version you asked for. +A plain `fern upgrade` resolves to the latest release, which is never below the minimum, so only the maximum changes what it writes. The minimum applies when you request an older version with [`--version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-upgrade): the bounds win over the version you asked for. -[`fern downgrade`](/learn/cli-api-reference/cli-reference/commands#fern-downgrade) is the exception: it writes whatever version you pass, including one below the minimum. The policy then overrides that pin the same way it overrides any other out-of-range pin, so the project's commands keep running the minimum. +[`fern downgrade`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-downgrade) is the exception: it writes whatever version you pass, including one below the minimum. The policy then overrides that pin the same way it overrides any other out-of-range pin, so the project's commands keep running the minimum. Running a newer CLI doesn't apply the migrations that `fern upgrade` performs. Raising the minimum across a major version therefore still requires each project to run `fern upgrade`. diff --git a/fern/products/cli-api-reference/pages/docs-commands.mdx b/fern/products/cli-api-reference/pages/docs-commands.mdx new file mode 100644 index 0000000000..8d7a9a7ff9 --- /dev/null +++ b/fern/products/cli-api-reference/pages/docs-commands.mdx @@ -0,0 +1,390 @@ +--- +title: 'Docs Commands' +description: 'Complete reference for all Fern CLI commands for generating and managing documentation.' +subtitle: 'Learn about the Fern CLI docs commands.' +hideOnThisPage: true +--- + +## Documentation commands + +| Command | Description | +|---------|-------------| +| [`fern docs dev`](#fern-docs-dev) | Run local documentation preview server | +| [`fern docs diff`](#fern-docs-diff) Beta | Generate visual diffs between preview and production docs | +| [`fern generate --docs`](#fern-generate---docs) | Build & publish documentation updates | +| [`fern docs preview list`](#fern-docs-preview-list) | List all preview deployments | +| [`fern docs preview delete`](#fern-docs-preview-delete) | Delete a preview deployment | +| [`fern docs md check`](#fern-docs-md-check) | Validate MDX syntax in documentation files | +| [`fern docs md generate`](#fern-docs-md-generate) | Generate MDX pages from library source code | +| [`fern docs theme export`](#fern-docs-theme-export) | Export theme-eligible fields from `docs.yml` into a standalone directory | +| [`fern docs theme upload`](#fern-docs-theme-upload) | Upload a theme to Fern's registry | +| [`fern docs link check`](#fern-docs-link-check) | Check for broken links on a live documentation site | +| [`fern docs theme list`](#fern-docs-theme-list) | List all themes for your organization | + +## Detailed command documentation + + + + + Use `fern generate --docs` to create a documentation site for your API. + + + ```bash + fern generate --docs [--instance ] [--preview] [--id ] [--force] + ``` + + + ### instance + + Use `--instance` to specify which instance URL in your `docs.yml` to generate documentation for. + + ```bash + fern generate --docs --instance your-organization.docs.buildwithfern.com + ``` + + ### preview + + Use `--preview` to preview updates to your documentation before publishing changes to your production site. + + ```bash + fern generate --docs --preview + ``` + + ### id + + Use `--id` with `--preview` to create a stable, named preview link. The preview URL follows the format `{org}-preview-{id}.docs.buildwithfern.com`, so rerunning with the same `--id` updates the existing preview in place rather than creating a new one. + + ```bash + fern generate --docs --preview --id my-feature + # -> https://your-org-preview-my-feature.docs.buildwithfern.com + ``` + + This is useful in CI workflows where you want one preview URL per pull request. See [Preview changes](/learn/docs/preview-publish/preview-changes#preview-links) for details. + + ### force + + When reusing an `--id` that already exists, Fern prompts you to confirm the overwrite. Use `--force` to skip the confirmation. This is detected automatically in GitHub Actions, but is needed for other CI environments like Azure Pipelines. + + ```bash + fern generate --docs --preview --id my-feature --force + ``` + + + + + + Use `fern docs dev` to run a local development server to preview your docs. + + + ```bash + fern docs dev [--port ] + ``` + + + + On Windows, `fern docs dev` requires [long path support](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later) to be enabled. + + To enable long path support, run the following command in an elevated PowerShell prompt, then restart your terminal: + + ```powershell + New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force + ``` + + If you can't enable long path support, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) to run `fern docs dev` in a Linux environment instead. + + + ### port + + Use `--port ` to specify the port the docs preview will be run on. + + ```bash + fern docs dev --port 57908 + ``` + + + + + Beta + + Use `fern docs diff` to generate visual diffs between your preview deployment and production docs. This command is intended for use in [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml). It captures screenshots of both versions and creates side-by-side comparison images. + + + ```bash + fern docs diff [--output ] + ``` + + + Pass the preview URL from `fern generate --docs --preview` and one or more MDX file paths. Diff images are saved to `.fern/diff` by default. + + ```bash + fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx fern/pages/quickstart.mdx + ``` + + ### output + + Use `--output` to specify a custom directory for diff images. + + ```bash + fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx --output ./my-diffs + ``` + + + + + + Use `fern docs preview list` to list all [preview deployments](/learn/docs/preview-publish/preview-changes#manage-preview-links) for your organization. + + + ```bash + fern docs preview list [--limit ] [--page ] + ``` + + + ### limit + + Use `--limit` to specify the number of preview deployments to display per page. + + ```bash + fern docs preview list --limit 20 + ``` + + ### page + + Use `--page` to specify which page of results to display. + + ```bash + fern docs preview list --page 2 + ``` + + + + + + Use `fern docs preview delete` to delete a [preview deployment](/learn/docs/preview-publish/preview-changes#manage-preview-links) generated with `fern generate --docs --preview`. Pass the full preview URL, or use `--id` to delete by the identifier used during generation. + + + ```bash + fern docs preview delete + + # Or delete by preview ID + fern docs preview delete --id + ``` + + + ### id + + Use `--id` to delete a preview deployment by the identifier used during generation instead of the full preview URL. + + ```bash + fern docs preview delete --id + ``` + + + + + + Use `fern docs md check` to validate MDX syntax across all documentation pages referenced in your navigation configuration, including `docs.yml`, versioned configuration files, and product-specific YAML files. + + + ```bash + fern docs md check + ``` + + + The command parses each MDX file and reports syntax errors with file paths and line:column numbers. The command accounts for frontmatter offsets, so reported line numbers correspond to the actual lines in your file. + + ```plaintext + fern/pages/quickstart.mdx:12:5 + Unexpected closing tag, expected corresponding closing tag for `` + + fern/pages/guide.mdx:45:1 + Expected a closing tag for `` before the end of `paragraph` + ``` + + When all files are valid, you'll see a success message: + + ```plaintext + ✓ All 42 MDX files are valid + ``` + + + + + + Use `fern docs md generate` to generate [MDX documentation pages from your library source code](/learn/docs/api-references/library-reference). The command reads `libraries` entries in `docs.yml` and produces pages for modules, classes, functions, and types. + + + ```bash + fern docs md generate [--local] [--library ] + ``` + + + For `git` inputs, the command sends the repository URL to Fern's servers for parsing. For `path` inputs, pass `--local` to parse the source on your machine instead. + + ### local + + Use `--local` to parse library source locally rather than on Fern's servers. Required when the library uses a `path` input. Local generation does not require authentication. + + ```bash + fern docs md generate --local + ``` + + ### library + + Use `--library` to generate docs for a single library when multiple libraries are configured. + + ```bash + fern docs md generate --library plant-sdk + ``` + + When `--library` is omitted, all configured libraries are processed in parallel. + + + + + + Use `fern docs theme export` to extract the [theme-eligible fields](/learn/docs/customization/global-themes) from your `docs.yml` into a standalone directory. The exported `theme.yml` and its assets can then be uploaded with `fern docs theme upload`. + + + ```bash + fern docs theme export [--output ] + ``` + + + By default, files are written to `./fern/theme/`. + + ### output + + Use `--output` to specify a custom directory for the exported theme. + + ```bash + fern docs theme export --output ./my-theme + ``` + + + + + + Use `fern docs theme upload` to upload a [theme](/learn/docs/customization/global-themes) to Fern's registry. The command reads `theme.yml` from `./fern/theme/` and uploads it along with any referenced file assets. + + + ```bash + fern docs theme upload [--name ] [--org ] + ``` + + + ### name + + Use `--name` to set the theme name. Defaults to `default`. + + ```bash + fern docs theme upload --name my-theme + ``` + + ### org + + Use `--org` to override the organization ID from `fern.config.json`. + + ```bash + fern docs theme upload --org my-org + ``` + + + + + + Use `fern docs link check` to scan a live documentation site for broken links. The command crawls the published site, checks every link, and reports broken (404) and blocked (403) URLs along with their source pages. + + + ```bash + fern docs link check [--url ] [--output ] + ``` + + + + Unlike the [`broken-links` rule](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site. + + + By default, the command auto-detects your docs URL from the `instances` in `docs.yml`. When all links are valid, the command exits with a success message. + + The command first scrapes every page on the site, then checks each link it finds. When broken links are found, the output includes a summary and a grouped list of broken URLs with status codes and source file paths. + + ```plaintext + ◆ Checking links on your-org.docs.buildwithfern.com... + + Scraping pages [████████████████████] 100% | 42/42 + Checking links [████████████████████] 100% | 240/240 + + Finished in 2 minutes, 23 seconds + + Summary + Pages scanned 42 + Links checked 240 + ✓ Working 228 + ✗ Broken 8 (external) + ⚠ Blocked 4 + + ───────────────────────────────────── + + External Broken Links (8) + + ✗ https://example.com/removed-page → 404 + fern/pages/quickstart.mdx + fern/pages/overview.mdx + + ✗ https://example.com/old-endpoint → 404 + fern/pages/integrations.mdx + ``` + + ### url + + Use `--url` to specify which docs site to check. This is useful when you have multiple instances or want to check a preview deployment. + + ```bash + fern docs link check --url https://your-org.docs.buildwithfern.com + ``` + + ### output + + Use `--output` to control the output format. Supported values are `text` (default), `json`, and `csv`. + + ```bash + # JSON output for programmatic use + fern docs link check --output json + + # CSV output for spreadsheets or reporting + fern docs link check --output csv + ``` + + + + + + Use `fern docs theme list` to list all [themes](/learn/docs/customization/global-themes) uploaded for your organization. + + + ```bash + fern docs theme list [--json] [--org ] + ``` + + + By default, outputs one theme name per line. + + ### json + + Use `--json` to output the full list as a JSON array, including `updatedAt` timestamps. + + ```bash + fern docs theme list --json + ``` + + ### org + + Use `--org` to override the organization ID from `fern.config.json`. + + ```bash + fern docs theme list --org my-org + ``` + + + diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/sdk-commands.mdx similarity index 70% rename from fern/products/cli-api-reference/pages/commands.mdx rename to fern/products/cli-api-reference/pages/sdk-commands.mdx index cf5943698d..5309be6e72 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/sdk-commands.mdx @@ -1,11 +1,10 @@ --- -title: 'Commands' -description: 'Complete reference for all Fern CLI commands for generating SDKs and developer documentation.' -subtitle: 'Learn about the Fern CLI commands.' +title: 'SDK Commands' +description: 'Complete reference for all Fern CLI commands for generating SDKs.' +subtitle: 'Learn about the Fern CLI SDK commands.' hideOnThisPage: true --- - | Command | Description | |---------|-------------| | [`fern init`](#fern-init) | Create new Fern project from OpenAPI spec or scratch | @@ -21,22 +20,6 @@ hideOnThisPage: true | [`fern org set cli-version`](#fern-org-set-cli-version) | Set a minimum, maximum, or exact CLI version for your organization | | [`fern org unset cli-version`](#fern-org-unset-cli-version) | Clear your organization's CLI version policy | -## Documentation commands - -| Command | Description | -|---------|-------------| -| [`fern docs dev`](#fern-docs-dev) | Run local documentation preview server | -| [`fern docs diff`](#fern-docs-diff) Beta | Generate visual diffs between preview and production docs | -| [`fern generate --docs`](#fern-generate---docs) | Build & publish documentation updates | -| [`fern docs preview list`](#fern-docs-preview-list) | List all preview deployments | -| [`fern docs preview delete`](#fern-docs-preview-delete) | Delete a preview deployment | -| [`fern docs md check`](#fern-docs-md-check) | Validate MDX syntax in documentation files | -| [`fern docs md generate`](#fern-docs-md-generate) | Generate MDX pages from library source code | -| [`fern docs theme export`](#fern-docs-theme-export) | Export theme-eligible fields from `docs.yml` into a standalone directory | -| [`fern docs theme upload`](#fern-docs-theme-upload) | Upload a theme to Fern's registry | -| [`fern docs link check`](#fern-docs-link-check) | Check for broken links on a live documentation site | -| [`fern docs theme list`](#fern-docs-theme-list) | List all themes for your organization | - ## SDK generation commands | Command | Description | @@ -105,7 +88,7 @@ hideOnThisPage: true background: '#000000' ``` - To publish the API docs, run [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs). + To publish the API docs, run [`fern generate --docs`](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs). ### mintlify @@ -394,7 +377,7 @@ hideOnThisPage: true ``` - To check links on a published site, use [`fern docs link check`](#fern-docs-link-check) or the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. ### api @@ -444,344 +427,177 @@ hideOnThisPage: true - - Use `fern generate --docs` to create a documentation site for your API. + + + Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the + latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions. ```bash - fern generate --docs [--instance ] [--preview] [--id ] [--force] + fern upgrade [--version ] [--from ] [--yes] ``` - ### instance - - Use `--instance` to specify which instance URL in your `docs.yml` to generate documentation for. - - ```bash - fern generate --docs --instance your-organization.docs.buildwithfern.com - ``` + When your organization sets a [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy#interaction-with-fern-upgrade), `fern upgrade` writes the highest version the policy allows rather than the latest published version. A `--version` below the organization's minimum is raised to the minimum. - ### preview + ### version - Use `--preview` to preview updates to your documentation before publishing changes to your production site. + Use `--version` to upgrade to a specific published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions) instead of the latest release. The version must be ahead of the version in `fern.config.json`; use [`fern downgrade`](#fern-downgrade) to move to an older version. ```bash - fern generate --docs --preview + fern upgrade --version 5.45.0 ``` - ### id + ### from - Use `--id` with `--preview` to create a stable, named preview link. The preview URL follows the format `{org}-preview-{id}.docs.buildwithfern.com`, so rerunning with the same `--id` updates the existing preview in place rather than creating a new one. + Use `--from` to set the version that migrations run from. Fern infers this from `fern.config.json` and git history; pass it when that inference is wrong, such as after `fern.config.json` was edited by hand. ```bash - fern generate --docs --preview --id my-feature - # -> https://your-org-preview-my-feature.docs.buildwithfern.com + fern upgrade --from 4.20.0 ``` - This is useful in CI workflows where you want one preview URL per pull request. See [Preview changes](/learn/docs/preview-publish/preview-changes#preview-links) for details. - - ### force + ### yes - When reusing an `--id` that already exists, Fern prompts you to confirm the overwrite. Use `--force` to skip the confirmation. This is detected automatically in GitHub Actions, but is needed for other CI environments like Azure Pipelines. + Use `--yes` (`-y`) to answer yes to every migration prompt, for non-interactive environments like CI. ```bash - fern generate --docs --preview --id my-feature --force + fern upgrade --yes ``` - + - Use `fern docs preview list` to list all [preview deployments](/learn/docs/preview-publish/preview-changes#manage-preview-links) for your organization. + Use `fern downgrade` to set the CLI version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to an older version. It rewrites the `version` field only: generator versions in `generators.yml` are left alone, and no migrations are reversed. ```bash - fern docs preview list [--limit ] [--page ] + fern downgrade ``` - ### limit - - Use `--limit` to specify the number of preview deployments to display per page. - - ```bash - fern docs preview list --limit 20 - ``` - - ### page - - Use `--page` to specify which page of results to display. - - ```bash - fern docs preview list --page 2 - ``` - - - - - - Use `fern docs preview delete` to delete a [preview deployment](/learn/docs/preview-publish/preview-changes#manage-preview-links) generated with `fern generate --docs --preview`. Pass the full preview URL, or use `--id` to delete by the identifier used during generation. - - ```bash - fern docs preview delete - - # Or delete by preview ID - fern docs preview delete --id + fern downgrade 5.40.0 ``` - - ### id - - Use `--id` to delete a preview deployment by the identifier used during generation instead of the full preview URL. - - ```bash - fern docs preview delete --id - ``` + A [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy) doesn't block the downgrade, but it does override it: the new version is written to `fern.config.json`, and subsequent commands still run the minimum required by your organization. - + - Use `fern docs dev` to run a local development server to preview your docs. + Use `fern login` to login to the Fern CLI via GitHub or Google. Logging in allows you + join GitHub organizations, gain permissions, and contribute to projects. ```bash - fern docs dev [--port ] + fern login + fern login --device-code + fern login --email ``` - - On Windows, `fern docs dev` requires [long path support](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later) to be enabled. - - To enable long path support, run the following command in an elevated PowerShell prompt, then restart your terminal: - - ```powershell - New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force - ``` - - If you can't enable long path support, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) to run `fern docs dev` in a Linux environment instead. - - - ### port - - Use `--port ` to specify the port the docs preview will be run on. - - ```bash - fern docs dev --port 57908 - ``` - - + By default, `fern login` opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available: - + ### device-code - Use `fern docs link check` to scan a live documentation site for broken links. The command crawls the published site, checks every link, and reports broken (404) and blocked (403) URLs along with their source pages. + Use `--device-code` to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers). - ```bash - fern docs link check [--url ] [--output ] - ``` - - - - Unlike the [`broken-links` rule](#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site. - - - By default, the command auto-detects your docs URL from the `instances` in `docs.yml`. When all links are valid, the command exits with a success message. - - The command first scrapes every page on the site, then checks each link it finds. When broken links are found, the output includes a summary and a grouped list of broken URLs with status codes and source file paths. - - ```plaintext - ◆ Checking links on your-org.docs.buildwithfern.com... - - Scraping pages [████████████████████] 100% | 42/42 - Checking links [████████████████████] 100% | 240/240 - - Finished in 2 minutes, 23 seconds - - Summary - Pages scanned 42 - Links checked 240 - ✓ Working 228 - ✗ Broken 8 (external) - ⚠ Blocked 4 - - ───────────────────────────────────── - - External Broken Links (8) - - ✗ https://example.com/removed-page → 404 - fern/pages/quickstart.mdx - fern/pages/overview.mdx - - ✗ https://example.com/old-endpoint → 404 - fern/pages/integrations.mdx + fern login --device-code ``` - ### url + ### email - Use `--url` to specify which docs site to check. This is useful when you have multiple instances or want to check a preview deployment. + Use `--email` to login via enterprise SSO. Pass the email address associated with your organization's SSO provider. ```bash - fern docs link check --url https://your-org.docs.buildwithfern.com + fern login --email user@example.com ``` - ### output - - Use `--output` to control the output format. Supported values are `text` (default), `json`, and `csv`. - - ```bash - # JSON output for programmatic use - fern docs link check --output json - - # CSV output for spreadsheets or reporting - fern docs link check --output csv - ``` + + To enable CI/CD, use [`fern token`](#fern-token). + - + - Use `fern docs md check` to validate MDX syntax across all documentation pages referenced in your navigation configuration, including `docs.yml`, versioned configuration files, and product-specific YAML files. + Use `fern logout` to log out of the Fern CLI. This will clear your authentication + credentials and revoke access to your GitHub organizations and permissions. ```bash - fern docs md check + fern logout ``` - The command parses each MDX file and reports syntax errors with file paths and line:column numbers. The command accounts for frontmatter offsets, so reported line numbers correspond to the actual lines in your file. - - ```plaintext - fern/pages/quickstart.mdx:12:5 - Unexpected closing tag, expected corresponding closing tag for `` - - fern/pages/guide.mdx:45:1 - Expected a closing tag for `` before the end of `paragraph` - ``` - - When all files are valid, you'll see a success message: - - ```plaintext - ✓ All 42 MDX files are valid - ``` + After logging out, you'll need to run [`fern login`](#fern-login) again to access protected features. - - - Use `fern docs md generate` to generate [MDX documentation pages from your library source code](/learn/docs/api-references/library-reference). The command reads `libraries` entries in `docs.yml` and produces pages for modules, classes, functions, and types. - - - ```bash - fern docs md generate [--local] [--library ] - ``` - - - For `git` inputs, the command sends the repository URL to Fern's servers for parsing. For `path` inputs, pass `--local` to parse the source on your machine instead. - - ### local - - Use `--local` to parse library source locally rather than on Fern's servers. Required when the library uses a `path` input. Local generation does not require authentication. - - ```bash - fern docs md generate --local - ``` - - ### library - - Use `--library` to generate docs for a single library when multiple libraries are configured. + - ```bash - fern docs md generate --library plant-sdk - ``` + - When `--library` is omitted, all configured libraries are processed in parallel. + See [Publishing your docs](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions) for instructions on using this API key in automated publishing workflows. - - Beta - - Use `fern docs diff` to generate visual diffs between your preview deployment and production docs. This command is intended for use in [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml). It captures screenshots of both versions and creates side-by-side comparison images. - - - ```bash - fern docs diff [--output ] - ``` - - - Pass the preview URL from `fern generate --docs --preview` and one or more MDX file paths. Diff images are saved to `.fern/diff` by default. + + Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and + updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). + ```bash - fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx fern/pages/quickstart.mdx + fern api update [--api ] ``` + - ### output + ### api - Use `--output` to specify a custom directory for diff images. + Use `--api` to specify the API to update if there are multiple specs with a defined `origin` in `generators.yml`. If you don't specify an API, all OpenAPI specs with an `origin` will be updated. + ```bash - fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx --output ./my-diffs + fern api update --api public-api ``` - + - + - Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the - latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions. + Use `fern api enrich` to convert [AI-generated examples](/learn/docs/ai-features/ai-examples) or manually authored [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) into portable OpenAPI examples that any OpenAPI-compatible tool can consume. ```bash - fern upgrade [--version ] [--from ] [--yes] + fern api enrich -f -o ``` - When your organization sets a [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy#interaction-with-fern-upgrade), `fern upgrade` writes the highest version the policy allows rather than the latest published version. A `--version` below the organization's minimum is raised to the minimum. - - ### version - - Use `--version` to upgrade to a specific published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions) instead of the latest release. The version must be ahead of the version in `fern.config.json`; use [`fern downgrade`](#fern-downgrade) to move to an older version. - - ```bash - fern upgrade --version 5.45.0 - ``` - - ### from - - Use `--from` to set the version that migrations run from. Fern infers this from `fern.config.json` and git history; pass it when that inference is wrong, such as after `fern.config.json` was edited by hand. - - ```bash - fern upgrade --from 4.20.0 - ``` + The command merges examples from an overrides file into native OpenAPI `example` fields and strips the `x-fern-examples` keys from the output. When an endpoint has multiple examples, each is stored as a named entry under the plural `examples` field. - ### yes + The command requires two flags: - Use `--yes` (`-y`) to answer yes to every migration prompt, for non-interactive environments like CI. + - `-f` (or `--file`) — the overrides file containing `x-fern-examples` (e.g., `ai_examples_override.yml`). + - `-o` (or `--output`) — the path for the enriched output file. Supports `.yml` and `.json` extensions. ```bash - fern upgrade --yes - ``` - - - - - - Use `fern downgrade` to set the CLI version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to an older version. It rewrites the `version` field only: generator versions in `generators.yml` are left alone, and no migrations are reversed. + # Output as YAML + fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml - - ```bash - fern downgrade + # Output as JSON + fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.json ``` - - ```bash - fern downgrade 5.40.0 - ``` + Each `x-fern-examples` field is mapped to its standard OpenAPI location: - A [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy) doesn't block the downgrade, but it does override it: the new version is written to `fern.config.json`, and subsequent commands still run the minimum required by your organization. + - `path-parameters` → `parameters[].example` (where `in: path`) + - `query-parameters` → `parameters[].example` (where `in: query`) + - `headers` → `parameters[].example` (where `in: header`) + - `request` → `requestBody.content.*.example` + - `response.body` → `responses..content.*.example` @@ -863,66 +679,6 @@ hideOnThisPage: true - - - Use `fern login` to login to the Fern CLI via GitHub or Google. Logging in allows you - join GitHub organizations, gain permissions, and contribute to projects. - - - ```bash - fern login - fern login --device-code - fern login --email - ``` - - - By default, `fern login` opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available: - - ### device-code - - Use `--device-code` to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers). - - ```bash - fern login --device-code - ``` - - ### email - - Use `--email` to login via enterprise SSO. Pass the email address associated with your organization's SSO provider. - - ```bash - fern login --email user@example.com - ``` - - - To enable CI/CD, use [`fern token`](/learn/cli-api/cli-reference/commands#fern-token). - - - - - - - Use `fern logout` to log out of the Fern CLI. This will clear your authentication - credentials and revoke access to your GitHub organizations and permissions. - - - ```bash - fern logout - ``` - - - After logging out, you'll need to run [`fern login`](#fern-login) again to access protected features. - - - - - - - - See [Publishing your docs](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions) for instructions on using this API key in automated publishing workflows. - - - Use `fern write-overrides` to generate a basic OpenAPI overrides file. An overrides file allows for @@ -1105,140 +861,4 @@ hideOnThisPage: true ``` - - - Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and - updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). - - - ```bash - fern api update [--api ] - ``` - - - ### api - - Use `--api` to specify the API to update if there are multiple specs with a defined `origin` in `generators.yml`. If you don't specify an API, all OpenAPI specs with an `origin` will be updated. - - - ```bash - fern api update --api public-api - ``` - - - - - - Use `fern api enrich` to convert [AI-generated examples](/learn/docs/ai-features/ai-examples) or manually authored [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) into portable OpenAPI examples that any OpenAPI-compatible tool can consume. - - - ```bash - fern api enrich -f -o - ``` - - - The command merges examples from an overrides file into native OpenAPI `example` fields and strips the `x-fern-examples` keys from the output. When an endpoint has multiple examples, each is stored as a named entry under the plural `examples` field. - - The command requires two flags: - - - `-f` (or `--file`) — the overrides file containing `x-fern-examples` (e.g., `ai_examples_override.yml`). - - `-o` (or `--output`) — the path for the enriched output file. Supports `.yml` and `.json` extensions. - - ```bash - # Output as YAML - fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml - - # Output as JSON - fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.json - ``` - - Each `x-fern-examples` field is mapped to its standard OpenAPI location: - - - `path-parameters` → `parameters[].example` (where `in: path`) - - `query-parameters` → `parameters[].example` (where `in: query`) - - `headers` → `parameters[].example` (where `in: header`) - - `request` → `requestBody.content.*.example` - - `response.body` → `responses..content.*.example` - - - - - - Use `fern docs theme export` to extract the [theme-eligible fields](/learn/docs/customization/global-themes) from your `docs.yml` into a standalone directory. The exported `theme.yml` and its assets can then be uploaded with `fern docs theme upload`. - - - ```bash - fern docs theme export [--output ] - ``` - - - By default, files are written to `./fern/theme/`. - - ### output - - Use `--output` to specify a custom directory for the exported theme. - - ```bash - fern docs theme export --output ./my-theme - ``` - - - - - - Use `fern docs theme upload` to upload a [theme](/learn/docs/customization/global-themes) to Fern's registry. The command reads `theme.yml` from `./fern/theme/` and uploads it along with any referenced file assets. - - - ```bash - fern docs theme upload [--name ] [--org ] - ``` - - - ### name - - Use `--name` to set the theme name. Defaults to `default`. - - ```bash - fern docs theme upload --name my-theme - ``` - - ### org - - Use `--org` to override the organization ID from `fern.config.json`. - - ```bash - fern docs theme upload --org my-org - ``` - - - - - - Use `fern docs theme list` to list all [themes](/learn/docs/customization/global-themes) uploaded for your organization. - - - ```bash - fern docs theme list [--json] [--org ] - ``` - - - By default, outputs one theme name per line. - - ### json - - Use `--json` to output the full list as a JSON array, including `updatedAt` timestamps. - - ```bash - fern docs theme list --json - ``` - - ### org - - Use `--org` to override the organization ID from `fern.config.json`. - - ```bash - fern docs theme list --org my-org - ``` - - diff --git a/fern/products/docs/pages/ai/agent-setup.mdx b/fern/products/docs/pages/ai/agent-setup.mdx index 93f7b09c07..b81e21aa62 100644 --- a/fern/products/docs/pages/ai/agent-setup.mdx +++ b/fern/products/docs/pages/ai/agent-setup.mdx @@ -52,7 +52,7 @@ fern login npx skills add fern-api/skills --skill fern-docs -a github-copilot ``` -[`fern mcp install`](/learn/cli-api-reference/cli-reference/commands) supports Claude Code, Cursor, and Codex only, so register both servers in `.vscode/mcp.json` and complete the browser login that the organization server prompts for on first use: +[`fern mcp install`](/learn/cli-api-reference/cli-reference/sdk-commands) supports Claude Code, Cursor, and Codex only, so register both servers in `.vscode/mcp.json` and complete the browser login that the organization server prompts for on first use: ```json { diff --git a/fern/products/docs/pages/ai/ai-examples.mdx b/fern/products/docs/pages/ai/ai-examples.mdx index a1f878f98c..36b9b3d530 100644 --- a/fern/products/docs/pages/ai/ai-examples.mdx +++ b/fern/products/docs/pages/ai/ai-examples.mdx @@ -44,7 +44,7 @@ AI-generated examples are written to `ai_examples_override.yml`. Edit this file ``` -To make AI-generated examples portable to non-Fern OpenAPI tools, use [`fern api enrich`](/learn/cli-api-reference/cli-reference/commands#fern-api-enrich) to merge them into native OpenAPI example fields. +To make AI-generated examples portable to non-Fern OpenAPI tools, use [`fern api enrich`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-enrich) to merge them into native OpenAPI example fields. ## Disable AI-generated examples diff --git a/fern/products/docs/pages/ai/markdown.mdx b/fern/products/docs/pages/ai/markdown.mdx index 26ae1601c6..b22cbbe1f1 100644 --- a/fern/products/docs/pages/ai/markdown.mdx +++ b/fern/products/docs/pages/ai/markdown.mdx @@ -63,7 +63,7 @@ When an agent requests a `.md` URL that matches no page and no redirect, the res ## Accessing protected docs -On sites with [authentication](/learn/docs/authentication/overview) enabled, agents must include a JWT on every Markdown request — whether for an individual page or `llms.txt`. Exchange your [Fern API key](/learn/cli-api/cli-reference/commands#fern-token) for a [JWT](/learn/docs/fern-api-reference/get-jwt): +On sites with [authentication](/learn/docs/authentication/overview) enabled, agents must include a JWT on every Markdown request — whether for an individual page or `llms.txt`. Exchange your [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) for a [JWT](/learn/docs/fern-api-reference/get-jwt): ```bash Get a JWT curl https://docs.example.com/api/fern-docs/get-jwt \ diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 2e63731293..8f38705ba3 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -46,7 +46,7 @@ Exchange your credentials for a JWT. The endpoint depends on how your site authe - Exchange a [Fern API key](/learn/cli-api/cli-reference/commands#fern-token) for a JWT via the [get-jwt endpoint](/learn/docs/fern-api-reference/get-jwt): + Exchange a [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) for a JWT via the [get-jwt endpoint](/learn/docs/fern-api-reference/get-jwt): ```bash curl https://docs.example.com/api/fern-docs/get-jwt \ diff --git a/fern/products/docs/pages/ai/writer.mdx b/fern/products/docs/pages/ai/writer.mdx index bbfe0c81de..5c3e4de353 100644 --- a/fern/products/docs/pages/ai/writer.mdx +++ b/fern/products/docs/pages/ai/writer.mdx @@ -83,7 +83,7 @@ Otherwise, install it on your docs repo (requires GitHub org admin access). The [Get a unique Slack installation link](/learn/docs/scribe-api/fern-writer-api/get-fern-writer-install-link) for your organization. Provide: -- Your [Fern API key](/learn/cli-api-reference/cli-reference/commands#fern-token) +- Your [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) - The GitHub repository in `owner/repo` format (e.g., `acme/docs`) You can alternatively use this cURL request: diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index f7c301f185..570fb9c931 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -84,5 +84,5 @@ navigation: - URL of your GraphQL API endpoint. Fern performs [introspection](https://graphql.org/learn/introspection/) against this endpoint to fetch the schema. When set, [running `fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) updates the local schema from this endpoint. + URL of your GraphQL API endpoint. Fern performs [introspection](https://graphql.org/learn/introspection/) against this endpoint to fetch the schema. When set, [running `fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) updates the local schema from this endpoint. diff --git a/fern/products/docs/pages/api-references/library-docs.mdx b/fern/products/docs/pages/api-references/library-docs.mdx index be31d79ed9..f45df7b373 100644 --- a/fern/products/docs/pages/api-references/library-docs.mdx +++ b/fern/products/docs/pages/api-references/library-docs.mdx @@ -73,7 +73,7 @@ navigation: -Run the [`fern docs md generate`](/learn/cli-api-reference/cli-reference/commands#fern-docs-md-generate) command to generate MDX files from your library source code: +Run the [`fern docs md generate`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-md-generate) command to generate MDX files from your library source code: diff --git a/fern/products/docs/pages/ask-fern/api-get-started.mdx b/fern/products/docs/pages/ask-fern/api-get-started.mdx index ad8bbaf430..a34592fd54 100644 --- a/fern/products/docs/pages/ask-fern/api-get-started.mdx +++ b/fern/products/docs/pages/ask-fern/api-get-started.mdx @@ -14,4 +14,4 @@ The Fern AI API allows you to manage your Ask Fern configuration using Fern's pu ## Authentication -Fern API requests require an API key for authentication. Use the CLI command [`fern token`](/learn/cli-api/cli-reference/commands#fern-token) to generate an API key. API keys don't expire. +Fern API requests require an API key for authentication. Use the CLI command [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) to generate an API key. API keys don't expire. diff --git a/fern/products/docs/pages/changelog/2026-05-14.mdx b/fern/products/docs/pages/changelog/2026-05-14.mdx index dbc585a32f..496aa35441 100644 --- a/fern/products/docs/pages/changelog/2026-05-14.mdx +++ b/fern/products/docs/pages/changelog/2026-05-14.mdx @@ -11,4 +11,4 @@ fern docs link check --url https://elevenlabs.io/docs This complements the existing [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `fern check`, which validates internal links against your local YAML navigation tree. Use `fern docs link check` after publishing to catch live 404s and broken external URLs that local validation can't detect. - + diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index 06c4d73f63..67724e1b27 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -74,7 +74,7 @@ In [versioned docs](/learn/docs/configuration/versions), the same path lands on ### Validating links -Fern provides two ways to catch broken links. The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/commands#fern-docs-link-check) or the [Fern Dashboard](https://dashboard.buildwithfern.com/). +Fern provides two ways to catch broken links. The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the [Fern Dashboard](https://dashboard.buildwithfern.com/). | | `fern check` broken-links rule | `fern docs link check` | |---|---|---| diff --git a/fern/products/docs/pages/customization/global-themes.mdx b/fern/products/docs/pages/customization/global-themes.mdx index f30d48e258..444749a158 100644 --- a/fern/products/docs/pages/customization/global-themes.mdx +++ b/fern/products/docs/pages/customization/global-themes.mdx @@ -14,7 +14,7 @@ This is useful when your organization maintains multiple documentation sites tha -From the repository that defines your canonical branding, [export](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-export) the theme: +From the repository that defines your canonical branding, [export](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-theme-export) the theme: ```bash fern docs theme export @@ -32,7 +32,7 @@ fern docs theme export --output ./my-theme -[Upload](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-upload) the exported theme to Fern's registry: +[Upload](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-theme-upload) the exported theme to Fern's registry: ```bash fern docs theme upload --name my-theme @@ -44,7 +44,7 @@ This uploads the theme configuration and all referenced file assets. If you omit -[List](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-list) all themes for your organization: +[List](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-theme-list) all themes for your organization: ```bash fern docs theme list @@ -70,7 +70,7 @@ global-theme: my-theme -Run the standard [publish command](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) from the child repository: +Run the standard [publish command](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs) from the child repository: ```bash fern generate --docs diff --git a/fern/products/docs/pages/developer-tools/gitlab.mdx b/fern/products/docs/pages/developer-tools/gitlab.mdx index 4552f16052..6069ee5a72 100644 --- a/fern/products/docs/pages/developer-tools/gitlab.mdx +++ b/fern/products/docs/pages/developer-tools/gitlab.mdx @@ -17,7 +17,7 @@ Use GitLab CI/CD to automatically generate preview links on merge requests, publ ### Generate a Fern API key -Run [`fern token`](/learn/cli-api-reference/cli-reference/commands#fern-token) in your terminal from the directory containing your `fern` folder. This generates an organization-scoped API key that authenticates the Fern CLI in CI/CD. +Run [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) in your terminal from the directory containing your `fern` folder. This generates an organization-scoped API key that authenticates the Fern CLI in CI/CD. ```bash fern token diff --git a/fern/products/docs/pages/getting-started/self-service-setup.mdx b/fern/products/docs/pages/getting-started/self-service-setup.mdx index 0f09447977..60422b82a1 100644 --- a/fern/products/docs/pages/getting-started/self-service-setup.mdx +++ b/fern/products/docs/pages/getting-started/self-service-setup.mdx @@ -18,7 +18,7 @@ The setup process also creates and configures: - **Organization**: An organization using your org ID, with you as a member. - **Fern API key**: A `FERN_TOKEN` in your repository's GitHub secrets that authenticates the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) in your CI/CD workflows, scoped to your organization. -- **GitHub Action**: A workflow that runs [`fern generate --docs`](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) whenever you push changes to your main branch, automatically rebuilding and publishing your documentation. +- **GitHub Action**: A workflow that runs [`fern generate --docs`](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs) whenever you push changes to your main branch, automatically rebuilding and publishing your documentation. After setup, you have full ownership of this repository. Push changes to your main branch to trigger an automatic rebuild and publish of your docs, or manage settings through the [Fern Dashboard](https://dashboard.buildwithfern.com). diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index f6b7604622..c333dc6c28 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1286,7 +1286,7 @@ ai-examples: ## Check configuration -Configure the severity of validation rules run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking). +Configure the severity of validation rules run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking). ```yaml docs.yml check: diff --git a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx index 2d9a284155..2ef696ef23 100644 --- a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx +++ b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx @@ -18,7 +18,7 @@ Install the following: ## Local development -[Run a local preview server](/learn/cli-api-reference/cli-reference/commands#fern-docs-dev) to view documentation changes instantly with hot reload. Offline access is available after the first online run. +[Run a local preview server](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-dev) to view documentation changes instantly with hot reload. Offline access is available after the first online run. ```bash # Start preview server (from directory containing fern folder) @@ -76,7 +76,7 @@ If the same command also prints `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts - For [internal pages](/learn/docs/writing-content/markdown-basics#link-format), use the published URL path from your `docs.yml` config (for example, `/learn/docs/configuration/navigation`) — not a relative path or on-disk file path. - For [images and other assets](/learn/docs/writing-content/markdown-media), use a path relative to the Markdown file. -Broken internal links fail by default. Use [`fern generate --docs --no-strict-broken-links`](/learn/cli-api-reference/cli-reference/commands#fern-generate) to downgrade the failure to a warning while you fix them. +Broken internal links fail by default. Use [`fern generate --docs --no-strict-broken-links`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-generate) to downgrade the failure to a warning while you fix them. #### `Invalid URL: /some/path` @@ -120,7 +120,7 @@ If your docs use [role-based access control](/learn/docs/authentication/features ### Manage preview links -Preview links persist indefinitely — Fern doesn't auto-expire them. Any organization member can use [`fern docs preview list`](/learn/cli-api-reference/cli-reference/commands#fern-docs-preview-list) to see active previews and [`fern docs preview delete`](/learn/cli-api-reference/cli-reference/commands#fern-docs-preview-delete) to remove them when they're no longer needed. To clean up previews automatically when PRs merge, set up a [GitHub Actions workflow](#clean-up-preview-links-when-prs-merge). +Preview links persist indefinitely — Fern doesn't auto-expire them. Any organization member can use [`fern docs preview list`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-preview-list) to see active previews and [`fern docs preview delete`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-preview-delete) to remove them when they're no longer needed. To clean up previews automatically when PRs merge, set up a [GitHub Actions workflow](#clean-up-preview-links-when-prs-merge). ### Automate with GitHub Actions @@ -135,7 +135,7 @@ You can use a GitHub Actions workflow to automatically generate a preview URL wh If you set up your site using the [guided UI](https://dashboard.buildwithfern.com/get-started) or [CLI quickstart](/learn/docs/getting-started/quickstart), this workflow is automatically included in your repository. Otherwise, add it manually using the examples below. -These workflows require a `FERN_TOKEN` [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). If you used the guided workflow, this secret is added automatically. Otherwise, generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/commands#fern-token) in your terminal, then add it in your repository's **Settings > Secrets and variables > Actions** with the name `FERN_TOKEN`. +These workflows require a `FERN_TOKEN` [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). If you used the guided workflow, this secret is added automatically. Otherwise, generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) in your terminal, then add it in your repository's **Settings > Secrets and variables > Actions** with the name `FERN_TOKEN`. You may need to re-run preview builds for any PRs that were opened before you configured the `FERN_TOKEN`. @@ -322,7 +322,7 @@ jobs: #### Clean up preview links when PRs merge -To clean up preview links automatically after a PR is merged, add this workflow alongside the one above. It calls [`fern docs preview delete`](/learn/cli-api-reference/cli-reference/commands#fern-docs-preview-delete) with the PR's branch name as the `--id`, matching the identifier used when the preview was generated. +To clean up preview links automatically after a PR is merged, add this workflow alongside the one above. It calls [`fern docs preview delete`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-preview-delete) with the PR's branch name as the `--id`, matching the identifier used when the preview was generated. ```yaml diff --git a/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx b/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx index 9c0badd4fc..e1a9089246 100644 --- a/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx +++ b/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx @@ -197,7 +197,7 @@ To unpublish a docs site, navigate to the **Settings** page for your site in the ### No token found. Please set the FERN_TOKEN environment variable or run `fern login`. -`fern generate --docs` needs an authenticated session to publish. Run [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) locally, or set `FERN_TOKEN` in your shell or CI environment. Generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/commands#fern-token). +`fern generate --docs` needs an authenticated session to publish. Run [`fern login`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-login) locally, or set `FERN_TOKEN` in your shell or CI environment. Generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token). ### OpenAPI spec validation failed with N errors. Fix the errors above before generating docs. diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index aa4f9a9eeb..602584f1ae 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -68,7 +68,7 @@ Set the `slug` property in `docs.yml` or in a page's frontmatter to customize th - **Product and version prefixes**: preserved in both cases. - Changing a slug updates the page's URL. Run [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) to detect pages that moved without a [redirect](/learn/docs/seo/redirects#catching-missing-redirects), so existing links don't break. + Changing a slug updates the page's URL. Run [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check) to detect pages that moved without a [redirect](/learn/docs/seo/redirects#catching-missing-redirects), so existing links don't break. ### Modify a tab slug diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index 9605c2ab8d..fd6a74b001 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -115,7 +115,7 @@ Overriding the default versioning behavior manually can lead to unexpected redir ## Catching missing redirects -The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. Tune its severity in `docs.yml`. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. Tune its severity in `docs.yml`. ## Common errors diff --git a/fern/products/sdks/custom-code.mdx b/fern/products/sdks/custom-code.mdx index f27e618ab3..fdb149cdc1 100644 --- a/fern/products/sdks/custom-code.mdx +++ b/fern/products/sdks/custom-code.mdx @@ -76,7 +76,7 @@ Replay automatically preserves the edits you make to your generated SDK across r * ... ``` -If the generator and your customization changed the same lines, Replay reports the conflict in the PR body. Run [`fern replay resolve`](/learn/cli-api-reference/cli-reference/commands#fern-replay-resolve) locally to walk through it. +If the generator and your customization changed the same lines, Replay reports the conflict in the PR body. Run [`fern replay resolve`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-replay-resolve) locally to walk through it. ### Enable Replay diff --git a/fern/products/sdks/deep-dives/self-hosted.mdx b/fern/products/sdks/deep-dives/self-hosted.mdx index b9d8b7ef03..d8b26cb5fb 100644 --- a/fern/products/sdks/deep-dives/self-hosted.mdx +++ b/fern/products/sdks/deep-dives/self-hosted.mdx @@ -147,7 +147,7 @@ fern generate --group python-sdk --local To pull generator images from a private registry your organization controls instead of Docker Hub, see [Private registry setup](#private-registry-setup). -To share a locally generated SDK internally without publishing it to a registry, add [`--package`](/learn/cli-api-reference/cli-reference/commands#package), which builds a distributable artifact into a `fern-dist/` folder inside the output directory. +To share a locally generated SDK internally without publishing it to a registry, add [`--package`](/learn/cli-api-reference/cli-reference/sdk-commands#package), which builds a distributable artifact into a `fern-dist/` folder inside the output directory. diff --git a/fern/products/sdks/generators/csharp/publishing-to-nuget.mdx b/fern/products/sdks/generators/csharp/publishing-to-nuget.mdx index 298edffec1..3637ae741a 100644 --- a/fern/products/sdks/generators/csharp/publishing-to-nuget.mdx +++ b/fern/products/sdks/generators/csharp/publishing-to-nuget.mdx @@ -9,7 +9,7 @@ registry](https://www.nuget.org/). After following the steps on this page, you'll have a versioned package published on NuGet. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a `.nupkg` with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). If you're using API key authentication, consider switching to OIDC (trusted publishing). See [Migrating from API key to OIDC publishing](#migrating-from-api-key-to-oidc-publishing) for the steps. diff --git a/fern/products/sdks/generators/csharp/quickstart.mdx b/fern/products/sdks/generators/csharp/quickstart.mdx index 0988ab7a17..b703ffafc6 100644 --- a/fern/products/sdks/generators/csharp/quickstart.mdx +++ b/fern/products/sdks/generators/csharp/quickstart.mdx @@ -59,7 +59,7 @@ fern generate --group csharp-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group csharp-sdk --api your-api-name diff --git a/fern/products/sdks/generators/go/publishing-to-go-package-manager.mdx b/fern/products/sdks/generators/go/publishing-to-go-package-manager.mdx index ab3393dd0f..bf1c9abed8 100644 --- a/fern/products/sdks/generators/go/publishing-to-go-package-manager.mdx +++ b/fern/products/sdks/generators/go/publishing-to-go-package-manager.mdx @@ -8,7 +8,7 @@ Publish your public-facing Fern Go SDK to [pkg.go.dev](https://pkg.go.dev/). To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a module source zip -with [`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +with [`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). This page assumes that you have: diff --git a/fern/products/sdks/generators/go/quickstart.mdx b/fern/products/sdks/generators/go/quickstart.mdx index 4cf5fd1534..144158e942 100644 --- a/fern/products/sdks/generators/go/quickstart.mdx +++ b/fern/products/sdks/generators/go/quickstart.mdx @@ -59,7 +59,7 @@ fern generate --group go-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group go-sdk --api your-api-name diff --git a/fern/products/sdks/generators/java/publishing-to-maven-central.mdx b/fern/products/sdks/generators/java/publishing-to-maven-central.mdx index 9007400147..1999a6986a 100644 --- a/fern/products/sdks/generators/java/publishing-to-maven-central.mdx +++ b/fern/products/sdks/generators/java/publishing-to-maven-central.mdx @@ -9,7 +9,7 @@ registry](https://central.sonatype.com/). After following the steps on this page, you'll have a versioned package published on Maven Central. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a JAR with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). This page assumes that you have: diff --git a/fern/products/sdks/generators/java/quickstart.mdx b/fern/products/sdks/generators/java/quickstart.mdx index 82af101ba3..b26a39dfd1 100644 --- a/fern/products/sdks/generators/java/quickstart.mdx +++ b/fern/products/sdks/generators/java/quickstart.mdx @@ -59,7 +59,7 @@ fern generate --group java-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group java-sdk --api your-api-name diff --git a/fern/products/sdks/generators/php/publishing-to-packagist.mdx b/fern/products/sdks/generators/php/publishing-to-packagist.mdx index c50230f893..9af07ceb6e 100644 --- a/fern/products/sdks/generators/php/publishing-to-packagist.mdx +++ b/fern/products/sdks/generators/php/publishing-to-packagist.mdx @@ -9,7 +9,7 @@ registry](https://packagist.org/). After following the steps on this page, you'll have a versioned package published on Packagist. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a Composer archive -with [`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +with [`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). This page assumes that you have: diff --git a/fern/products/sdks/generators/php/quickstart.mdx b/fern/products/sdks/generators/php/quickstart.mdx index f251a200d7..ab0b05ea2b 100644 --- a/fern/products/sdks/generators/php/quickstart.mdx +++ b/fern/products/sdks/generators/php/quickstart.mdx @@ -59,7 +59,7 @@ fern generate --group php-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group php-sdk --api your-api-name diff --git a/fern/products/sdks/generators/python/publishing-to-pypi.mdx b/fern/products/sdks/generators/python/publishing-to-pypi.mdx index 0ebad5b1ef..06bc64dd0c 100644 --- a/fern/products/sdks/generators/python/publishing-to-pypi.mdx +++ b/fern/products/sdks/generators/python/publishing-to-pypi.mdx @@ -9,7 +9,7 @@ registry](https://pypi.org/). After following the steps on this page, you'll have a versioned package published on PyPI. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a wheel with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). If you're using token-based authentication, consider switching to OIDC (trusted publishing). See [Migrating from token-based to OIDC publishing](#migrating-from-token-based-to-oidc-publishing) for the steps. diff --git a/fern/products/sdks/generators/python/quickstart.mdx b/fern/products/sdks/generators/python/quickstart.mdx index 6cb2c9b9f8..a9b402fb3f 100644 --- a/fern/products/sdks/generators/python/quickstart.mdx +++ b/fern/products/sdks/generators/python/quickstart.mdx @@ -55,7 +55,7 @@ fern generate --group python-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group python-sdk --api your-api-name diff --git a/fern/products/sdks/generators/ruby/publishing-to-rubygems.mdx b/fern/products/sdks/generators/ruby/publishing-to-rubygems.mdx index 6b5025b05d..21ed4350c8 100644 --- a/fern/products/sdks/generators/ruby/publishing-to-rubygems.mdx +++ b/fern/products/sdks/generators/ruby/publishing-to-rubygems.mdx @@ -9,7 +9,7 @@ registry](https://rubygems.org/). After following the steps on this page, you'll have a versioned package published on RubyGems. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a gem with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). This page assumes that you have: diff --git a/fern/products/sdks/generators/ruby/quickstart.mdx b/fern/products/sdks/generators/ruby/quickstart.mdx index f1b5709a0b..e4cdf781dc 100644 --- a/fern/products/sdks/generators/ruby/quickstart.mdx +++ b/fern/products/sdks/generators/ruby/quickstart.mdx @@ -59,7 +59,7 @@ fern generate --group ruby-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group ruby-sdk --api your-api-name diff --git a/fern/products/sdks/generators/rust/publishing-to-crates-io.mdx b/fern/products/sdks/generators/rust/publishing-to-crates-io.mdx index a7cc205236..cb5e1626e3 100644 --- a/fern/products/sdks/generators/rust/publishing-to-crates-io.mdx +++ b/fern/products/sdks/generators/rust/publishing-to-crates-io.mdx @@ -9,7 +9,7 @@ registry](https://crates.io/). After following the steps on this page, you'll have a versioned crate published on crates.io. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a `.crate` file with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). This page assumes that you have: diff --git a/fern/products/sdks/generators/typescript/publishing-to-npm.mdx b/fern/products/sdks/generators/typescript/publishing-to-npm.mdx index bc78f73e44..1273bf43f9 100644 --- a/fern/products/sdks/generators/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/generators/typescript/publishing-to-npm.mdx @@ -9,7 +9,7 @@ registry](https://www.npmjs.com/). After following the steps on this page, you'll have a versioned package published on npm. To distribute the SDK internally instead, generate to the local file system (optionally [self-hosted](/learn/sdks/deep-dives/self-hosted)) and build a tarball with -[`fern generate --package`](/learn/cli-api-reference/cli-reference/commands#package). +[`fern generate --package`](/learn/cli-api-reference/cli-reference/sdk-commands#package). If you're using token-based authentication, npm has deprecated long-lived classic tokens. See [Migrating from token-based to OpenID Connect (OIDC) publishing](#migrating-from-token-based-to-oidc-publishing) to upgrade to the more secure OIDC authentication. diff --git a/fern/products/sdks/generators/typescript/quickstart.mdx b/fern/products/sdks/generators/typescript/quickstart.mdx index 3e28b66fd2..221cdb9c41 100644 --- a/fern/products/sdks/generators/typescript/quickstart.mdx +++ b/fern/products/sdks/generators/typescript/quickstart.mdx @@ -58,7 +58,7 @@ fern generate --group ts-sdk ``` - If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + If you have multiple APIs, use the [`--api` flag](/learn/cli-api-reference/cli-reference/sdk-commands#api) to specify the API you want to generate: ```bash fern generate --group ts-sdk --api your-api-name diff --git a/fern/products/sdks/replay-migration.mdx b/fern/products/sdks/replay-migration.mdx index 5888c4584a..77108ffe39 100644 --- a/fern/products/sdks/replay-migration.mdx +++ b/fern/products/sdks/replay-migration.mdx @@ -226,8 +226,8 @@ Re-add the credentials you removed in Phase 1. | Command | Effect | |---------|--------| -| [`fern generate --no-replay`](/learn/cli-api-reference/cli-reference/commands#no-replay) | Skip patch application for one generation. Generation still creates `[fern-generated]`; patches aren't applied. Useful for debugging. | -| [`fern replay forget`](/learn/cli-api-reference/cli-reference/commands#fern-replay-forget) | Untrack patches by ID, by pattern, or all at once. The next generation overwrites those files. | +| [`fern generate --no-replay`](/learn/cli-api-reference/cli-reference/sdk-commands#no-replay) | Skip patch application for one generation. Generation still creates `[fern-generated]`; patches aren't applied. Useful for debugging. | +| [`fern replay forget`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-replay-forget) | Untrack patches by ID, by pattern, or all at once. The next generation overwrites those files. | ## Known caveats From 6d65a59f3accf5da1ca4e2b1d7b0352c590e2a8f Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 19 Aug 2026 21:18:32 +0000 Subject: [PATCH 2/3] Move general CLI commands to their own reference page --- .../cli-api-reference/cli-api-reference.yml | 5 +- .../cli-api-reference/pages/docs-commands.mdx | 4 +- .../pages/general-commands.mdx | 492 ++++++++++++++++++ .../cli-api-reference/pages/sdk-commands.mdx | 485 +---------------- 4 files changed, 499 insertions(+), 487 deletions(-) create mode 100644 fern/products/cli-api-reference/pages/general-commands.mdx diff --git a/fern/products/cli-api-reference/cli-api-reference.yml b/fern/products/cli-api-reference/cli-api-reference.yml index b9c9ef8321..db4a067f37 100644 --- a/fern/products/cli-api-reference/cli-api-reference.yml +++ b/fern/products/cli-api-reference/cli-api-reference.yml @@ -7,6 +7,9 @@ navigation: - page: Global options path: ./pages/global-options.mdx slug: options + - page: General Commands + path: ./pages/general-commands.mdx + slug: general-commands - page: Docs Commands path: ./pages/docs-commands.mdx slug: docs-commands @@ -16,4 +19,4 @@ navigation: - page: CLI version policy path: ./pages/cli-version-policy.mdx slug: version-policy - - changelog: ./cli-changelog + - changelog: ./cli-changelog \ No newline at end of file diff --git a/fern/products/cli-api-reference/pages/docs-commands.mdx b/fern/products/cli-api-reference/pages/docs-commands.mdx index 8d7a9a7ff9..c5a49f1b71 100644 --- a/fern/products/cli-api-reference/pages/docs-commands.mdx +++ b/fern/products/cli-api-reference/pages/docs-commands.mdx @@ -302,7 +302,7 @@ hideOnThisPage: true - Unlike the [`broken-links` rule](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site. + Unlike the [`broken-links` rule](/learn/cli-api-reference/cli-reference/general-commands#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site. By default, the command auto-detects your docs URL from the `instances` in `docs.yml`. When all links are valid, the command exits with a success message. @@ -387,4 +387,4 @@ hideOnThisPage: true ``` - + \ No newline at end of file diff --git a/fern/products/cli-api-reference/pages/general-commands.mdx b/fern/products/cli-api-reference/pages/general-commands.mdx new file mode 100644 index 0000000000..c99229bca8 --- /dev/null +++ b/fern/products/cli-api-reference/pages/general-commands.mdx @@ -0,0 +1,492 @@ +--- +title: 'General Commands' +description: 'Complete reference for general Fern CLI commands.' +subtitle: 'Commands that apply across SDKs and docs.' +hideOnThisPage: true +--- + +| Command | Description | +|---------|-------------| +| [`fern init`](#fern-init) | Create new Fern project from OpenAPI spec or scratch | +| [`fern check`](#fern-check) | Validate API definition & configuration | +| [`fern upgrade`](#fern-upgrade) | Update Fern CLI & generators to latest versions | +| [`fern downgrade`](#fern-downgrade) | Move the Fern CLI version in `fern.config.json` back to an older version | +| [`fern login`](#fern-login) | Login to Fern CLI via GitHub, Google, Postman, or enterprise SSO | +| [`fern logout`](#fern-logout) | Log out of the Fern CLI | +| [`fern export`](#fern-export) | Export an OpenAPI spec for your API | +| [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec | +| [`fern api enrich`](#fern-api-enrich) | Merge `x-fern-examples` from an overrides file into native OpenAPI examples | +| [`fern org get`](#fern-org-get) | View your organization's CLI version policy | +| [`fern org set cli-version`](#fern-org-set-cli-version) | Set a minimum, maximum, or exact CLI version for your organization | +| [`fern org unset cli-version`](#fern-org-unset-cli-version) | Clear your organization's CLI version policy | + +## Detailed command documentation + + + + + Use `fern init` to initialize a new Fern workspace in the current folder. By default, you'll see the IMDb API example. + + + ```bash + fern init [--docs] [--openapi ] + ``` + + + When initializing with OpenAPI, your project structure will look like this: + + + + + + + + + + + + ### openapi + + Use `--openapi` to initialize a project from an OpenAPI specification: + + ```bash + # Initialize from local file + fern init --openapi ./path/to/openapi.yml + + # Initialize from URL + fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json + ``` + + ### docs + + By adding `--docs`, you'll also get a sample documentation website for your API with an API Reference section. + + ```bash + fern init --docs + ``` + + The file added will contain: + + ```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' + ``` + + To publish the API docs, run [`fern generate --docs`](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs). + + ### mintlify + + By adding `--mintlify PATH_TO_MINT_CONFIG`, the CLI will automatically convert your Mintlify docs folder into a Fern docs site, based on the `mint.json` file. + + ```bash + fern init --mintlify PATH_TO_MINT_CONFIG + ``` + + The CLI will create a `fern/` folder with the following structure: + + + + + + + + + + ### readme + + The `fern init` command supports importing Readme generated docs sites. This requires having a local chromium browser instance installed. + You can ensure this is installed by installing the `fern` cli from source, following the instructions [here](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md). + + By adding `--readme URL_TO_README_DOCS_SITE`, the CLI will automatically convert the Readme generated docs site into a Fern docs site. + + ```bash + fern init --readme URL_TO_README_DOCS_SITE + ``` + + The CLI will create a `fern/` folder with the following structure: + + + + + + + + + + + For more information on getting started, check out our [Quickstart Guide](/learn/docs/getting-started/quickstart) + + + + + + Use `fern export` to generate an OpenAPI spec for your API. This is useful when you've defined your API in a format other than OpenAPI (such as the [Fern Definition](/learn/api-definitions/ferndef/overview)) and need to export it for integration with other tools or services. + + The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec. + + + ```bash + # Write the exported spec as YAML + fern export [--api ] path/to/openapi.yml + + # ...or as JSON + fern export [--api ] path/to/openapi.json + ``` + + + ### api + + Use `--api` to specify which API to export when you have multiple APIs defined in your `fern/apis/` folder. + + + ```bash + fern export --api public-api path/to/openapi.yml + ``` + + + ### indent + + Use `--indent` to set the indentation size, in spaces, of the generated spec. + + + ```bash + fern export --indent 4 path/to/openapi.yml + ``` + + + + + + + + The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead. + + + Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. + + Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`. + + + ```bash + fern check [--api ] [--warnings] + ``` + + + You can configure the severity of the validation rules run by `fern check` in your `docs.yml` file [using the `check.rules` property](/learn/docs/configuration/site-level-settings#check-configuration). + + ```yaml docs.yml + check: + rules: + broken-links: error + example-validation: warn + missing-redirects: error + ``` + + + To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + + + ### api + + Use `--api ` to specify which API you'd like to check. + + ```bash + fern check --api public-api + ``` + + ### warnings + + Use `--warnings` to log warnings in addition to errors. + + ```bash + fern check --warnings + ``` + + ## Usage in a GitHub Action + + + ```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 + + ``` + + + + + + + Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the + latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions. + + + ```bash + fern upgrade [--version ] [--from ] [--yes] + ``` + + + When your organization sets a [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy#interaction-with-fern-upgrade), `fern upgrade` writes the highest version the policy allows rather than the latest published version. A `--version` below the organization's minimum is raised to the minimum. + + ### version + + Use `--version` to upgrade to a specific published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions) instead of the latest release. The version must be ahead of the version in `fern.config.json`; use [`fern downgrade`](#fern-downgrade) to move to an older version. + + ```bash + fern upgrade --version 5.45.0 + ``` + + ### from + + Use `--from` to set the version that migrations run from. Fern infers this from `fern.config.json` and git history; pass it when that inference is wrong, such as after `fern.config.json` was edited by hand. + + ```bash + fern upgrade --from 4.20.0 + ``` + + ### yes + + Use `--yes` (`-y`) to answer yes to every migration prompt, for non-interactive environments like CI. + + ```bash + fern upgrade --yes + ``` + + + + + + Use `fern downgrade` to set the CLI version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to an older version. It rewrites the `version` field only: generator versions in `generators.yml` are left alone, and no migrations are reversed. + + + ```bash + fern downgrade + ``` + + + ```bash + fern downgrade 5.40.0 + ``` + + A [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy) doesn't block the downgrade, but it does override it: the new version is written to `fern.config.json`, and subsequent commands still run the minimum required by your organization. + + + + + + Use `fern login` to login to the Fern CLI via GitHub or Google. Logging in allows you + join GitHub organizations, gain permissions, and contribute to projects. + + + ```bash + fern login + fern login --device-code + fern login --email + ``` + + + By default, `fern login` opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available: + + ### device-code + + Use `--device-code` to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers). + + ```bash + fern login --device-code + ``` + + ### email + + Use `--email` to login via enterprise SSO. Pass the email address associated with your organization's SSO provider. + + ```bash + fern login --email user@example.com + ``` + + + To enable CI/CD, use [`fern token`](#fern-token). + + + + + + + Use `fern logout` to log out of the Fern CLI. This will clear your authentication + credentials and revoke access to your GitHub organizations and permissions. + + + ```bash + fern logout + ``` + + + After logging out, you'll need to run [`fern login`](#fern-login) again to access protected features. + + + + + + + + See [Publishing your docs](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions) for instructions on using this API key in automated publishing workflows. + + + + + Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and + updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). + + + ```bash + fern api update [--api ] + ``` + + + ### api + + Use `--api` to specify the API to update if there are multiple specs with a defined `origin` in `generators.yml`. If you don't specify an API, all OpenAPI specs with an `origin` will be updated. + + + ```bash + fern api update --api public-api + ``` + + + + + + Use `fern api enrich` to convert [AI-generated examples](/learn/docs/ai-features/ai-examples) or manually authored [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) into portable OpenAPI examples that any OpenAPI-compatible tool can consume. + + + ```bash + fern api enrich -f -o + ``` + + + The command merges examples from an overrides file into native OpenAPI `example` fields and strips the `x-fern-examples` keys from the output. When an endpoint has multiple examples, each is stored as a named entry under the plural `examples` field. + + The command requires two flags: + + - `-f` (or `--file`) — the overrides file containing `x-fern-examples` (e.g., `ai_examples_override.yml`). + - `-o` (or `--output`) — the path for the enriched output file. Supports `.yml` and `.json` extensions. + + ```bash + # Output as YAML + fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml + + # Output as JSON + fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.json + ``` + + Each `x-fern-examples` field is mapped to its standard OpenAPI location: + + - `path-parameters` → `parameters[].example` (where `in: path`) + - `query-parameters` → `parameters[].example` (where `in: query`) + - `headers` → `parameters[].example` (where `in: header`) + - `request` → `requestBody.content.*.example` + - `response.body` → `responses..content.*.example` + + + + + + Use `fern org get` to view your organization's [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy). + + + ```bash + fern org get [--json] [--org ] + ``` + + + ### json + + Use `--json` to output the raw `cliVersionMin` and `cliVersionMax` fields instead of a one-line description. + + ```bash + fern org get --json + ``` + + ### org + + Use `--org` to override the organization ID from `fern.config.json`. + + ```bash + fern org get --org my-org + ``` + + + + + + Use `fern org set cli-version` to [constrain the Fern CLI version](/learn/cli-api-reference/cli-reference/version-policy) used by every project in your organization. Requires an organization admin. + + + ```bash + fern org set cli-version [version] [--min ] [--max ] [--org ] + ``` + + + ```bash + # Pin an exact version + fern org set cli-version 5.45.0 + + # Set a minimum, a maximum, or both + fern org set cli-version --min 5.40.0 + fern org set cli-version --max 5.50.0 + fern org set cli-version --min 5.40.0 --max 5.50.0 + ``` + + Each bound is an exact published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions). + + ### org + + Use `--org` to override the organization ID from `fern.config.json`. + + ```bash + fern org set cli-version 5.45.0 --org my-org + ``` + + + + + + Use `fern org unset cli-version` to remove your organization's [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy). Requires an organization admin. + + + ```bash + fern org unset cli-version [--min] [--max] [--org ] + ``` + + + Both bounds are removed by default. Pass `--min` or `--max` to clear one end and keep the other. + + ```bash + fern org unset cli-version --max + ``` + + + \ No newline at end of file diff --git a/fern/products/cli-api-reference/pages/sdk-commands.mdx b/fern/products/cli-api-reference/pages/sdk-commands.mdx index 5309be6e72..843448008a 100644 --- a/fern/products/cli-api-reference/pages/sdk-commands.mdx +++ b/fern/products/cli-api-reference/pages/sdk-commands.mdx @@ -5,21 +5,6 @@ subtitle: 'Learn about the Fern CLI SDK commands.' hideOnThisPage: true --- -| Command | Description | -|---------|-------------| -| [`fern init`](#fern-init) | Create new Fern project from OpenAPI spec or scratch | -| [`fern check`](#fern-check) | Validate API definition & configuration | -| [`fern upgrade`](#fern-upgrade) | Update Fern CLI & generators to latest versions | -| [`fern downgrade`](#fern-downgrade) | Move the Fern CLI version in `fern.config.json` back to an older version | -| [`fern login`](#fern-login) | Login to Fern CLI via GitHub, Google, Postman, or enterprise SSO | -| [`fern logout`](#fern-logout) | Log out of the Fern CLI | -| [`fern export`](#fern-export) | Export an OpenAPI spec for your API | -| [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec | -| [`fern api enrich`](#fern-api-enrich) | Merge `x-fern-examples` from an overrides file into native OpenAPI examples | -| [`fern org get`](#fern-org-get) | View your organization's CLI version policy | -| [`fern org set cli-version`](#fern-org-set-cli-version) | Set a minimum, maximum, or exact CLI version for your organization | -| [`fern org unset cli-version`](#fern-org-unset-cli-version) | Clear your organization's CLI version policy | - ## SDK generation commands | Command | Description | @@ -33,145 +18,6 @@ hideOnThisPage: true ## Detailed command documentation - - - Use `fern init` to initialize a new Fern workspace in the current folder. By default, you'll see the IMDb API example. - - - ```bash - fern init [--docs] [--openapi ] - ``` - - - When initializing with OpenAPI, your project structure will look like this: - - - - - - - - - - - - ### openapi - - Use `--openapi` to initialize a project from an OpenAPI specification: - - ```bash - # Initialize from local file - fern init --openapi ./path/to/openapi.yml - - # Initialize from URL - fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json - ``` - - ### docs - - By adding `--docs`, you'll also get a sample documentation website for your API with an API Reference section. - - ```bash - fern init --docs - ``` - - The file added will contain: - - ```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' - ``` - - To publish the API docs, run [`fern generate --docs`](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs). - - ### mintlify - - By adding `--mintlify PATH_TO_MINT_CONFIG`, the CLI will automatically convert your Mintlify docs folder into a Fern docs site, based on the `mint.json` file. - - ```bash - fern init --mintlify PATH_TO_MINT_CONFIG - ``` - - The CLI will create a `fern/` folder with the following structure: - - - - - - - - - - ### readme - - The `fern init` command supports importing Readme generated docs sites. This requires having a local chromium browser instance installed. - You can ensure this is installed by installing the `fern` cli from source, following the instructions [here](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md). - - By adding `--readme URL_TO_README_DOCS_SITE`, the CLI will automatically convert the Readme generated docs site into a Fern docs site. - - ```bash - fern init --readme URL_TO_README_DOCS_SITE - ``` - - The CLI will create a `fern/` folder with the following structure: - - - - - - - - - - - For more information on getting started, check out our [Quickstart Guide](/learn/docs/getting-started/quickstart) - - - - - - Use `fern export` to generate an OpenAPI spec for your API. This is useful when you've defined your API in a format other than OpenAPI (such as the [Fern Definition](/learn/api-definitions/ferndef/overview)) and need to export it for integration with other tools or services. - - The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec. - - - ```bash - # Write the exported spec as YAML - fern export [--api ] path/to/openapi.yml - - # ...or as JSON - fern export [--api ] path/to/openapi.json - ``` - - - ### api - - Use `--api` to specify which API to export when you have multiple APIs defined in your `fern/apis/` folder. - - - ```bash - fern export --api public-api path/to/openapi.yml - ``` - - - ### indent - - Use `--indent` to set the indentation size, in spaces, of the generated spec. - - - ```bash - fern export --indent 4 path/to/openapi.yml - ``` - - - - Use `fern generate` to run the Fern compiler and create SDKs for your API. @@ -350,335 +196,6 @@ hideOnThisPage: true - - - - The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead. - - - Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. - - Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`. - - - ```bash - fern check [--api ] [--warnings] - ``` - - - You can configure the severity of the validation rules run by `fern check` in your `docs.yml` file [using the `check.rules` property](/learn/docs/configuration/site-level-settings#check-configuration). - - ```yaml docs.yml - check: - rules: - broken-links: error - example-validation: warn - missing-redirects: error - ``` - - - To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. - - - ### api - - Use `--api ` to specify which API you'd like to check. - - ```bash - fern check --api public-api - ``` - - ### warnings - - Use `--warnings` to log warnings in addition to errors. - - ```bash - fern check --warnings - ``` - - ## Usage in a GitHub Action - - - ```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 - - ``` - - - - - - - - Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the - latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions. - - - ```bash - fern upgrade [--version ] [--from ] [--yes] - ``` - - - When your organization sets a [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy#interaction-with-fern-upgrade), `fern upgrade` writes the highest version the policy allows rather than the latest published version. A `--version` below the organization's minimum is raised to the minimum. - - ### version - - Use `--version` to upgrade to a specific published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions) instead of the latest release. The version must be ahead of the version in `fern.config.json`; use [`fern downgrade`](#fern-downgrade) to move to an older version. - - ```bash - fern upgrade --version 5.45.0 - ``` - - ### from - - Use `--from` to set the version that migrations run from. Fern infers this from `fern.config.json` and git history; pass it when that inference is wrong, such as after `fern.config.json` was edited by hand. - - ```bash - fern upgrade --from 4.20.0 - ``` - - ### yes - - Use `--yes` (`-y`) to answer yes to every migration prompt, for non-interactive environments like CI. - - ```bash - fern upgrade --yes - ``` - - - - - - Use `fern downgrade` to set the CLI version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to an older version. It rewrites the `version` field only: generator versions in `generators.yml` are left alone, and no migrations are reversed. - - - ```bash - fern downgrade - ``` - - - ```bash - fern downgrade 5.40.0 - ``` - - A [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy) doesn't block the downgrade, but it does override it: the new version is written to `fern.config.json`, and subsequent commands still run the minimum required by your organization. - - - - - - Use `fern login` to login to the Fern CLI via GitHub or Google. Logging in allows you - join GitHub organizations, gain permissions, and contribute to projects. - - - ```bash - fern login - fern login --device-code - fern login --email - ``` - - - By default, `fern login` opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available: - - ### device-code - - Use `--device-code` to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers). - - ```bash - fern login --device-code - ``` - - ### email - - Use `--email` to login via enterprise SSO. Pass the email address associated with your organization's SSO provider. - - ```bash - fern login --email user@example.com - ``` - - - To enable CI/CD, use [`fern token`](#fern-token). - - - - - - - Use `fern logout` to log out of the Fern CLI. This will clear your authentication - credentials and revoke access to your GitHub organizations and permissions. - - - ```bash - fern logout - ``` - - - After logging out, you'll need to run [`fern login`](#fern-login) again to access protected features. - - - - - - - - See [Publishing your docs](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions) for instructions on using this API key in automated publishing workflows. - - - - - Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and - updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). - - - ```bash - fern api update [--api ] - ``` - - - ### api - - Use `--api` to specify the API to update if there are multiple specs with a defined `origin` in `generators.yml`. If you don't specify an API, all OpenAPI specs with an `origin` will be updated. - - - ```bash - fern api update --api public-api - ``` - - - - - - Use `fern api enrich` to convert [AI-generated examples](/learn/docs/ai-features/ai-examples) or manually authored [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) into portable OpenAPI examples that any OpenAPI-compatible tool can consume. - - - ```bash - fern api enrich -f -o - ``` - - - The command merges examples from an overrides file into native OpenAPI `example` fields and strips the `x-fern-examples` keys from the output. When an endpoint has multiple examples, each is stored as a named entry under the plural `examples` field. - - The command requires two flags: - - - `-f` (or `--file`) — the overrides file containing `x-fern-examples` (e.g., `ai_examples_override.yml`). - - `-o` (or `--output`) — the path for the enriched output file. Supports `.yml` and `.json` extensions. - - ```bash - # Output as YAML - fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml - - # Output as JSON - fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.json - ``` - - Each `x-fern-examples` field is mapped to its standard OpenAPI location: - - - `path-parameters` → `parameters[].example` (where `in: path`) - - `query-parameters` → `parameters[].example` (where `in: query`) - - `headers` → `parameters[].example` (where `in: header`) - - `request` → `requestBody.content.*.example` - - `response.body` → `responses..content.*.example` - - - - - - Use `fern org get` to view your organization's [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy). - - - ```bash - fern org get [--json] [--org ] - ``` - - - ### json - - Use `--json` to output the raw `cliVersionMin` and `cliVersionMax` fields instead of a one-line description. - - ```bash - fern org get --json - ``` - - ### org - - Use `--org` to override the organization ID from `fern.config.json`. - - ```bash - fern org get --org my-org - ``` - - - - - - Use `fern org set cli-version` to [constrain the Fern CLI version](/learn/cli-api-reference/cli-reference/version-policy) used by every project in your organization. Requires an organization admin. - - - ```bash - fern org set cli-version [version] [--min ] [--max ] [--org ] - ``` - - - ```bash - # Pin an exact version - fern org set cli-version 5.45.0 - - # Set a minimum, a maximum, or both - fern org set cli-version --min 5.40.0 - fern org set cli-version --max 5.50.0 - fern org set cli-version --min 5.40.0 --max 5.50.0 - ``` - - Each bound is an exact published version of the [`fern-api` package](https://www.npmjs.com/package/fern-api?activeTab=versions). - - ### org - - Use `--org` to override the organization ID from `fern.config.json`. - - ```bash - fern org set cli-version 5.45.0 --org my-org - ``` - - - - - - Use `fern org unset cli-version` to remove your organization's [CLI version policy](/learn/cli-api-reference/cli-reference/version-policy). Requires an organization admin. - - - ```bash - fern org unset cli-version [--min] [--max] [--org ] - ``` - - - Both bounds are removed by default. Pass `--min` or `--max` to clear one end and keep the other. - - ```bash - fern org unset cli-version --max - ``` - - - Use `fern write-overrides` to generate a basic OpenAPI overrides file. An overrides file allows for @@ -861,4 +378,4 @@ hideOnThisPage: true ``` - + \ No newline at end of file From 84ad691af1926dd2910ff5db8568c80104bbff92 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 19 Aug 2026 18:18:37 -0400 Subject: [PATCH 3/3] updates --- fern/docs.yml | 4 ++-- fern/products/api-def/ferndef/export-openapi.mdx | 2 +- fern/products/api-def/openapi/automation.mdx | 2 +- .../products/api-def/openapi/extensions/examples.mdx | 2 +- fern/products/api-def/pages/project-structure.mdx | 2 +- .../products/cli-api-reference/cli-api-reference.yml | 6 +++--- .../cli-api-reference/pages/cli-get-started.mdx | 2 +- .../cli-api-reference/pages/cli-version-policy.mdx | 12 ++++++------ .../cli-api-reference/pages/docs-commands.mdx | 4 ++-- .../cli-api-reference/pages/general-commands.mdx | 7 +++++-- .../cli-api-reference/pages/sdk-commands.mdx | 4 ++-- fern/products/docs/pages/ai/ai-examples.mdx | 2 +- fern/products/docs/pages/ai/markdown.mdx | 2 +- fern/products/docs/pages/ai/mcp-server.mdx | 2 +- fern/products/docs/pages/ai/writer.mdx | 2 +- .../pages/api-references/generate-graphql-ref.mdx | 2 +- .../products/docs/pages/ask-fern/api-get-started.mdx | 2 +- .../writing-content/markdown-basics.mdx | 2 +- fern/products/docs/pages/developer-tools/gitlab.mdx | 2 +- .../docs/pages/navigation/site-level-settings.mdx | 2 +- .../preview-publish/preview-changes-locally.mdx | 4 ++-- .../pages/preview-publish/publishing-your-docs.mdx | 2 +- fern/products/docs/pages/seo/configuring-slugs.mdx | 2 +- fern/products/docs/pages/seo/redirects.mdx | 2 +- 24 files changed, 39 insertions(+), 36 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index 68ff603aad..9f01a26744 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -752,7 +752,7 @@ redirects: - source: /learn/api/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-api-reference/cli-reference/commands - destination: /learn/cli-api-reference/cli-reference/sdk-commands + destination: /learn/cli-api-reference/cli-reference/general-commands # /learn/cli-reference/* (legacy) - source: /learn/cli-reference/cli-overview @@ -762,7 +762,7 @@ redirects: - source: /learn/cli-reference/get-started destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-reference/commands - destination: /learn/cli-api-reference/cli-reference/sdk-commands + destination: /learn/cli-api-reference/cli-reference/general-commands - source: /learn/cli-reference/options destination: /learn/cli-api-reference/cli-reference/options - source: /learn/cli-reference/changelog/:slug* diff --git a/fern/products/api-def/ferndef/export-openapi.mdx b/fern/products/api-def/ferndef/export-openapi.mdx index 53393f8c46..7f45a4bb5e 100644 --- a/fern/products/api-def/ferndef/export-openapi.mdx +++ b/fern/products/api-def/ferndef/export-openapi.mdx @@ -7,7 +7,7 @@ noindex: true -To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/learn/cli-api-reference/cli-reference/sdk-commands#fern-export). +To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/learn/cli-api-reference/cli-reference/general-commands#fern-export). The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec. diff --git a/fern/products/api-def/openapi/automation.mdx b/fern/products/api-def/openapi/automation.mdx index 905f8500ca..e34a333a80 100644 --- a/fern/products/api-def/openapi/automation.mdx +++ b/fern/products/api-def/openapi/automation.mdx @@ -20,7 +20,7 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y ``` - Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. + Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. ```yml title=".github/workflows/sync-openapi.yml" name: Sync OpenAPI Specs # can be customized diff --git a/fern/products/api-def/openapi/extensions/examples.mdx b/fern/products/api-def/openapi/extensions/examples.mdx index c7830883e0..ed7f338bdf 100644 --- a/fern/products/api-def/openapi/extensions/examples.mdx +++ b/fern/products/api-def/openapi/extensions/examples.mdx @@ -116,4 +116,4 @@ paths: ## Convert to native OpenAPI examples -To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-enrich) to convert them into native OpenAPI example fields. +To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-enrich) to convert them into native OpenAPI example fields. diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 7e802e08aa..2e912282b5 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -65,7 +65,7 @@ For [OpenAPI](/learn/api-definitions/openapi/overview), [AsyncAPI](/learn/api-de There are four common ways to manage your API definition: - **Commit directly into your Fern repository (recommended).** Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don't maintain the definition elsewhere. -- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). +- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification). - **Host at a public URL.** Serve the definition from a publicly accessible endpoint and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference. - **Reference from a remote git repository.** Point [`openapi`](/learn/sdks/reference/generators-yml#openapi), [`asyncapi`](/learn/sdks/reference/generators-yml#asyncapi), or proto [`root`](/learn/sdks/reference/generators-yml#root) to a file in an external git repository using the `git` sub-object. The CLI shallow-clones the repository at generation time, using your local git credential configuration. This is useful when spec files live in a private repo you don't want to copy. diff --git a/fern/products/cli-api-reference/cli-api-reference.yml b/fern/products/cli-api-reference/cli-api-reference.yml index db4a067f37..176ae6e0b5 100644 --- a/fern/products/cli-api-reference/cli-api-reference.yml +++ b/fern/products/cli-api-reference/cli-api-reference.yml @@ -7,13 +7,13 @@ navigation: - page: Global options path: ./pages/global-options.mdx slug: options - - page: General Commands + - page: General commands path: ./pages/general-commands.mdx slug: general-commands - - page: Docs Commands + - page: Docs commands path: ./pages/docs-commands.mdx slug: docs-commands - - page: SDK Commands + - page: SDK commands path: ./pages/sdk-commands.mdx slug: sdk-commands - page: CLI version policy diff --git a/fern/products/cli-api-reference/pages/cli-get-started.mdx b/fern/products/cli-api-reference/pages/cli-get-started.mdx index 04c31072a9..3dd301e15d 100644 --- a/fern/products/cli-api-reference/pages/cli-get-started.mdx +++ b/fern/products/cli-api-reference/pages/cli-get-started.mdx @@ -83,7 +83,7 @@ npm fern generate The Fern CLI manages both documentation and SDK workflows. Below is a brief overview of the common commands for each. All commands support [global options](/learn/cli-api-reference/cli-reference/options) like `--log-level` for debugging. -For complete CLI documentation, see the [command reference](/learn/cli-api-reference/cli-reference/sdk-commands). +The [general](/learn/cli-api-reference/cli-reference/general-commands), [docs](/learn/cli-api-reference/cli-reference/docs-commands), and [SDK](/learn/cli-api-reference/cli-reference/sdk-commands) command references document every command and flag in full. diff --git a/fern/products/cli-api-reference/pages/cli-version-policy.mdx b/fern/products/cli-api-reference/pages/cli-version-policy.mdx index 2c8dad6bf5..96f30857bd 100644 --- a/fern/products/cli-api-reference/pages/cli-version-policy.mdx +++ b/fern/products/cli-api-reference/pages/cli-version-policy.mdx @@ -42,7 +42,7 @@ A policy never blocks a command. When the CLI can't read your organization's bou ## Set the policy -[`fern org set cli-version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-set-cli-version) writes the bounds. It requires an organization admin and an authenticated session from [`fern login`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-login). The organization is read from `fern.config.json`; pass `--org` to target a different one. +[`fern org set cli-version`](/learn/cli-api-reference/cli-reference/general-commands#fern-org-set-cli-version) writes the bounds. It requires an organization admin and an authenticated session from [`fern login`](/learn/cli-api-reference/cli-reference/general-commands#fern-login). The organization is read from `fern.config.json`; pass `--org` to target a different one. ```bash # Pin an exact version @@ -69,11 +69,11 @@ fern org get fern org get --json ``` -[`fern org get`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-get) prints the policy in one line — `Fern CLI must be between 5.40.0 and 5.50.0`, or the equivalent for a minimum, maximum, or exact pin — and reports when no policy is set. `--json` returns the raw `cliVersionMin` and `cliVersionMax` fields instead. +[`fern org get`](/learn/cli-api-reference/cli-reference/general-commands#fern-org-get) prints the policy in one line — `Fern CLI must be between 5.40.0 and 5.50.0`, or the equivalent for a minimum, maximum, or exact pin — and reports when no policy is set. `--json` returns the raw `cliVersionMin` and `cliVersionMax` fields instead. ## Clear the policy -[`fern org unset cli-version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-org-unset-cli-version) clears the bounds, and like setting them it requires an organization admin. +[`fern org unset cli-version`](/learn/cli-api-reference/cli-reference/general-commands#fern-org-unset-cli-version) clears the bounds, and like setting them it requires an organization admin. ```bash # Remove both bounds @@ -88,7 +88,7 @@ fern org unset cli-version --max ## Interaction with `fern upgrade` -A policy changes the version that runs, not the version on disk, so a project stays out of range until it's upgraded. [`fern upgrade`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-upgrade) brings the file itself into range: it applies the bounds to the upgrade target before writing it. +A policy changes the version that runs, not the version on disk, so a project stays out of range until it's upgraded. [`fern upgrade`](/learn/cli-api-reference/cli-reference/general-commands#fern-upgrade) brings the file itself into range: it applies the bounds to the upgrade target before writing it. | Command | Policy | Version written | |---|---|---| @@ -96,8 +96,8 @@ A policy changes the version that runs, not the version on disk, so a project st | `fern upgrade` | Pinned to `5.45.0` | `5.45.0` | | `fern upgrade --version 5.35.0` | Minimum `5.40.0` | `5.40.0` | -A plain `fern upgrade` resolves to the latest release, which is never below the minimum, so only the maximum changes what it writes. The minimum applies when you request an older version with [`--version`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-upgrade): the bounds win over the version you asked for. +A plain `fern upgrade` resolves to the latest release, which is never below the minimum, so only the maximum changes what it writes. The minimum applies when you request an older version with [`--version`](/learn/cli-api-reference/cli-reference/general-commands#fern-upgrade): the bounds win over the version you asked for. -[`fern downgrade`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-downgrade) is the exception: it writes whatever version you pass, including one below the minimum. The policy then overrides that pin the same way it overrides any other out-of-range pin, so the project's commands keep running the minimum. +[`fern downgrade`](/learn/cli-api-reference/cli-reference/general-commands#fern-downgrade) is the exception: it writes whatever version you pass, including one below the minimum. The policy then overrides that pin the same way it overrides any other out-of-range pin, so the project's commands keep running the minimum. Running a newer CLI doesn't apply the migrations that `fern upgrade` performs. Raising the minimum across a major version therefore still requires each project to run `fern upgrade`. diff --git a/fern/products/cli-api-reference/pages/docs-commands.mdx b/fern/products/cli-api-reference/pages/docs-commands.mdx index c5a49f1b71..b07ca99822 100644 --- a/fern/products/cli-api-reference/pages/docs-commands.mdx +++ b/fern/products/cli-api-reference/pages/docs-commands.mdx @@ -1,11 +1,11 @@ --- -title: 'Docs Commands' +title: 'Docs commands' description: 'Complete reference for all Fern CLI commands for generating and managing documentation.' subtitle: 'Learn about the Fern CLI docs commands.' hideOnThisPage: true --- -## Documentation commands +These commands build, preview, and publish a Fern documentation site, and validate the MDX pages and links behind it. Creating a docs project with `fern init --docs` and validating `docs.yml` with `fern check` are [general commands](/learn/cli-api-reference/cli-reference/general-commands), and [SDK commands](/learn/cli-api-reference/cli-reference/sdk-commands) generate client libraries from the same API definition your docs render. Each docs command accepts the [global options](/learn/cli-api-reference/cli-reference/options). | Command | Description | |---------|-------------| diff --git a/fern/products/cli-api-reference/pages/general-commands.mdx b/fern/products/cli-api-reference/pages/general-commands.mdx index c99229bca8..27fabe6170 100644 --- a/fern/products/cli-api-reference/pages/general-commands.mdx +++ b/fern/products/cli-api-reference/pages/general-commands.mdx @@ -1,10 +1,12 @@ --- -title: 'General Commands' +title: 'General commands' description: 'Complete reference for general Fern CLI commands.' subtitle: 'Commands that apply across SDKs and docs.' hideOnThisPage: true --- +These commands apply to every Fern project, whether it publishes [docs](/learn/cli-api-reference/cli-reference/docs-commands), [SDKs](/learn/cli-api-reference/cli-reference/sdk-commands), or both. They create and validate a project, authenticate the CLI, update your API definition, and set the CLI version your organization runs. Each one accepts the [global options](/learn/cli-api-reference/cli-reference/options). + | Command | Description | |---------|-------------| | [`fern init`](#fern-init) | Create new Fern project from OpenAPI spec or scratch | @@ -13,6 +15,7 @@ hideOnThisPage: true | [`fern downgrade`](#fern-downgrade) | Move the Fern CLI version in `fern.config.json` back to an older version | | [`fern login`](#fern-login) | Login to Fern CLI via GitHub, Google, Postman, or enterprise SSO | | [`fern logout`](#fern-logout) | Log out of the Fern CLI | +| [`fern token`](#fern-token) | Generate an organization-scoped API key for CI/CD | | [`fern export`](#fern-export) | Export an OpenAPI spec for your API | | [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec | | [`fern api enrich`](#fern-api-enrich) | Merge `x-fern-examples` from an overrides file into native OpenAPI examples | @@ -489,4 +492,4 @@ hideOnThisPage: true ``` - \ No newline at end of file + diff --git a/fern/products/cli-api-reference/pages/sdk-commands.mdx b/fern/products/cli-api-reference/pages/sdk-commands.mdx index 843448008a..0660f09d1a 100644 --- a/fern/products/cli-api-reference/pages/sdk-commands.mdx +++ b/fern/products/cli-api-reference/pages/sdk-commands.mdx @@ -1,11 +1,11 @@ --- -title: 'SDK Commands' +title: 'SDK commands' description: 'Complete reference for all Fern CLI commands for generating SDKs.' subtitle: 'Learn about the Fern CLI SDK commands.' hideOnThisPage: true --- -## SDK generation commands +These commands generate SDKs from your API definition, keep generators up to date, and manage the custom code [Fern Replay](/learn/sdks/overview/custom-code#replay) carries across regenerations. Creating a project with `fern init` and validating the API definition with `fern check` are [general commands](/learn/cli-api-reference/cli-reference/general-commands), and [docs commands](/learn/cli-api-reference/cli-reference/docs-commands) publish the API reference that documents the SDKs you generate. Each SDK command accepts the [global options](/learn/cli-api-reference/cli-reference/options). | Command | Description | |---------|-------------| diff --git a/fern/products/docs/pages/ai/ai-examples.mdx b/fern/products/docs/pages/ai/ai-examples.mdx index 36b9b3d530..2170e836b5 100644 --- a/fern/products/docs/pages/ai/ai-examples.mdx +++ b/fern/products/docs/pages/ai/ai-examples.mdx @@ -44,7 +44,7 @@ AI-generated examples are written to `ai_examples_override.yml`. Edit this file ``` -To make AI-generated examples portable to non-Fern OpenAPI tools, use [`fern api enrich`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-enrich) to merge them into native OpenAPI example fields. +To make AI-generated examples portable to non-Fern OpenAPI tools, use [`fern api enrich`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-enrich) to merge them into native OpenAPI example fields. ## Disable AI-generated examples diff --git a/fern/products/docs/pages/ai/markdown.mdx b/fern/products/docs/pages/ai/markdown.mdx index b22cbbe1f1..23ce75f3ac 100644 --- a/fern/products/docs/pages/ai/markdown.mdx +++ b/fern/products/docs/pages/ai/markdown.mdx @@ -63,7 +63,7 @@ When an agent requests a `.md` URL that matches no page and no redirect, the res ## Accessing protected docs -On sites with [authentication](/learn/docs/authentication/overview) enabled, agents must include a JWT on every Markdown request — whether for an individual page or `llms.txt`. Exchange your [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) for a [JWT](/learn/docs/fern-api-reference/get-jwt): +On sites with [authentication](/learn/docs/authentication/overview) enabled, agents must include a JWT on every Markdown request — whether for an individual page or `llms.txt`. Exchange your [Fern API key](/learn/cli-api-reference/cli-reference/general-commands#fern-token) for a [JWT](/learn/docs/fern-api-reference/get-jwt): ```bash Get a JWT curl https://docs.example.com/api/fern-docs/get-jwt \ diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 8f38705ba3..d2db8415ec 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -46,7 +46,7 @@ Exchange your credentials for a JWT. The endpoint depends on how your site authe - Exchange a [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) for a JWT via the [get-jwt endpoint](/learn/docs/fern-api-reference/get-jwt): + Exchange a [Fern API key](/learn/cli-api-reference/cli-reference/general-commands#fern-token) for a JWT via the [get-jwt endpoint](/learn/docs/fern-api-reference/get-jwt): ```bash curl https://docs.example.com/api/fern-docs/get-jwt \ diff --git a/fern/products/docs/pages/ai/writer.mdx b/fern/products/docs/pages/ai/writer.mdx index 5c3e4de353..199ccb8869 100644 --- a/fern/products/docs/pages/ai/writer.mdx +++ b/fern/products/docs/pages/ai/writer.mdx @@ -83,7 +83,7 @@ Otherwise, install it on your docs repo (requires GitHub org admin access). The [Get a unique Slack installation link](/learn/docs/scribe-api/fern-writer-api/get-fern-writer-install-link) for your organization. Provide: -- Your [Fern API key](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) +- Your [Fern API key](/learn/cli-api-reference/cli-reference/general-commands#fern-token) - The GitHub repository in `owner/repo` format (e.g., `acme/docs`) You can alternatively use this cURL request: diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 570fb9c931..ae5fb5a17a 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -84,5 +84,5 @@ navigation: - URL of your GraphQL API endpoint. Fern performs [introspection](https://graphql.org/learn/introspection/) against this endpoint to fetch the schema. When set, [running `fern api update`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-api-update) updates the local schema from this endpoint. + URL of your GraphQL API endpoint. Fern performs [introspection](https://graphql.org/learn/introspection/) against this endpoint to fetch the schema. When set, [running `fern api update`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-update) updates the local schema from this endpoint. diff --git a/fern/products/docs/pages/ask-fern/api-get-started.mdx b/fern/products/docs/pages/ask-fern/api-get-started.mdx index a34592fd54..b065279524 100644 --- a/fern/products/docs/pages/ask-fern/api-get-started.mdx +++ b/fern/products/docs/pages/ask-fern/api-get-started.mdx @@ -14,4 +14,4 @@ The Fern AI API allows you to manage your Ask Fern configuration using Fern's pu ## Authentication -Fern API requests require an API key for authentication. Use the CLI command [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) to generate an API key. API keys don't expire. +Fern API requests require an API key for authentication. Use the CLI command [`fern token`](/learn/cli-api-reference/cli-reference/general-commands#fern-token) to generate an API key. API keys don't expire. diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index 67724e1b27..d8d2e327c3 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -74,7 +74,7 @@ In [versioned docs](/learn/docs/configuration/versions), the same path lands on ### Validating links -Fern provides two ways to catch broken links. The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the [Fern Dashboard](https://dashboard.buildwithfern.com/). +Fern provides two ways to catch broken links. The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. To check links on a published site, use [`fern docs link check`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-link-check) or the [Fern Dashboard](https://dashboard.buildwithfern.com/). | | `fern check` broken-links rule | `fern docs link check` | |---|---|---| diff --git a/fern/products/docs/pages/developer-tools/gitlab.mdx b/fern/products/docs/pages/developer-tools/gitlab.mdx index 6069ee5a72..a6cefe4334 100644 --- a/fern/products/docs/pages/developer-tools/gitlab.mdx +++ b/fern/products/docs/pages/developer-tools/gitlab.mdx @@ -17,7 +17,7 @@ Use GitLab CI/CD to automatically generate preview links on merge requests, publ ### Generate a Fern API key -Run [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) in your terminal from the directory containing your `fern` folder. This generates an organization-scoped API key that authenticates the Fern CLI in CI/CD. +Run [`fern token`](/learn/cli-api-reference/cli-reference/general-commands#fern-token) in your terminal from the directory containing your `fern` folder. This generates an organization-scoped API key that authenticates the Fern CLI in CI/CD. ```bash fern token diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index c333dc6c28..7869127e8d 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1286,7 +1286,7 @@ ai-examples: ## Check configuration -Configure the severity of validation rules run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking). +Configure the severity of validation rules run by [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking). ```yaml docs.yml check: diff --git a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx index 2ef696ef23..61ba4d5f26 100644 --- a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx +++ b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx @@ -76,7 +76,7 @@ If the same command also prints `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts - For [internal pages](/learn/docs/writing-content/markdown-basics#link-format), use the published URL path from your `docs.yml` config (for example, `/learn/docs/configuration/navigation`) — not a relative path or on-disk file path. - For [images and other assets](/learn/docs/writing-content/markdown-media), use a path relative to the Markdown file. -Broken internal links fail by default. Use [`fern generate --docs --no-strict-broken-links`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-generate) to downgrade the failure to a warning while you fix them. +Broken internal links fail by default. Use [`fern generate --docs --no-strict-broken-links`](/learn/cli-api-reference/cli-reference/docs-commands#fern-generate---docs) to downgrade the failure to a warning while you fix them. #### `Invalid URL: /some/path` @@ -135,7 +135,7 @@ You can use a GitHub Actions workflow to automatically generate a preview URL wh If you set up your site using the [guided UI](https://dashboard.buildwithfern.com/get-started) or [CLI quickstart](/learn/docs/getting-started/quickstart), this workflow is automatically included in your repository. Otherwise, add it manually using the examples below. -These workflows require a `FERN_TOKEN` [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). If you used the guided workflow, this secret is added automatically. Otherwise, generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token) in your terminal, then add it in your repository's **Settings > Secrets and variables > Actions** with the name `FERN_TOKEN`. +These workflows require a `FERN_TOKEN` [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). If you used the guided workflow, this secret is added automatically. Otherwise, generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/general-commands#fern-token) in your terminal, then add it in your repository's **Settings > Secrets and variables > Actions** with the name `FERN_TOKEN`. You may need to re-run preview builds for any PRs that were opened before you configured the `FERN_TOKEN`. diff --git a/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx b/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx index e1a9089246..0fe41c9d06 100644 --- a/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx +++ b/fern/products/docs/pages/preview-publish/publishing-your-docs.mdx @@ -197,7 +197,7 @@ To unpublish a docs site, navigate to the **Settings** page for your site in the ### No token found. Please set the FERN_TOKEN environment variable or run `fern login`. -`fern generate --docs` needs an authenticated session to publish. Run [`fern login`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-login) locally, or set `FERN_TOKEN` in your shell or CI environment. Generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-token). +`fern generate --docs` needs an authenticated session to publish. Run [`fern login`](/learn/cli-api-reference/cli-reference/general-commands#fern-login) locally, or set `FERN_TOKEN` in your shell or CI environment. Generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/general-commands#fern-token). ### OpenAPI spec validation failed with N errors. Fix the errors above before generating docs. diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 602584f1ae..e5033afaad 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -68,7 +68,7 @@ Set the `slug` property in `docs.yml` or in a page's frontmatter to customize th - **Product and version prefixes**: preserved in both cases. - Changing a slug updates the page's URL. Run [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check) to detect pages that moved without a [redirect](/learn/docs/seo/redirects#catching-missing-redirects), so existing links don't break. + Changing a slug updates the page's URL. Run [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) to detect pages that moved without a [redirect](/learn/docs/seo/redirects#catching-missing-redirects), so existing links don't break. ### Modify a tab slug diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index fd6a74b001..dfc05e091b 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -115,7 +115,7 @@ Overriding the default versioning behavior manually can lead to unexpected redir ## Catching missing redirects -The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/sdk-commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. Tune its severity in `docs.yml`. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. Tune its severity in `docs.yml`. ## Common errors