Skip to content

CLOUDFLARE 2026-09-28

Read original ↗

Introducing Forge: the open source pipeline for generating SDKs, CLIs, docs, and more

Summary

Cloudflare open-sourced Forge (Apache 2.0), a pluggable code-generation pipeline that produces SDKs, CLIs, docs, and other API "surfaces" from an interface spec. Forge is the generation engine behind the cf CLI and will over the coming months power Cloudflare's API documentation, SDKs (TypeScript, Rust, Python, Go, PHP, Terraform), and more. The motivating problem is scale + coordination: Cloudflare's API spans 3,500+ operations across hundreds of services and repositories written in Rust, Go, TypeScript, and Python, and hosted code-generation vendors couldn't keep up — one team's API change would silently break the shared generation pipeline, discovered only at release time. Forge's core bet is to run generation in CI on every pull request, across hundreds of repos — linting each change and emitting preview builds of the CLI, docs, and SDKs with just that change highlighted that a developer can install and test before merge. This is the Workers Previews premise ("a full preview for every change") applied to SDK/CLI/docs generation at fleet scale. Two further design pillars: transformers can generate anything (not just language SDKs — Cap'n Web, TanStack Query bindings, Zod/Valibot schemas, MCP servers, whole dashboards) and transformers can be chained (one output feeds another — e.g. cf's TypeScript SDK is generated from OpenAPI, and the CLI + Cap'n Web specs are generated from that TypeScript SDK), with the user — not the tool vendor — controlling the chaining. Forge also underpins Cloudflare's forthcoming API-versioning-without-breaking-clients approach: ship new major API versions while continuing to emit artifacts old clients can keep using.

Key takeaways

  1. The API outgrew hosted generators — the problem is coordination at scale, not codegen itself. 3,500+ operations, hundreds of services, four backend languages (Rust, Go, TS, Python). Cloudflare tried several hosted generation products, relied on some in production, and "none of them solved this problem for us, and some have shut down entirely." The concrete failure loop: "One team would merge a change that inadvertently would break the generation pipeline, another team would discover this at release time." Coordinating changes between teams and external vendors was the bottleneck. (Source: §"Our API outgrew our generators")

  2. Preview build for every pull request, across hundreds of repos. Forge "runs in CI, on each team's API repos, just like our AI code reviewer and test pipelines. It lints every change, and then generates preview builds of the CLI, docs, and SDKs with just your changes highlighted that you can install to test." Explicitly framed as the same premise as Workers Previews — a full preview build for every change — "but applied to SDK generation at scale, including when the API surface is distributed across hundreds of services and repositories." Purpose: detect problems in CI before they cause issues downstream. (Source: §"Our API outgrew our generators")

  3. Transformers can generate anything, including Cap'n Web. Forge can take an OpenAPI spec and generate Cap'n Web directly, opening the door to generating Workers bindings — since "bindings in the Workers runtime are implemented as Workers that expose RPC methods." Not Cap'n Web-specific: the same mechanism can emit TanStack Query bindings, Zod or Valibot schemas, MCP servers, "or anything else that makes it easier to consume your API" — "always up to date, always validated against your real API." (Source: §"Forge transformers can generate anything")

  4. Transformers can be chained — generate outputs from other outputs — and the USER controls the chain. Forge supports OpenAPI as input today and is designed to allow AsyncAPI, GraphQL, Cap'n Proto, Protobuf as future input formats. Its differentiator vs existing generators is user-controlled chaining: "This is common in other generators where the CLI and Terraform targets are produced from the Go SDK. But what's missing, and what Forge provides, is a way for the user to control this chaining system themselves." Cloudflare's own chain: OpenAPI → TypeScript SDK → (cf CLI + Cap'n Web specs). They needed this because cf is written in TypeScript, "which other SDK generators don't generally chain from for CLIs." (Source: §"Forge transformers can be chained")

  5. CLIs are different from SDKs — they carry hand-written, non-API-backed behavior that must flow into docs too. CLIs "often introduce local-only behaviors that wouldn't make sense in an SDK" — e.g. cf dev and cf build, which are added on top of the generated output and call TypeScript APIs from other packages like Vite. This forces a hard question Cloudflare couldn't find an existing tool to answer: "If you're generating your CLI and your docs purely from your OpenAPI spec, how do you feed those handwritten commands back into your docs, so they can be documented alongside the rest?" Forge is being built to merge hand-written surface into generated docs. (Source: §"Forge transformers can be chained")

  6. Forge is the foundation for API versioning without breaking clients. Cloudflare's v4 API has been the single major version for 10 years; by SemVer definitions they've shipped many breaking-worthy changes without bumping, and several operations carry stale internal v2/beta tags. A big-bang v5 "would leave a lot of our customers behind." With Forge releasing artifacts along the way, they're "working on an API versioning approach that allows us to release new major API versions without breaking old clients or SDKs." Terraform is called out for "extra special care" given upgrade rigor. (Source: §"Change your API without breaking users")

  7. Open source under Apache 2.0 — critical tooling should not require a SaaS. "You should own your SDKs, CLIs, and docs." Forge is deployable and runnable for free, including privately with custom modifications, under a permissive license. The stated motivation: agents are now customers of every product, so CLIs / SDKs / MCP servers / docs are "table stakes for every product," and everyone should be able to generate the surfaces agents need without a hosted vendor. (Source: §"Critical tools should be open to all")

Systems / concepts / patterns extracted

  • Forge (NEW) — the open-source pluggable generation pipeline.
  • cf CLI — first shipped Forge consumer; generated via the OpenAPI → TS SDK → CLI chain.
  • Cap'n Web — a Forge output target generable directly from OpenAPI; path to generating Workers bindings.
  • Terraform provider — a planned Forge output; flagged for careful migration.
  • MCP servers, TanStack Query bindings, Zod/Valibot schemas — cited as arbitrary transformer outputs.
  • AI code reviewer — cited as the sibling CI pipeline Forge runs alongside.
  • Concepts: concepts/schema-evolution / concepts/backward-compatibility (major-version API evolution without breaking old clients/SDKs), concepts/machine-readable-documentation (generated, always-validated docs incl. hand-written commands), concepts/local-remote-parity (generated surfaces validated against the real API).
  • Reusable ideas recorded as tags/prose (NOT minted as pages):
  • preview-build-per-change / preview-per-PR for generated artifacts — Workers-Previews premise applied to SDK/CLI/docs generation; a preview build with just-your-changes highlighted on every PR across hundreds of repos. Single distinct source here; recorded on this page and on systems/cloudflare-forge / systems/cf-cli, not minted.
  • transformer-chaining / output-from-output codegen with user-controlled chains — one generated artifact is the input to the next (OpenAPI → TS SDK → CLI + Cap'n Web). Recorded as prose on systems/cloudflare-forge; not a standalone pattern page (single source).
  • spec-as-single-source-of-truth for all API surfaces — folded into the existing cf CLI "one TypeScript schema" framing (typescript-as-codegen-source / schema-driven-interface-generation), enriched, not re-minted.

Operational numbers

Metric Value Source
Cloudflare API operations 3,500+ §"Our API outgrew our generators"
Backend service languages Rust, Go, TypeScript, Python §"Our API outgrew our generators"
Repos / services generation spans "hundreds" §"Our API outgrew our generators"
Age of single v4 major API version 10 years §"Change your API without breaking users"
License Apache 2.0 §"Critical tools should be open to all"
Planned SDK targets TypeScript, Rust, Python, Go, PHP, Terraform §"Change your API without breaking users"
Input formats: today / planned OpenAPI / AsyncAPI, GraphQL, Cap'n Proto, Protobuf §"Forge transformers can be chained"

Caveats

  • Early in its life. Forge "is early in its life, but already generates the output required for the cf CLI." The docs / SDK / broader-target coverage is roadmap ("over the next few months"), not shipped state — treat the multi-target, multi-input-format, chained-docs vision as design intent.
  • No throughput / latency numbers. The post gives API-surface scale (3,500+ ops, hundreds of repos) but no CI build-time, preview-generation latency, or per-PR volume figures.
  • API-versioning approach is stated intent, not a shipped mechanism. "Working on an API versioning approach" — no concrete versioning scheme (URL, header, artifact-channel) is disclosed. See patterns/staged-rollout / concepts/backward-compatibility for the general shape this will have to take.
  • Only OpenAPI input is real today. AsyncAPI / GraphQL / Cap'n Proto / Protobuf are design-for, not available. Cap'n Web / MCP / TanStack / Zod outputs beyond the cf CLI are illustrative of the extensibility model rather than confirmed shipped generators.

Source

Last updated · 766 distilled / 2,225 read