Cloudflare 重构 CLI：用 TypeScript Schema 驱动下一代 Wrangler

Cloudflare 正在重新构建 Wrangler CLI，目标是让它成为覆盖所有 Cloudflare 产品的统一命令行工具。近期发布的 Technical Preview（npx cf）展示了未来 Wrangler 的雏形，同时发布了 Local Explorer 本地开发调试工具。

背景：碎片化的 CLI 现状

Cloudflare 拥有超过 100 个产品和近 3000 个 HTTP API 操作，但很多产品在 Wrangler CLI 中没有对应的命令。随着 AI Agent 越来越多地通过 CLI 与平台交互，CLI 的一致性变得至关重要。目前更新 CLI、Workers Bindings、wrangler.jsonc 配置、Agent Skills 和文档仍然是手动流程，容易出错且难以扩展。

新方案：TypeScript 驱动的代码生成管道

Cloudflare 引入了一套新的 TypeScript schema，用于定义 API 范围、CLI 命令和参数，以及生成任何接口所需的上下文。这套 schema 本质上是一组 TypeScript 类型，配合约定、linting 和安全护栏来确保一致性。由于它是自定义格式，可以轻松适配当前或未来的任何接口需求，同时仍能生成 OpenAPI schema。

这一层的建设是核心——先造好机器，再开始构建 CLI 和其他接口。

CLI 一致性工程

Agent 期望 CLI 是一致的。如果一个命令用 <command> info 获取资源信息，另一个却用 <command> get，Agent 就会调用不存在的命令。在数百上千人的工程组织中，靠人工审查来保证一致性几乎不可能。

Cloudflare 的做法是在 schema 层实施规则和护栏：

• 统一用 get，不用 info
• 统一用 --force，不用 --skip-confirmations
• 统一用 --json，不搞 --format，且所有命令都支持

Wrangler CLI 的特殊之处在于它同时操作本地模拟资源和远程资源（如 D1 数据库、R2 存储桶、KV 命名空间）。一致的默认值和清晰的输出信号（标明命令操作的是远程还是本地资源），能确保 Agent 获得明确的指引。

Local Explorer：本地资源可视化

Local Explorer 是此次发布的一个新功能，在 Wrangler 和 Cloudflare Vite 插件中以开放测试版形式提供。

当你在本地开发 Worker 时，Local Explorer 可以让你检查模拟资源的状态，包括 KV、R2、D1、Durable Objects 和 Workflows。你通过 Cloudflare API 和 Dashboard 能做的所有操作，在本地也能完全通过相同的底层 API 结构完成。

使用方法：用 Wrangler 或 Vite 插件运行应用后，按 e 键即可打开 Local Explorer，查看 Worker 当前绑定了哪些资源以及其中存储的数据。

这个工具对 Agent 开发特别有用——你可以随时检查 Agent 对数据做了什么操作，验证 schema、填充测试数据，或者直接 DROP TABLE 重新开始。

Cloudflare 的目标是提供一个仅修改本地数据的 Cloudflare API 镜像，使本地资源通过与你远程使用的相同 API 可用。当你在新版 CLI 中传递 --local 标志时，命令只是向这个本地 API 镜像发出请求，而不是远程 API。

该 API 现在可通过 /cdn-cgi/explorer/api 在任何由 Wrangler 或 Vite 插件驱动的应用上访问。将你的 Agent 指向这个地址，它就能找到 OpenAPI 规范来管理你的本地资源。

安装与实测

# 全局安装
npm install -g cf

# 或直接运行
npx cf

当前版本为 v0.0.5，仍处于早期 Technical Preview 阶段。实测可用的命令：

关键特性实测

该 CLI 在设计上对 AI Agent 非常友好，实测验证了以下几个特性：

默认 JSON 输出：所有命令输出默认即为 JSON 格式，Agent 可直接解析，无需额外指定输出格式。

--dry-run 安全模式：支持在执行创建/更新/删除操作前预览效果，避免误操作。Agent 可在执行敏感操作前先 dry-run 确认。

agent-context 内置指南：运行 cf agent-context 会输出完整的 Agent 使用指南，包括认证方式、输出格式、安全规范、上下文解析规则和错误处理建议。Agent 可以读取这段输出来了解如何正确使用 CLI。

schema 自省能力：cf schema --list 可列出所有可用的 API schema，cf schema <命令> 可查看特定命令的完整请求参数、路径参数和响应结构。Agent 可以在运行时动态查询 API 结构，无需硬编码。

上下文解析优先级：CLI flags > 环境变量（CLOUDFLARE_API_TOKEN 等）> 项目配置（.cfrc）> 用户配置（~/.config/cf/config.json），Agent 无需在每个命令中重复指定账号和 Zone ID。

实测输出示例

# 查看版本
$ cf --version
# Cloudflare CLI v0.0.5

# 检查登录状态
$ cf auth whoami
# {"authenticated": false, "error": "Not logged in"}

# 查询 DNS 记录列表的 API schema
$ cf schema dns records list
# 返回操作 ID、HTTP 方法、路径参数、查询参数等完整信息

参与反馈

目前的 Technical Preview 仅提供 Cloudflare 一小部分产品的命令。Cloudflare 团队已经在测试支持全部 Cloudflare API 的版本，每个产品的命令都会经过仔细审查和调优，确保输出对人和 Agent 都友好。

未来几个月，他们将会把新系统与 Wrangler 现有功能整合，形成最终的下一代 Wrangler CLI。

Cloudflare 希望听到开发者的声音——你最希望哪个操作用一行 CLI 命令就能完成？你希望 wrangler.jsonc 能配置什么（比如 DNS 记录或 Cache Rules）？你的 Agent 在哪里卡住了，你希望 CLI 提供什么命令给 Agent 使用？

欢迎加入 Cloudflare Developers Discord 提供反馈。