Changelog

5.41.0

(feat): Add X-Request-Id header to all CLI v2 HTTP requests for request tracing and debugging.

5.40.1

(fix): Add /openapi.json, /openapi.yaml, /openapi.yml, /asyncapi.json, /asyncapi.yaml, and /asyncapi.yml to the link validator whitelist, and add pattern-based matching for dynamic API spec paths like /openapi/<id>.json so fern check no longer reports false broken-link errors for these special doc pages.

5.40.0

(feat): Add hidden fern docs theme delete --name <theme name> CLI command to delete a named theme from an org. Includes a confirmation prompt (skippable with --yes).

5.39.0

(feat): Add a settings.search object to docs.yml with two new options:

• prioritize-current-product: boosts search results from the current product/version via Algolia optionalFilters without excluding results from other products/versions.
• default-filter-by-current-product: auto-selects the current product as a facet filter so only results from the current product are shown by default.

settings.default-search-filters is preserved as an alias for settings.search.default-filter-by-current-product for backwards compatibility.

5.38.2

(fix): Honor operation-level x-fern-streaming.resumable on SSE endpoints whose streaming is auto-detected from a text/event-stream response. Previously, setting resumable: true without an explicit format was silently dropped and the endpoint generated as non-resumable.

5.38.1

(fix): Fix fern check --broken-links (and fern docs broken-links) silently skipping broken links inside API Reference description fields. Links in endpoint, type, property, path-parameter, and other docs / description fields are now validated against the rest of the docs navigation.

5.38.0

(feat): Add interactive login prompt to fern login. When no active Auth0 session exists, the CLI now presents a menu to choose a login provider (GitHub, Google, Postman, or SSO). Selecting SSO prompts for an email address and routes directly to the organization’s identity provider. If an active session already exists, authentication completes silently as before.

5.37.12

(fix): Fix false “page was moved” warnings in fern check and fern docs dev when the same file is referenced across multiple doc versions. The missing-redirects rule now tracks all slugs per pageId instead of only the last one encountered.

5.37.11

(fix): Bump the fern init fallback version for fern-typescript-sdk / fern-typescript-node-sdk from 2.3.2 to 3.71.2. The 2.3.2 container runs Node 20 and started failing yarn install after mute-stream@4.0.0 (Node ≥22) was published as a transitive dep. The fallback only triggers when FDR cannot resolve a compatible generator version, so released CLIs are unaffected — this restores a working default for fresh fern init and for dev builds.

5.37.10

(fix): Fix x-fern-audiences filtering dropping transitively-referenced named types when an outer schema reaches its descendants through a chain of $refs. Audience filtering now walks the full type-dependency closure instead of a single level, so deeply nested object types are preserved in the docs IR and no longer render as any in the docs site.

5.37.9

(chore): Add cli-generator to the allowed PR title scopes enforced by the lint-pr-title workflow.

5.37.8

(fix): Fix FDR generator version lookup for Ruby SDK to use the correct registry ID (ruby-sdk-v2) instead of the stale legacy ID (ruby-sdk). This ensures fern generator upgrade and IR version resolution return the actual latest Ruby SDK generator version.

5.37.7

(fix): Bump @fern-api/fdr-sdk to 1.2.16 to fix crash when generating examples for endpoints that reference types excluded by audience filtering.

5.37.6

(chore): Centralize theme-eligible docs.yml field definitions in @fern-api/configuration so theme export, upload, and global theme stitching reference the same source of truth.

5.37.5

(fix): Handle docs preview file watcher startup failures as local environment errors.

5.37.4

(chore): Revert the @fern-api/venus-api-sdk bump from 5.35.5 (0.22.34 -> 4.0.0).

5.37.3

(fix): Report invalid Mintlify navigation configuration as a user-facing config error during docs import.

5.37.2

(fix): Report absolute OpenAPI spec paths as user-facing workspace configuration errors.

(fix): Include settings in theme export so that fern docs theme export captures the settings configuration from docs.yml.

5.37.1

(fix): Prevent login from reporting missing browser opener tools as internal errors. Upgrade open to v11 so spawn failures reject the returned promise, and handle them inline in redirect, device-code, and logout flows.

5.37.0

(feat): Propagate the per-spec namespace: declared in generators.yml through the raw specs manifest mounted into generator containers. RawSpecsManifestEntry now carries an optional namespace field populated from OpenAPISpec.namespace (also OpenRPCSpec.namespace and GraphQLSpec.namespace). Enables generators that opt into generatorWantsSpecs to route multi-spec workspaces by their workspace-declared namespace instead of inferring one from the runner-assigned filename. The new fernapi/fern-cli generator uses this to emit .spec_under("<ns>", ...) in the generated main.rs when the user namespaces their specs.

(fix): Skip copying zero-byte snippet.json stubs from the workspace temp dir into the user’s generated output. The local workspace runner pre-creates an empty snippet.json file and bind-mounts it into the generator container so the generator can optionally write per-endpoint code samples. Generators that emit a CLI binary (or any output without call-site snippets) leave it empty — copying the empty stub left a confusing 0-byte snippet.json in the user’s output. The runner now stat’s the tmp file and skips the copy when it’s empty.

5.36.1

(fix): Fix OpenAPI 3.1 importer to inherit path-level parameters (headers, query params) into operations. Previously, only operation-level parameters were processed, causing path-level headers like Accept: application/json to be silently dropped.

5.36.0

(feat): cli-v2: add fern update command for installing and switching between CLI versions. Includes fern update, fern update list, fern update use <version>, fern update --check, and fern update --to <version>. Versions are stored in ~/.cache/fern/v1/versions/<version>/ and tracked in ~/.fernrc under the new cli field. A new opt-in --versions flag was added to fern cache clear; the default behavior continues to leave installed CLI binaries untouched. fern cache show now reports the versions cache alongside IR and logs. After every successful command, the CLI runs a rate-limited (24-hour) probe against the release feed and prints a one-line nag when a newer version is available.

5.35.5

(chore): Bump @fern-api/venus-api-sdk from 0.22.34 to 4.0.0, fixing a bug where Authorization headers were silently dropped on org GET endpoints.

5.35.4

(fix): Report response property references on non-object responses as definition reference errors instead of internal errors.

5.35.3

(fix): Treat missing type declarations during IR generation as user reference errors instead of reportable resolver failures.

5.35.2

(fix): Bump @fern-api/generator-cli to 0.9.35, which disables minimatch negation on .fernignore patterns so a stray !pattern no longer silently inverts the match and discards generator output.

5.35.1

(fix): Fix OpenAPI respect-readonly-schemas so that endpoint response types correctly reference the Read variant (e.g. WebhookRead instead of Webhook) when the same schema is used in both request and response contexts.

5.35.0

(feat): Add support for user-provided examples in GraphQL specs. Users can now specify an examples field in their GraphQL spec configuration pointing to a YAML file containing named examples (with query, variables, and response) for each operation.

5.34.0

(feat): Support uploading raw API spec files alongside the IR during remote generation. The CLI now sends the IR as the “ir” multipart field (with backward-compatible “file” support on Fiddle) and optionally appends a “specs” tar.gz archive containing pre-processed spec files for generators that need them.

5.33.7

(fix): Handle null OpenAPI overlay files as validation failures instead of allowing them to throw internal TypeErrors during workspace loading.

5.33.6

(fix): Classify missing readme endpoint references in generators.yml as configuration errors.

5.33.5

(fix): Classify unresolved Fern response type references as validation errors instead of reportable internal resolution failures.

5.33.4

(fix): Add retry logic to the air-gap health check so that transient network failures (DNS blips, momentary connectivity drops) no longer cause false air-gapped mode detection. The check now retries up to 3 times with backoff before declaring air-gapped mode. Also logs the underlying error cause for better debugging.

5.33.3

(fix): Swallow stdout/stderr EPIPE events in the cli-v2 terminal logger so Unix pipe closures do not report false-positive internal errors.

(fix): Stop reporting invalid endpoint server references during IR-to-FDR conversion to Sentry.

(fix): Prevent CLI telemetry from failing when the user’s home directory cannot store Fern’s analytics ID.

5.33.2

(fix): Validate that the Fern instance url and every custom-domain share the same basepath when basepath-aware mode is enabled (multi-source: true or the deprecated experimental.basepath-aware: true). Previously the check was skipped when the custom domain was at the root, allowing publishes that would 404 after DNS cutover.

(fix): Strip any https:// or http:// prefix from custom-domain entries in docs.yml before they’re sent to FDR or used for basepath comparisons. Including the protocol in the configured value could interfere with basepath resolution during DNS cutover.

5.33.1

(chore): Publish a JSON Schema for fern.yml so YAML language servers can provide autocomplete and validation in IDEs. Regenerate via fern schema --output (or pnpm fern-yml:jsonschema in the monorepo).

5.33.0

(feat): Mount pre-processed API specs into generator Docker containers. Specs are bundled, overrides merged, overlays applied, x-fern-ignore operations filtered, and x-fern-audiences respected before outputting compact JSON to generators. Add hidden resolve-specs command.

5.32.1

(chore): Bump @fern-api/generator-cli to 0.9.33 (picks up @fern-api/replay 0.16.1).

5.32.0

(feat): Support structured x-fern-base-path with per-parameter declarations and defaults. The OpenAPI extension now accepts an object form with path and parameters, where each parameter can specify a type, docs, and default.

5.31.0

(feat): Populate hasWebSocketInTree on IR Package/Subpackage types. When a subpackage (or any of its nested children) contains a WebSocket channel, this field is set to true, enabling generators to wire WebSocket-only namespaces into the root client.

5.30.4

(fix): Fix the OpenAPI importer silently dropping the request body of an operation that combines x-fern-streaming (with stream-condition) with a oneOf or anyOf request body schema. Endpoints whose body is a plain object (properties/allOf) are unaffected.

5.30.3

(fix): Fix a TypeError: Cannot read properties of undefined (reading 'startsWith') crash in the OpenAPI parser when an operation’s x-fern-streaming extension sets only resumable: true (or otherwise omits both format and stream-condition). The parser now returns undefined for that operation instead of crashing.

5.30.2

(fix): Fix fern docs link check disconnecting on large sites by using batched requests instead of a single long-lived SSE connection. Pages are now scraped in batches of ~200 and links checked in batches of ~500, with automatic retries on connection failures.

5.30.1

(fix): Fix broken link checker to validate links in pages referenced via folder entries in docs.yml navigation.

5.30.0

(feat): Add commit-and-release mode support for self-hosted GitHub configuration. Users can now set mode: commit-and-release in their self-hosted github: block to commit directly to a branch and create a GitHub release.

5.29.0

(feat): Port the hidden fern docs md command group from CLI v1 to CLI v2. Adds fern docs md generate (beta library documentation generation from source code) and fern docs md check (MDX-only syntax validation) with CLI v2’s consistent UI.

5.28.3

(chore): Add bin/ property to CLI v2 Cache class for shared tool binaries (buf, protoc-gen-openapi) at ~/.fern/bin/, enabling both CLI v1 and CLI v2 to share the same binary download location.

5.28.2

(chore): Generator-cli now delegates divergent-merge recovery (squash-merge of a regen PR, force-push past a generation, lost-then-found generations) entirely to @fern-api/replay’s derived scan boundary. Customers no longer hit the pre-replay precondition gauntlet that occasionally got stuck on stale fern-generation-base tag pointers. Replay still writes the tag for backward compatibility with older bundled generator-cli versions.

5.28.1

(fix): Fix global theme merge to deep-merge object fields instead of overwriting them. Local-only sub-fields (e.g. logo.right-text, logo.height) are now preserved when the global theme defines sibling fields on the same object.

5.28.0

(feat): Consolidate all CLI v2 cache directories into ~/.fern/. Docs preview bundles are now managed under ~/.fern/v1/docs-preview/ and discoverable via fern cache show and fern cache clear --docs-preview. The fern cache clear command never touches the user’s auth token or telemetry ID.

5.27.8

(fix): Fix property-level x-fern-audiences filtering breaking error type resolution when enableUniqueErrorsPerEndpoint is true. Types referenced via object properties (e.g. ErrorResponse → ErrorResponseError) are now correctly included during audience filtering, resolving “Failed to find ErrorResponseError” errors in fern check and fern docs dev.

5.27.7

(chore): Bump @fern-api/generator-cli to 0.9.30, which includes @fern-api/replay 0.15.2 with a fix for customer commits on merged regen branches surviving replay detection.

5.27.6

(chore): Bump @fern-api/generator-cli to 0.9.29, which includes @fern-api/replay 0.15.1 with fixes for fallback patch anchoring, composite-patch survival, and FileOwnership divergence.

5.27.5

(fix): Wrap replaceImagePathsAndUrls calls in DocsDefinitionResolver and previewDocs with try/catch boundaries that convert MDX parse failures to CliError(ParseError), preventing user-authored MDX syntax errors from reaching Sentry as false-positive InternalErrors.

5.27.4

(fix): Classify service and environment errors at their boundary call sites: mark exhausted 429 retries as NetworkError, pass error objects through failWithoutThrowing in remote generation so CliError codes propagate, and reclassify docs preview server startup failures as EnvironmentError instead of InternalError.

5.27.3

(fix): Wrap yaml.load calls in getVersionedNavigationConfiguration and getNavigationConfiguration with try/catch boundaries that convert YAML parse failures to CliError(ParseError), preventing user-authored YAML syntax errors in version and product config files from reaching Sentry as false-positive InternalErrors.

5.27.2

(fix): Suppress Sentry false positives for ENOTEMPTY/ENOMEM syscalls, undici fetch-failed TypeErrors, and errno codes on error.cause.

5.27.1

(fix): Report escaped fatal CLI errors through telemetry in packaged production runs.

5.27.0

(internal): Enrich CLI telemetry with automation-mode context (config repo, branch, commit sha, PR number, trigger, and GitHub run details) on every PostHog event and Sentry error report. Add the three-leg failure flow (Sentry + PostHog + automation event API) so automation-run failures surface end-to-end.