将 cf 用于编码 Agent

编码 Agent 可以使用 cf 操作你的 Cloudflare 账户。命令会返回 JSON，并描述自身的输入，因此 Agent 无需事先了解 cf 即可找到并运行正确的命令。

为 Agent 设置 `cf`

全局安装 cf，让每个 Agent 会话都能运行它：
npm i cf
yarn add cf
pnpm add cf
bun add cf
在将 cf 安装为依赖的项目中，全局命令会运行项目内的副本。
登录：
```
cf auth login
```
登录会打开浏览器页面供你批准访问，请亲自完成此步骤。对于无人值守运行的 Agent，请参阅为无人值守 Agent 进行身份验证。
告诉 Agent 优先使用 cf。将以下说明添加到用户级 AGENTS.md、CLAUDE.md 或等效说明文件中：
AGENTS.mdmd
```
When interacting with Cloudflare, use the `cf` CLI unless the project has a
Wrangler configuration file.
```
仍使用 wrangler.jsonc 或 wrangler.toml 的项目继续通过 Wrangler 工作，其余 Cloudflare 任务则通过 cf 完成。

你也可以让 Agent 替你完成此设置：

Install the Cloudflare CLI with `npm install -g cf`. Then add this line to my
user-level AGENTS.md or CLAUDE.md file: "When interacting with Cloudflare, use
the cf CLI unless the project has a Wrangler configuration file."

帮助 Agent 查找命令

cf 有 2,900 多条命令。Agent 不必阅读每个产品的帮助，而是可以描述任务、检查最佳匹配，然后运行它。

通过描述任务来搜索命令：
```
cf cli search "create D1 database"
```
搜索在本地运行，不需要凭据。请将任务放在引号中。cf cli search 将整个任务作为单个参数，第一个词之后未加引号的词会作为未知命令失败。它最多返回五个匹配项组成的 JSON 数组，最佳匹配在前。每个匹配项包含命令和简短摘要。以下是此次搜索的前两个匹配项：
```
[
  {
    "command": "cf d1 create",
    "summary": "Create D1 Database"
  },
  {
    "command": "cf d1 update",
    "summary": "Update D1 Database"
  }
]
```
检查所选命令的 API 请求：
```
cf schema d1 create
```
JSON 结果描述该命令发送的 API 请求：operationId、httpMethod、path、pathParams、queryParams、hasRequestBody 和 requestBodyFields。每个参数和请求体字段会列出名称、类型以及是否必需。请求体字段还包含说明。cf schema 覆盖生成的 API 命令。要查看命令的参数和选项，或像 cf deploy 这样的命令，请带 --help 运行该命令。

路径和查询参数使用其 API 名称，例如 account_id。requestBodyFields 列出命令也作为选项接受的请求体字段，使用选项名称。对象内的字段会得到组合名称，例如 read_replication.mode 会变成 read-replication-mode，数组字段显示类型 string。对于某些请求体，该列表不完整或为空。对这些命令，请用 --body 传入完整请求体，并查阅 API 参考了解其结构。
使用 --dry-run 预览请求，然后去掉该选项再运行命令：
```
cf d1 create --name my-database --dry-run
```

根级和分组的 --help 输出开头会提醒 Agent 先使用 cf cli search。命令自身的 --help 以纯文本显示用法。如果 Agent 输入了不存在的命令，cf 会列出最接近的匹配项。

查找 Cloudflare 文档

你和 Agent 可以使用 cf docs search 查找 Cloudflare 各产品的指南、教程和示例。搜索使用实时 Cloudflare 文档，需要互联网连接，但不需要 Cloudflare 登录。

描述任务或提出问题：
```
cf docs search "proxy a DNS record"
```
请将查询放在引号中。命令最多返回五个按排名排列的 JSON 结果，每项包含 title、description 和 url。

选择一个结果，并使用 Accept: text/markdown 请求头获取其 URL，以 Markdown 阅读完整页面：

curl -H "Accept: text/markdown" \
  https://developers.cloudflare.com/learning-paths/prevent-ddos-attacks/baseline/proxy-dns-records/

使用 cf cli search 查找命令，使用 cf docs search 查找文档。两种搜索都保持通用：不要包含账户 ID、域名、电子邮件地址、令牌或其他可识别信息。

阅读命令输出

结果以 JSON 形式写入标准输出。消息（例如所选 zone）和错误写入标准错误。当标准输出不是终端时，其中仅包含结果，因此 Agent 无需额外标志即可解析它，或用 jq 过滤。

列表打印 JSON 数组并返回一页。分页选项因命令而异，请查看该命令的 --help 输出。
不返回数据的变更 不会向标准输出打印任何内容。
原始内容（例如 R2 对象或 Workers AI 模型生成的图像）原样写入标准输出。请将其重定向到文件。
JSON 输出 无论标准输出是否为终端都会缩进。仅在终端中添加颜色。

失败的命令以非零状态码退出，并将错误打印到标准错误。

安全运行命令

预览变更。 添加 --dry-run 以 JSON 打印请求而不发送。Dry run 不需要凭据。
检查被中止的删除。 在非交互会话中，没有 --force 的破坏性命令会向标准错误打印 Aborted.，并以状态码 0 退出。成功退出并不表示资源已被删除。
在允许 --force 之前先审查。 在某些命令上，--force 也是 API 参数。例如，cf workers delete --force 还会删除仍被其他 Workers 引用的 Worker。
在支持的地方使用本地数据。 --local 仅适用于本地开发提供的少数资源，主要是 KV 键、通过 cf d1 raw、cf d1 migrations list 和 cf d1 migrations apply 操作的 D1 数据库，以及 R2 对象。没有本地等效项的命令（包括 cf d1 query）会返回错误，而不是调用 Cloudflare API。

有关本地状态，请参阅本地资源数据。

在 Wrangler 项目中工作

要让 Agent 迁移项目，请让它：

预览迁移而不写入文件：
```
cf migrate --dry-run
```
运行迁移：
```
cf migrate
```
解决生成的 cloudflare.config.ts 中的 TODO(@cloudflare) 注释，并就它无法自行做出的选择询问你。在每个必需项解决之前，构建会失败。

完整流程请参阅迁移 Wrangler 项目。

为无人值守 Agent 进行身份验证

在持续集成（CI）等无人值守环境中运行的 Agent 无法完成 cf auth login。请改为设置 CLOUDFLARE_API_TOKEN。该令牌优先于任何已存储的登录。有关变量、令牌权限和非交互行为，请参阅在 CI 中使用 cf。

要在本机为某个项目给 Agent 单独的凭据，请将命名 profile 绑定到项目目录。请参阅使用命名 profile。

检查本地资源

当 cf dev 在受支持的编码 Agent 内运行时，开发服务器还会打印 Local Explorer API 的 URL 和主要路由。Agent 可以使用此 API 读取和更改 Worker 本地绑定中的数据，并查询本地跟踪和日志。