🌿 [Scheduled] Upgrade Fern CLI

[fern-api]

Upgrading from 4.92.0 to 5.15.3 - Changelog

5.15.3

• fix: Fix fern check to respect x-fern-ignore when validating duplicate SDK method names. Operations marked with x-fern-ignore: true are now excluded from the duplicate override check.

5.15.2

• fix: Fix dynamic IR upload and check endpoints to pass correct field names (version, snippetConfiguration) matching the FDR server contract, resolving 500 errors during SDK generation.

5.15.1

• fix: Source org_id on the replay PostHog event from fern.config.json (the project organization slug, like every other CLI flow), not from a Venus token lookup.

5.15.0

• feat: Bake replay initialization into fern generate. Repos with a prior [fern-generated]
  commit but no .fern/replay.lock now auto-bootstrap inline during the post-generation
  pipeline — eliminating the need to run fern replay init as a separate step.

5.14.1

• fix: Fix non-deterministic snippet output across runs for SDK generators that consume the
  dynamic IR (Java, PHP, Python v2, Go v2, Ruby v2, Swift, Rust). The dynamic IR now
  tags examples with isUserSpecified and emits deterministic example ids; affected
  generators select examples using the canonical "all user, else first autogenerated"
  rule, matching TS v1 / Python v1 behavior.

60 additional updates, see more




5.14.0

feat: Emit the replay PostHog event from cloud generation, with surface, org_id, duration_ms, and additional patch counters.

5.13.2

fix: Improve 429 rate-limit retry logic for remote generation: increase max retries
from 3 to 5, respect the server's retryAfter hint as a minimum delay, and widen
jitter (0.2 → 0.5) to reduce thundering-herd retries when many generators run
concurrently across multiple API groups.

5.13.1

fix: Fix dynamic IR upload URLs request passing empty apiId and irVersions parameters, which caused 500 errors from FDR during SDK generation.

5.12.0

feat: fern automations generate now automatically retries 429 Too Many Requests responses with
exponential backoff (2s → 120s, up to 3 attempts, jittered). Automation runs are unattended,
so transient rate limiting should not fail the run and ask a human to re-trigger with a flag.
Real outages still surface as failures after retries exhaust.

feat: Surface CLI errors and warnings as GitHub Actions annotations when running under GHA.

fern automations generate now emits a structured ::error:: workflow command for every
failed generator, anchored on the exact line in generators.yml so the annotation appears
inline on the file in the PR's Files-changed view, with the API / group / generator name
in the title and the failure reason in the body.

All other commands (e.g. fern generate, fern check) emit annotations from any
logger.error / logger.warn call, providing baseline coverage for failures that don't
flow through the per-generator collector. Status-only logs (omitOnTTY) are filtered out
so they don't burn through GitHub's per-step annotation cap.

5.11.0

feat: Forward the top-level replay block from generators.yml to Fiddle's
createJobV3 call so cloud generation honors replay.enabled: false and
skips the replay pipeline when a customer opts out. Activates once the
@fern-fern/fiddle-sdk catalog pin advances to a version that exposes
replay on CreateJobRequestV2 (schema landed in fern-api/fiddle#729).

fix: Fix fern check --api <name> failing when broken-links validation is enabled
and docs.yml references multiple APIs. The docs validator now always sees
the full set of API workspaces (so the valid-markdown-links rule can resolve
every API referenced from the docs navigation), while the --api filter is
still applied to API-level validation only.

5.10.3

fix: Apply per-locale navbar-links overlays in the default fern docs dev app
preview server (the legacy preview and production publish already did this,
so dev was the odd one out and showed English CTAs on /<lang>/ URLs).
Also matches translation overrides for skip-slug sibling tabs positionally
when slug-based matching can't disambiguate them — without this, only the
one tab whose slug retained its own segment got translated.

5.10.0

fix: Fix self-hosted GitHub clone failing with "Invalid username or token" when
the user's ${GITHUB_TOKEN} is an OAuth user token (gho_) or personal
access token (ghp_, github_pat_). The clone URL hardcoded the
x-access-token: username, which is the format reserved for GitHub App
installation tokens (ghs_). Now selects the format based on the token
prefix, so both auth modes work.

5.9.0

feat: Accept branch under github when mode is release in generators.yml. This
allows users to configure a non-default branch for release mode in preparation for
wiring the field through to the remote generation service.

5.8.1

fix: Add a valid-changelog-slug rule to fern check that errors when a changelog's
effective URL slug is not one of the values served as an RSS/Atom/JSON feed by
the docs platform (changelog, changelogs, release-notes, releasenotes,
whats-new, whatsnew). Severity defaults to error and can be overridden
via check.rules.valid-changelog-slug in docs.yml.

5.8.0

feat: Add support for a custom robots.txt file in docs.yml. Set agents.robots-txt to a relative
filepath and Fern will host the file at /robots.txt on your docs site, overriding the
auto-generated default.

fix: Show a clear, actionable error when the Fern GitHub App is not installed on
the target repository instead of the generic "Failed to create job" message.

5.7.10

fix: Fix the OpenAPI 3.1 -> IR converter to respect endpoint-level security: [] opt-outs when auth is configured in generators.yml. Previously, declaring an auth scheme at the workspace level would silently override every endpoint-level security field — including explicit empty-array opt-outs — so endpoints that intentionally opted out of auth (e.g. an OAuth token endpoint, or a public endpoint) ended up rendered in docs and SDKs as if they required the global auth scheme.

5.7.9

fix: fern docs dev now fails with a clear error when no docs.yml is present, instead of exiting silently.

fix: Fix section landing pages with skip-slug: true ignoring frontmatter slug declarations.
Sections now compute separate slugs for the overview page (honors frontmatter) and for
children (respects skip-slug), so both features work correctly together.

5.7.8

fix: Fix fern logout showing a "localhost refused to connect" error page by
starting a local server to serve a branded confirmation page, matching the login flow.
Also update both login and logout confirmation pages with new branded designs.

5.7.7

fix: Improve logging when APIs are skipped during docs generation. Skipped APIs
now log at error level (instead of warn) with the API name and a clear
reason. Repetitive per-endpoint frontmatter warnings are aggregated into
a single summary line per API.

5.7.6

fix: Fix docs preview server showing "ready" message when the server process
crashes on startup. The CLI now exits with a clear error message instead.

fix: On Windows, recover critical standalone node_modules packages (next,
react-dom, styled-jsx) when symlink resolution fails due to long .pnpm
directory names. The CLI now scans the .pnpm store and copies packages
directly as a fallback.

5.7.5

fix: Send customDomains when publishing docs translations so FDR mirrors the translated blob to every URL the docs are published to. Previously translations were only written under the canonical fern URL, so docs sites served from a custom domain with a basepath (e.g. buildwithfern.com/learn) 404'd on every localized page.

5.7.4

fix: Strip Windows drive letter prefixes from resolved image paths in docs preview
to prevent raw filesystem paths from leaking into rendered HTML on Windows.

5.7.3

fix: Fix image path resolution on Windows for fern docs dev and fern generate docs.
Path utilities (resolve, dirname, join) now normalize output to forward slashes,
preventing file ID lookup mismatches caused by mixed path separators on Windows.

5.7.2

fix: Allow BCP 47 locale tags (e.g. ja-JP, pt-BR, zh-Hans-CN) in the translations and languages fields of docs.yml. Previously these were rejected by the JSON-schema validator with must be one of [en, es, fr, ...].

5.7.1

fix: Preserve OpenAPI default values for array schemas across query parameters,
headers, request bodies, and response body properties so docs can render
"Defaults to ..." metadata for arrays.

5.7.0

feat: cli-v2: fern sdk generate --api - and fern sdk preview --api - now read the
OpenAPI/AsyncAPI spec from stdin (e.g. cat openapi.json | fern sdk generate --api - --org acme --target typescript --output ./sdk).

feat: cli-v2: fern api split --output - prints the generated overlay/overrides for
the matching spec to stdout as a preview, without modifying the workspace
(no git-HEAD restore, no fern.yml updates). Requires --api to select a single
spec.

5.6.1

fix: Fix translated docs pages failing to resolve shared snippets (<Markdown src="..."/> and <Code src="..."/>).
Snippet references are now resolved before registering translations, with locale-aware loading that prefers
translated snippets (e.g., translations/zh/snippets/foo.mdx) when available.

5.6.0

feat: Add fern automations upgrade command that wraps fern upgrade and
fern generator upgrade into a single invocation with structured JSON
output (--json). Designed for consumption by the fern-upgrade GitHub
Action.

fix: Replace brittle hardcoded changelog URL map in upgradeGenerator.ts with
a regex-based derivation that supports all current and future generators.

5.5.0

feat: Add alpha, beta, preview, and legacy as supported values for the
x-fern-availability OpenAPI extension and the availability field
in Fern Definitions. These flow through the IR to generators and docs.

feat: Use first-class FDR Availability values (Alpha, Preview, Legacy) when
converting IR to FDR, replacing the previous fallback mappings to Beta /
Deprecated. Bumps @fern-api/fdr-sdk to a release that includes the new
enum values.

5.4.3

fix: Fix OpenAPI endpoints that declare only a 204 No Content success response
being dropped during OpenAPI -> IR conversion. The user-defined 204 status
code is now preserved on the endpoint response so docs display it correctly
instead of falling back to a default 200.

5.4.2

fix: Fix broken-links false positives for absolute links on sites that configure a
basePath (e.g. https://docs.example.com/product). Page slugs are stored with
the basePath prepended (product/about), but authors commonly write site-relative
absolute links without it (/about, /v2/guide). The link validator now also
checks the basePath-prefixed form so both conventions resolve.

5.4.1

fix: Fix OpenAPI parsing crash when specs contain non-standard additionalProperties: "true" (string instead of boolean).
The parser was attempting to use the in operator on a string value, causing a Cannot use 'in' operator to search for 'type' in true error.

fix: Surface rule initialization errors in fern check instead of exiting silently.
Previously, when a validation rule (e.g. valid-markdown-links) failed to
initialize because its docs configuration could not be resolved — for
example, a navigation folder: entry pointing at a path that does not
exist — fern check would exit with code 1 and no visible error message.
Now the underlying failure (e.g. Folder not found: …) is reported as a
fatal violation on docs.yml.

5.4.0

feat: Make auth optional at the service level in Fern Definition files.
When omitted, auth is inherited from the root API-level auth scheme.
This allows users to only specify auth: false when they explicitly want to disable auth.

5.3.0

feat: Translation overlays can now override navbar links (CTAs) per locale. Set navbar-links:
inside translations/<locale>/docs.yml and the per-locale FDR upload will use those
instead of the docs-level navbar-links. Local icon files referenced from the overlay
are uploaded and resolved alongside the rest of the docs assets.

5.2.2

fix: Translated docs.yml overlays are now read directly from translations/<locale>/docs.yml,
so an extra nested fern/ folder is no longer required. The legacy
translations/<locale>/fern/docs.yml location continues to work as a fallback.

5.2.1

fix: Fix auth scheme descriptions being lost when using generators.yml auth-schemes.
When security schemes are overridden in generators.yml, Fern now preserves the
descriptions from the OpenAPI spec's components.securitySchemes instead of using
generic placeholder text.

5.2.0

feat: Add multi-source property to docs.yml instances configuration. When enabled, docs registration
uses a basepath-aware S3 key format, allowing multiple independent doc sites to be hosted under the
same custom domain with different basepaths. This replaces experimental.basepath-aware, which is now
deprecated but still supported. When multi-source: true, the CLI validates that the url and
custom-domain share the same basepath.

5.0.0

break: Remove og:background-image metadata key. Use og:dynamic:background-image instead,
which is consistent with other og:dynamic:* settings.

4.109.0

feat: cli-v2: Add support for GraphQL specs in fern.yml. Specs can now be declared
with a graphql key (plus optional name, origin, and overrides) and are
rendered in the docs pipeline. SDK generation targets that reference an API
containing a GraphQL spec emit a non-fatal warning and skip the GraphQL spec,
since GraphQL SDK generation is not supported.

4.107.3

fix: Fix fern generate --docs --preview hang when OpenAPI specs contain circular
$ref chains. The unbundled fallback document now has its circular references
replaced with opaque object schemas so downstream converters no longer
infinite-loop.

4.107.2

fix: Suppress additional Sentry false positives: EADDRINUSE port conflicts,
MDX/acorn parse errors from docs preview and publishing, version range
strings in generators.yml, missing fern project when using --id flag,
non-JSON fern.config.json, and absolute filepath in OpenAPI spec config.

4.107.1

fix: Make OpenAPI validation errors non-fatal during docs generation. Previously,
validation issues like "Self-referencing circular pointer" or parameter name
collisions would abort fern generate --docs entirely. The CLI now logs
warnings and skips the offending API workspace so the rest of the docs can
still be published. These validations remain errors in fern check.

4.107.0

feat: Add infer-discriminated-union-base-properties OpenAPI parser setting.
When enabled, the parser intersects the resolved (allOf-flattened) property
maps of every variant of a discriminated oneOf and lifts properties that
appear in all variants with structurally-equal schemas into the union's
common properties. SDKs (e.g. C#, Java, Go) that already support union base
properties can then expose those shared fields directly on the union type
without forcing callers to cast to a concrete variant. Defaults to false.

4.106.3

fix: Send gitattributesEntries to Fiddle on fern replay init so the
generated PR marks .fern/replay.lock as linguist-generated=true.
Previously the entries were written into a temp clone that was discarded
and never reached the server. Requires a matching Fiddle server change
to consume the new field.

4.106.2

fix: Translation no longer fails for an entire locale when a single MDX file has a parse error.
Invalid pages are skipped with a warning that includes the file path, and the base page is used as a fallback.

4.106.1

fix: Fix OpenAPI importer generating duplicate type names when an operation's
request body $refs a top-level components.schemas.X schema whose name
collides with the auto-generated request wrapper name. The wrapper is now
disambiguated by using "Body" instead of "Request" in the generated name.

4.106.0

feat: Add support for translating navigation labels (tabs, products, versions, sections, pages, announcements)
via YAML overlay files in translations/<lang>/fern/. The overlay files use the same format as
write-translation output and are deep-merged over the source navigation configuration.

4.105.0

fix: Fix branch creation during signed commit push in generator-cli. GitHub's
updateRef API returns 422 (not 404) when the target branch does not exist,
so the createRef fallback was unreachable.

feat: fern docs dev now exits with a hard error on Windows when long path support
is not enabled, instead of printing a warning.

4.104.0

feat: Support simplified string syntax for translations field in docs.yml.
You can now use translations: [en, ja, fr] instead of requiring
translations: [{lang: en}, {lang: ja}, {lang: fr}]. The verbose
object syntax remains supported for specifying default: true.

4.103.1

fix: Fix translation directory check to treat the first locale as the default when no explicit default: true is set, matching the behavior of the rest of the CLI.

4.103.0

feat: Support BCP 47 locale tags (e.g. ja-JP, pt-BR, zh-Hans-CN) in the
translations and languages fields of docs.yml. Previously only
two-letter language codes were accepted.

4.102.0

feat: Add validation to fern check / fern docs check that verifies all configured
translation locales have a corresponding directory under fern/translations/.
If a directory is missing, a clear error message is printed showing the expected
directory structure.

4.101.0

feat: Add websocket-oneof-display setting to docs.yml. When set to grouped,
WebSocket messages with oneOf bodies are rendered as a single parent entry
with nested variants instead of flattened separate entries (default: flat).

4.100.3

fix: Fix fern generate --docs --preview to register translations for preview URLs.
Previously, translation registration was skipped entirely in preview mode,
causing translated docs to not appear in preview deployments.

4.100.2

fix: Fix fern docs dev to serve translated page content when viewing localized pages.

4.100.1

fix: Fix fern automations generate step summary not displaying SDK versions.
Upgrade Fiddle SDK to consume the new actualVersion field from
FinishedTaskStatus, which Fiddle now returns for both AUTO and explicit
versioning modes. Falls back to log-regex parsing and locally-resolved
version for backward compatibility.

fix: Fix fern docs dev to serve translated page content when viewing localized pages.

4.99.0

feat: [Alpha] Add support for a translations block in docs.yml to configure multi-language documentation.
Each entry specifies a locale (lang) and optionally marks it as the default language.

fix: Include docs translation metadata in the docs definition published to FDR so generated fdr.json
advertises configured locales alongside uploaded translation files.

4.98.0

feat: Move docs theme commands (export, list, upload) from CLI v2 to CLI v1.
Commands are now available as fern docs theme export, fern docs theme list, and fern docs theme upload.
Uses DocsWorkspace for path resolution, v1 auth, and validates all file references before uploading.

4.97.0

feat: [Alpha] Add support for a translations block in docs.yml to configure multi-language documentation.
Each entry specifies a locale (lang) and optionally marks it as the default language.

fix: Include docs translation metadata in the docs definition published to FDR so generated fdr.json
advertises configured locales alongside uploaded translation files.

4.96.0

feat: Add optional baseProperties field to UndiscriminatedUnionTypeDeclaration in the IR schema.
Both the V3 importer and the legacy OpenAPI importer now extract sibling properties from
oneOf/anyOf schemas and populate baseProperties on undiscriminated unions.

4.95.0

feat: Add placeholder field to auth scheme configuration (basic, bearer, header) for controlling
example values in dynamic code snippets. The fallback chain is: explicit placeholder > generic placeholder.
Configurable via Fern definition YAML and OpenAPI extensions (x-fern-basic, x-fern-bearer, x-fern-header).

4.94.2

fix: Fix Python dynamic snippet generation to respect the use_typeddict_requests
configuration option. When enabled, dynamic snippets now generate dict literals
instead of Pydantic model constructors for object and discriminated union types.

4.94.1

fix: Fix global theme asset downloads preserving original filenames and extensions.
Previously, assets downloaded from S3 CAS URLs (whose pathname is a raw content
hash) were saved without a file extension, breaking downstream MIME type detection.
The CLI now reads the filename from the presigned URL's response-content-disposition
query parameter, falling back to the Content-Disposition response header, then
Content-Type, so files land on disk with their correct names (e.g. logo.svg).

4.94.0

feat: Add consumer-side support for the global-theme key in docs.yml. When a docs site
declares global-theme: <name>, the CLI fetches the named theme from Fern's cloud
registry and merges it into the docs configuration before building (theme values win
for branding fields). Works with fern generate --docs, fern generate --docs --preview,
and fern docs dev (dev mode requires FERN_TOKEN to be set).

4.93.0

feat: Expose claude-code under page-actions in docs.yml so docs sites can toggle the
"Connect to Claude Code" button (e.g. page-actions.options.claude-code: false or
page-actions.default: claude-code).

---

Requested by: Fern Dashboard (ddn-demo)

[github-actions]

🌿 Preview your docs: https://ddn-demo-preview-32474e22-5411-4d9e-8cf5-3944c6086383.docs.buildwithfern.com