为整个 Cloudflare 构建一个 CLI
原文:Building a CLI for all of Cloudflare Source: https://blog.cloudflare.com/cf-cli-local-explorer/
2026-04-13
Cloudflare 拥有庞大的 API 表面。我们有超过 100 款产品,以及近 3,000 个 HTTP API 操作。
agents 越来越成为我们 API 的主要用户。开发者带着自己的 coding agent 在 Cloudflare 上构建并部署 应用、agents 和 平台,配置自己的账户,查询我们的 API 来获取分析数据和日志。
我们希望让每一款 Cloudflare 产品都能以 agents 需要的所有方式被访问。例如,我们现在用一个 Code Mode MCP server 把 Cloudflare 的整个 API 暴露出来,只用 不到 1,000 个 token。但还有大量表面需要覆盖:CLI 命令、Workers Bindings —— 包括用于本地开发和测试的 API、跨多种语言的 SDK、配置文件、Terraform、开发者文档、API 文档 和 OpenAPI schema、Agent Skills。
如今我们有许多产品并未在所有这些接口上都可用。CLI 尤其如此 —— 也就是 Wrangler。许多 Cloudflare 产品在 Wrangler 里没有任何 CLI 命令。而 agents 偏偏喜欢 CLI。
所以我们一直在重新构建 Wrangler CLI,让它成为整个 Cloudflare 的 CLI。它为所有 Cloudflare 产品提供命令,并允许你用 infrastructure-as-code 一起配置它们。
今天我们以技术预览的形式分享下一代 Wrangler 的早期版本。它非常早期,但只有公开开发我们才能得到最好的反馈。
你今天就可以通过运行 npx cf 试用技术预览版。或者通过运行 npm install -g cf 全局安装。
目前 cf 只为 Cloudflare 一小部分产品提供命令。我们已经在内部测试覆盖整个 Cloudflare API 表面的版本 —— 我们将有意识地审查并打磨每一款产品的命令,让其输出对 agents 和人都更顺手。需要明确的是,这个技术预览只是未来 Wrangler CLI 的一小部分。在接下来的几个月里,我们会把它和你已熟知喜爱的 Wrangler 部分结合起来。
为了让它能跟上 Cloudflare 产品开发的快节奏,我们必须创建一个新系统,用来生成命令、配置、binding API 等等。
从第一性原理重新思考 schema 与代码生成管道
我们已经基于 Cloudflare API 的 OpenAPI schema 生成了 Cloudflare API SDK、Terraform provider 和 Code Mode MCP server。但更新我们的 CLI、Workers Bindings、wrangler.jsonc 配置、Agent Skills、dashboard 和文档仍然是手动过程。这本来就容易出错,需要太多来回沟通,也无法扩展到在下一代 CLI 中支持完整的 Cloudflare API。
要做到这一点,我们需要的远不止 OpenAPI schema 所能表达的东西。OpenAPI schema 描述的是 REST API,但我们有交互式 CLI 命令,涉及多个动作,这些动作既包含本地开发又包含 API 请求;我们有以 RPC API 形式表达的 Workers bindings;还有把这一切串起来的 Agent Skills 和文档。
我们在 Cloudflare 写大量 TypeScript。它是软件工程的通用语言。我们不断发现,用 TypeScript 表达 API 就是更好用 —— 就像我们在 Cap n’ Web、Code Mode 以及 Workers 平台内置的 RPC 系统 中所做的那样。
于是我们引入了一种新的 TypeScript schema,可以定义 API 的完整范畴、CLI 命令和参数,以及生成任何接口所需的上下文。这种 schema 格式“只是“一组带约定、lint 和护栏的 TypeScript 类型,以确保一致性。但因为它是我们自己的格式,可以轻松适应今天或将来需要的任何接口,同时 仍然 能够生成 OpenAPI schema:
到目前为止,我们的大部分精力都集中在这一层 —— 构建我们需要的“机器“,这样我们现在才可以开始构建多年来一直想要的 CLI 和其他接口。这让我们可以更大胆地畅想能在 Cloudflare 范围内标准化什么、为 agents 优化什么 —— 尤其是在 CLI 的 context engineering 方面。
Agents 与 CLI —— 一致性和 context engineering
Agents 期望 CLI 是一致的。如果一个命令用 <command> info 这种语法获取资源信息,而另一个用 <command> get,agent 就会期望其中一种,然后对另一种调用一个不存在的命令。在一个有数百乃至数千人、产品众多的大型工程组织里,通过评审手动强制一致性就像瑞士奶酪一样千疮百孔。你可以在 CLI 层强制执行,但这样命名又会在 CLI、REST API 和 SDK 之间不一致,问题甚至变得更糟。
我们率先做的事之一,就是开始在 schema 层制定规则和护栏。永远是 get,绝不用 info。永远是 --force,绝不用 --skip-confirmations。永远是 --json,绝不用 --format,而且所有命令都要支持。
Wrangler CLI 也颇为独特 —— 它提供既可以处理本地模拟资源、又可以处理远程资源的命令和配置,比如 D1 数据库、R2 存储桶 和 KV 命名空间。这意味着一致的默认值更加重要。如果一个 agent 以为自己在修改远程数据库,但实际上是把记录加到了本地数据库,而开发者又在用 remote bindings 在本地针对远程数据库开发,他们的 agent 就无法理解为什么向本地开发服务器请求时新增的记录不显示出来。一致的默认值,加上能清晰指明命令应用于远程还是本地资源的输出,确保 agents 得到明确的指引。
Local Explorer —— 远程能做什么,现在本地也能做
今天我们还发布了 Local Explorer,这是 Wrangler 和 Cloudflare Vite 插件中以公开 beta 形式提供的新功能。
Local Explorer 让你在本地开发时审视你的 Worker 所使用的模拟资源,包括 KV、R2、D1、Durable Objects 和 Workflows。你通过 Cloudflare API 和 Dashboard 对这些产品所能做的事情,现在完全可以在本地做,底层使用同样的 API 结构。
多年来我们 押注于完全的本地开发 —— 不只是为了 Cloudflare Workers,而是为了整个平台。当你使用 D1 时,即便 D1 是托管的、serverless 的数据库产品,你也可以完全在本地通过 bindings 运行你的数据库并与之通信,无需任何额外配置或工具。通过 Miniflare —— 我们的本地开发平台模拟器 —— Workers 运行时在本地开发中提供与生产环境完全一样的 API,并使用本地 SQLite 数据库提供同样的功能。这让编写和运行测试变得简单快速,无需网络访问,可以离线工作。
但直到现在,要弄清楚本地存了哪些数据,还得自己反向工程,审视 .wrangler/state 目录的内容,或者安装第三方工具。
现在,每当你用 Wrangler CLI 或 Cloudflare Vite 插件运行应用时,系统都会提示你打开 local explorer(键盘快捷键 e)。这给你一个简单的本地界面,显示你的 Worker 当前挂载了哪些 bindings,以及它们里面存了什么数据。
当你用 Agents 构建时,Local Explorer 是理解 agent 在数据上做什么的好方式,让本地开发循环变得交互性更强。任何时候你需要验证 schema、灌一些测试记录,或者干脆从头开始 DROP TABLE,都可以求助 Local Explorer。
我们的目标是提供一个只修改本地数据的 Cloudflare API 镜像,这样你所有的本地资源都可以通过你远程使用的同一套 API 访问。当本地和远程的 API 形态匹配后,在即将发布的 CLI 版本里运行 CLI 命令并加上 --local 标志,命令就能正常工作。唯一的区别是命令请求的是这个 Cloudflare API 的本地镜像。
从今天起,这个 API 在任何由 Wrangler 或 Vite 插件驱动的应用上都可以通过 /cdn-cgi/explorer/api 访问。把你的 agent 指向这个地址,它就会找到一个 OpenAPI 规范,从而可以替你管理本地资源,只需和你的 agent 对话即可。
告诉我们你对一个 Cloudflare 全平台 CLI 的期待与梦想
机器已经造好了,现在是时候把今天 Wrangler 中最好的部分,与现在新成为可能的能力结合起来,让 Wrangler 成为使用整个 Cloudflare 的最佳 CLI。
你今天就可以通过运行 npx cf 试用技术预览版。或者通过运行 npm install -g cf 全局安装。
对于这个非常早期的版本,我们想听到你的反馈 —— 不只是关于这个技术预览今天能做什么,还包括你希望从一个面向 Cloudflare 整个平台的 CLI 中得到什么。告诉我们,什么事情你希望可以一行 CLI 命令搞定,而今天却需要在 dashboard 里点上几下;你希望在 wrangler.jsonc 中可以配置什么 —— 比如 DNS 记录或缓存规则;以及你的 agents 在哪里卡住了,你希望我们的 CLI 提供什么命令给 agent 用。
到 Cloudflare Developers Discord 告诉我们你最想我们先加进 CLI 的是什么,并敬请期待更多更新。
感谢 Emily Shen 在启动 Local Explorer 项目方面所做的宝贵贡献。