Changelog

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.

5.26.4

(fix): Fix missing-redirects causing fern check to exit with code 1 even when the rule is configured at warn. Rule initialization failures now honor the configured severity (warn emits a warning, error emits an error) instead of always being reported as fatal. The missing-redirects rule also degrades to a warning when the local docs navigation fails to resolve, captures the underlying failAndThrow message so the warning explains why (e.g. Folder not found: ...) instead of [object Object], and non-Error throws are formatted readably across the validator.

5.26.3

(fix): Fix fern docs dev grabbing the local fern token for authentication when loading a global theme

5.26.2

(fix): Fix commit author attribution for GitHub Enterprise: API-created commits now use the Fern bot identity instead of the PAT-owning user, matching the git CLI behavior of Fern 3.x generators.

(fix): Authenticate Venus calls during local Docker generation (fern generate --local) by silently picking up an existing FERN_TOKEN env var or saved login token, matching the remote generation path. Previously, useLocalDocker skipped the auth flow entirely, leaving Venus calls (e.g. GET /organizations/{org_id}) unauthenticated.

5.26.1

(fix): Forward --verify through the remote (Fiddle) generation path. Previously the CLI-level --verify flag only worked for local generation; on remote runs the value was silently dropped before reaching CreateJobRequestV2.verify. The flag now plumbs through runRemoteGenerationForAPIWorkspace → runRemoteGenerationForGenerator → createAndStartJob and is set on the Fiddle job request, enabling the generator-cli pipeline’s VerificationStep against the language-specific validator on opted-in runs.

5.26.0

(feat): Add fern docs link check command to validate links on live documentation sites. Supports text, JSON, and CSV output formats via --output flag. Use --url <url> to specify which docs site to check, or auto-detect from docs.yml.

(feat): Add progress bars matching fern docs dev style for fern docs link check. Broken links show status codes, blocked links show diagnostic details, and error messages include actionable context.

(feat): The fern docs link check command now resolves broken link sources to local file paths when the server provides sourcePageIds and a Fern workspace is available.

5.25.0

(feat): Register the new fernapi/fern-cli generator in the CLI configuration.

5.24.2

(fix): Fix fern config migrate producing wrong file path references in the generated fern.yml. Paths from generators.yml (relative to the fern/ directory) are now correctly re-rooted to be relative to the project root where fern.yml is created. This also fixes the docs $ref pointer to use ./fern/docs.yml instead of ./docs.yml.

5.24.1

(chore): Propagate Fern docs: strings into generated JSON Schemas so editor hovers work for schemas served from schema.buildwithfern.dev.

5.24.0

(internal): Plumb verify, verifyRunner, and verifyValidatorVersion flags through GenerationRunner.RunArgs so the seed runner can invoke PostGenerationPipeline with VerificationStep and exercise the same validator-container code path that fern generate --local --verify uses. No customer-facing CLI behavior change — the flags are opt-in and used only by the seed test runner today.

5.23.6

(fix): Fix fern docs dev hot reload not working for .mdx file changes. The backend now updates the docs definition before notifying the browser to refresh, and the reload handler properly recovers from errors instead of silently blocking all future reloads.

5.23.5

(fix): Fix SDK generation crashing with fatal: <sha> is not a valid object when the prior fern-bot PR was squash-merged and its branch deleted. The stale fern-generation-base tag update is now skipped with a warning; the SDK PR still opens.

5.23.4

(fix): Fix allOf composition so inline elements with real constraints (e.g. pattern, minLength) produce a properly merged type instead of being silently dropped. Also refactored the allOf shortcircuit logic to use a metadata allowlist, which is safer against new OpenAPI fields.

(fix): Fix example generation for allOf compositions to merge base schema fields into property overrides. When an allOf override specifies only items without type: array, the base schema’s type is now correctly inherited, producing properly typed examples instead of null.