Changelog

5.17.1

(fix): Fix publish to respect FERN_FDR_ORIGIN environment variable override.

5.17.0

(internal): Attach fern_run_id and github_run_id as PostHog properties on every CLI event so PostHog dashboards can correlate analytics with the FERN_RUN_ID set by the GitHub Actions wrappers and the matching Sentry tags.

5.16.1

(fix): fern check now accepts changelog navigation entries whose URL has any allowlisted segment (e.g. whats-new, release-notes, changelog), not just the trailing one. This means a changelog page like /whats-new/product-updates no longer raises a false-positive error about RSS / Atom / JSON feeds 404ing — the docs server matches the same loosened rule when serving feeds.

5.16.0

(feat): cli-v2: fern check now prints rich, Rust-style errors for MDX/Markdown parse failures. Each error includes a stable error code (e.g. E0301), a --> path:line:col location, two surrounding source lines with a caret pointer, and an inline fix: suggestion when one is available.

(feat): cli-v2: add interactive AI-assisted fixes for MDX/Markdown parse errors. fern check now offers to apply a fix when run interactively — using a deterministic string-replace when the parser’s fix: hint matches the file, and falling back to a configured AI provider otherwise. Provider is selected via fern config ai set-provider <anthropic|openai|bedrock> and credentials via fern config ai set-key <key> (Bedrock uses the standard AWS environment). Prompts are skipped automatically when running inside a Claude Code session (CLAUDECODE=1).

(feat): cli-v2: when fern check finds multiple MDX errors, prompt once for a batch action (“apply all”, “review each”, “skip all”) instead of prompting once per error.

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.

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.13.0

(internal): Remove the fern write-translation command. Translation directories under translations/<lang>/ are still respected when loading docs, but the CLI no longer ships a command to generate them.

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.

(chore): Bump @fern-fern/fiddle-sdk catalog pin to 1.0.2. The new SDK exposes replay on CreateJobRequestV2, so the field added to createJobV3 in PR #15690 stops being silently stripped by the SDK serializer and now actually reaches Fiddle. With this in place, customers setting replay.enabled: false in generators.yml get the legacy GitHub push/PR path on cloud generation. Final activation step for FER-10343.

(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.

(chore): Make @boundaryml/baml an optional dependency. The CLI no longer requires BAML to be installed unless AI features (auto-versioning, sdk-diff) are used. Users who invoke AI features without BAML installed will see a clear error message with installation instructions.

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.2

(chore): Bump axios to ^1.15.1 to address CVE-2026-42037 (CRLF injection in multipart/form-data body via unsanitized blob.type). Narrow the type of the response Content-Type header in init’s OpenAPI URL loader to satisfy axios 1.16’s stricter AxiosResponseHeaders typings.

5.10.1

(chore): Plumb the top-level replay block from generators.yml through the remote generation runner to the createJobV3 wire boundary, so cloud generation can honor replay.enabled once Fiddle exposes the field.

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.

(internal): Capture PostHog telemetry for replay outcomes during fern generate. Emits a single replay event with action: pipeline_run carrying patch counts, conflict reason buckets, generator/repo context, and pipeline duration. Honors FERN_DISABLE_TELEMETRY (v1) and FERN_TELEMETRY_DISABLED / ~/.fernrc (v2). Adds a structured [replay] info log line and per-bucket conflict debug counts so the same data is visible in stdout. No file paths, patch IDs, or commit messages are emitted; the SDK repo URI is hashed (sha256, 16-char prefix). Wires the previously-no-op v2 TaskContextAdapter.instrumentPostHogEvent so v2-driven generates feed the same event stream as v1. Distinguishes genuine replay crashes from flow: first-generation to keep success-rate dashboards honest.

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.2

(chore): Remove break from the supported changelog types so the automated release flow cannot produce a major version bump. Major releases must now be made by editing the relevant versions.yml directly so the breaking change is explicitly acknowledged in review. Validation rejects type: break in unreleased/.

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

(chore): Reduce verbose logging during OpenAPI parsing by moving individual example validation warnings to debug level. The per-API example validation summary is still shown at warn level.

(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

(internal): cli-v2: introduce a shared stdin/stdout abstraction so commands uniformly honor the Unix - marker on I/O flags (stdin for inputs, stdout for outputs), with a “- used at most once per command” guard and a JSON-or-path input helper that parses inline JSON first and falls back to a file read.

(internal): cli-v2: fern api compile --output - now uses the shared stdio helper (behavior unchanged — still streams IR JSON to stdout).

(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.1

(chore): Bump @fern-api/fdr-sdk to 1.2.0-1d73d2e141 to pick up the first-class Alpha, Preview, and Legacy availability values published from the fdr@1.2.0 tag.

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.1.0

(internal): Introduce a simpler TtyAwareLogger local to cli-v2. The new logger drops legacy behaviours that cli-v2 did not use (omitOnTTY, FERN_SPINNER_STATUS, dynamic finish reassignment, ora dependency) and exposes a minimal register / write / takeOverTerminal / finish surface against a generic Paintable interface. Box-frame rendering moves into TaskGroup. The legacy TtyAwareLogger in @fern-api/cli-logger is untouched.

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.108.0

(internal): Validate staged changelog entries in changes/<version>/*.yml (not just versions.yml) and trigger the workflow on PRs that touch those staged files. Catches unescaped {} / <> / #{} patterns at PR time instead of after autorelease promotes the entry to versions.yml on main.

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

(chore): Improved translation logging by moving verbose page array output to debug level and formatting as a concise count instead of raw JSON array.

(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.100.0

(internal): Suppress Sentry false positives caused by user- and environment-provoked errors being misclassified as InternalError:

• Add a generic ErrnoException classifier in resolveErrorCode that maps filesystem errors (ENOENT, EACCES, ENOSPC, EPIPE, …) to EnvironmentError and network errors (ENOTFOUND, ECONNREFUSED, ETIMEDOUT, …) to NetworkError, both of which are non-reportable.
• Register an error listener on process.stdout/process.stderr in TtyAwareLogger to swallow EPIPE at the source before it reaches Sentry’s uncaught-exception integration (triggered when piping CLI output into head, jq, etc.).
• Make ContainerError non-reportable and replace the aggregate CliError({ ContainerError }) throw in the sdk generate and docs publish commands with TaskAbortSignal to prevent double-reporting individual task failures.
• Fix JsonError, ParseError, and GeneratorError class names surviving esbuild minification by explicitly setting this.name in their constructors, so isSchemaValidationError can reliably classify them as ParseError.
• Wrap yaml.load in loadOpenAPI to translate YAMLException into a user-readable CliError({ ParseError }) with file, line, and column context.
• Wrap swagger2openapi conversion failures in convertOpenAPIV2ToV3 as CliError({ ParseError }).
• Pass explicit ValidationError / NetworkError codes in createOrganizationIfDoesNotExist instead of letting them fall through to InternalError.
• Reclassify “Generator not found” in the upgrade message helper from InternalError to ConfigError (user’s generators.yml references an image not in FDR).
• Use TaskAbortSignal in rerunFernCliAtVersion failure path instead of reporting a spurious InternalError.

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.