Cloudflare cf CLI：面向 AI Agent 的统一 API 命令行工具

Cloudflare 推出面向 AI Agent 设计的命令行工具 cf,覆盖超过 3,000 个 API 操作。通过自然语言搜索、JSON 优先输出和 TypeScript 配置,cf 降低了 Agent 操作大型 API 时的上下文负担,将复杂的多工具流程统一到单一 CLI。

cf CLI 的核心特性

Cloudflare 的新工具 cf 将 API 覆盖范围从 Wrangler 的约 280 个操作扩展到整个 Cloudflare API 的 3,000+ 操作。核心设计理念:

统一 API 访问: Agent 通过单一工具执行所有 Cloudflare 操作
JSON 优先设计: "Agent 只需要 JSON,如果 Agent 是该工具的未来主要用户,JSON 就应该是默认格式" (官方原文)
自然语言搜索: Agent 无需手动解析 3,000 个路由即可发现命令
TypeScript 配置: 通过 cloudflare.config.ts 实现类型安全的编程式配置
Vite 集成: 提供现代开发服务器、热模块替换和优化构建

自然语言搜索: cf cli search

传统方式下,Agent 需要在上下文中加载完整 API 文档或遍历数千个端点。cf 的 search 命令允许 Agent 用自然语言查询,返回匹配操作的精选列表。

工作原理

搜索基于 API 描述和参数进行匹配,无需解析完整文档:

# Agent 查询示例
$ cf cli search "create worker"

Results:
  workers.script.upload        - Upload a Worker script
  workers.routes.create        - Create a Worker route
  workers.deployments.create   - Create a deployment

# 获取具体操作的详细信息
$ cf workers.script.upload --help

上下文节省

对比传统方式:

传统: Agent 在 prompt 中携带完整 API 参考 (数十万 token)
cf search: 按需查询,仅返回相关操作 (数百 token)

结构化参数: 表单 vs JSON 拼接

cf 使用结构化表单收集参数,而非要求 Agent 手动构造复杂 JSON。

传统方式的问题

# Agent 需要手动构造 JSON
$ curl -X POST https://api.cloudflare.com/workers/script \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "script": "...",
    "bindings": [{"type": "kv_namespace", "name": "CACHE", "namespace_id": "..."}],
    "compatibility_date": "2026-09-01"
  }'

# 然后用 jq 解析响应
$ ... | jq '.result.id'

cf 的改进

# 结构化参数验证
$ cf workers.script.upload \
  --name my-worker \
  --script @worker.js \
  --binding kv:CACHE=namespace-id \
  --compatibility-date 2026-09-01

# 默认输出 JSON,无需 jq
{
  "success": true,
  "result": {
    "id": "worker-abc123",
    "created_on": "2026-09-28T10:00:00Z"
  }
}

优势:

参数验证发生在客户端,减少无效 API 调用
类型提示通过 LSP 自动补全
无需重复使用 jq 过滤 unicode 表格

TypeScript 配置: cloudflare.config.ts

cf 支持通过 TypeScript 文件编程式配置,替代传统的 TOML/YAML。

完整示例

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    name: "example-worker",

    // 环境变量绑定
    env: {
      API_URL: bindings.text(
        mode === "production"
          ? "https://example.com"
          : "https://staging.example.com"
      ),

      // KV 命名空间
      CACHE: bindings.kv({
        id: `namespace-${mode}`
      }),

      // D1 数据库
      DB: bindings.d1({
        database_id: process.env.DB_ID
      }),
    },

    // 兼容性配置
    compatibility_date: "2026-09-01",
    compatibility_flags: ["nodejs_compat"],
  },

  // 开发服务器
  dev: {
    port: mode === "production" ? 8787 : 3000,
  },
}));

Agent 的优势

LSP 自动补全: Agent 可以通过编辑器协议获取可用选项,无需在 prompt 中列举所有配置项
类型安全: TypeScript 编译器捕获配置错误,Agent 无需反复试错
编程式逻辑: 支持环境工厂模式,减少重复配置

实际效果

根据 Cloudflare 披露,一个内部配置通过编程式环境工厂缩减了 40% (从 5,000+ 行减少)。

降低 Agent 上下文负担的三个机制

1. 精简 JSON 输出

对比人类可读表格 vs Agent 优化 JSON:

# 传统 CLI (人类友好)
┌─────────┬──────────────┬──────────┐
│ ID      │ Name         │ Status   │
├─────────┼──────────────┼──────────┤
│ abc123  │ my-worker    │ deployed │
│ def456  │ test-worker  │ draft    │
└─────────┴──────────────┴──────────┘

# cf (Agent 友好,默认格式)
[
  {"id": "abc123", "name": "my-worker", "status": "deployed"},
  {"id": "def456", "name": "test-worker", "status": "draft"}
]

Token 节省: 表格格式需要 Agent 解析 unicode 绘图字符,JSON 直接映射到数据结构。

2. LSP 驱动的自动补全

TypeScript 的 Language Server Protocol 提供实时类型提示:

// Agent 编辑 cloudflare.config.ts 时
env: {
  CACHE: bindings.kv({
    id: "...",  // ← LSP 提示: string (必填)
    preview_id?: string  // ← LSP 提示: 可选参数
  })
}

Agent 无需在 prompt 中携带完整 schema,通过 LSP 查询即可获取。

3. 内置 AGENTS.md 指导

cf 自动附加 Agent 专用指导文件到上下文:

# AGENTS.md 示例内容
## Common Patterns

- Use `cf cli search` to discover operations
- All commands output JSON by default
- Pipe results to next command without jq
- TypeScript config enables LSP autocomplete

## Error Handling

- 4xx errors: check parameter validation
- 5xx errors: retry with exponential backoff

这些文件由 Cloudflare 维护,Agent 无需手动学习最佳实践。

实际使用场景

端到端 Worker 部署流程

单一工具完成完整生命周期 (传统需要切换多个 CLI):

# 1. 创建 Worker
$ cf workers.script.upload --name api-server --script @dist/worker.js

# 2. 配置域名
$ cf dns.records.create --zone example.com --type CNAME --name api --content workers.dev

# 3. 部署到生产
$ cf workers.deployments.create --script-name api-server --env production

# 4. 配置 Cloudflare Access 保护
$ cf access.applications.create \
  --name "API Server" \
  --domain api.example.com \
  --policy @access-policy.json

# 5. 启用 WAF 规则
$ cf waf.rules.create --zone example.com --rule-id managed-challenge

# 6. 监控日志
$ cf workers.tail --script-name api-server

Cloudflare 原文描述: "Agent 可以设置 Worker、部署它、监控和观察它、用 Cloudflare Access 保护它、购买域名并用 Cloudflare WAF 防护,全部来自单一工具。"

从 Wrangler 迁移

# 自动迁移现有项目
$ cf migrate

Migrating wrangler.toml to cloudflare.config.ts...
✓ Configuration converted
✓ Dependencies updated
✓ 18-month compatibility maintained

Next steps:
  1. Review cloudflare.config.ts
  2. Test: cf dev
  3. Deploy: cf deploy

Wrangler 在 cf 正式发布后将维护 18 个月。

与传统 API 调用的对比

维度	传统 curl + jq	cf CLI
输出格式	需要 `--json` + `jq` 过滤	默认 JSON,无需后处理
API 发现	手动解析文档或遍历端点	`cf cli search` 自然语言查询
参数验证	服务端报错,浪费 API 调用	客户端验证 + LSP 类型检查
配置复用	TOML/YAML 重复配置	TypeScript 编程式工厂
上下文大小	需要携带完整 API schema	按需搜索 + LSP 查询

厂商描述 vs 独立验证

本文内容来源: Cloudflare 官方博客 (2026-09-28),为厂商自述。

未经独立验证的声明:

上下文节省比例 (40% 配置缩减)
Agent 操作成功率
与竞品 CLI 的速度对比

可验证的技术特性:

工具开源: cloudflare/workers-sdk
API 覆盖范围: 可通过 cf cli search 验证
JSON 输出: 可实际运行命令确认
TypeScript 配置: 公开的类型定义

局限性与注意事项

Beta 阶段: cf 目前处于 beta,API 可能变动
学习曲线: TypeScript 配置需要开发者熟悉 TS 生态
Wrangler 过渡期: 18 个月后 Wrangler 维护状态未明确
Agent 依赖性: 工具高度优化 Agent 使用,人类开发者体验可能不如传统 CLI

开始使用

安装

# npm
npm install -g @cloudflare/cf

# 或直接运行
npx @cloudflare/cf --version

认证

# 使用 API Token
export CLOUDFLARE_API_TOKEN=your_token_here

# 或交互式登录
cf login

快速开始

# 1. 搜索操作
cf cli search "list workers"

# 2. 执行命令
cf workers.scripts.list

# 3. 创建配置
cf init

# 4. 启动开发服务器
cf dev

参考资料

Cloudflare 官方博客: Cloudflare cf CLI Launch (2026-09-28)
GitHub 仓库: cloudflare/workers-sdk
官方文档: cf CLI Documentation

发布日期: 基于 2026 年 9 月 28 日 Cloudflare 官方发布整理