cf-cli

Cloudflare CLI（cf）

cf 是 Cloudflare 面向公开 Cloudflare API（2,900 多条命令，大多数由 API 架构生成）和 Workers 项目的命令行界面。目前处于 beta 阶段：在正式发布前，命令、配置和构建输出都可能发生变化。

优先检索，而非依赖预训练知识。 将任务描述给 cf cli search，用 cf schema 或 --help 检查匹配结果，并在运行尚未验证的命令前使用 --dry-run 预览。

文档索引：https://developers.cloudflare.com/cf/llms.txt

文档

主题	页面
安装、登录、凭据和账户选择	https://developers.cloudflare.com/cf/get-started/index.md
使用 cf init、cf dev、cf deploy 创建第一个 Worker	https://developers.cloudflare.com/cf/get-started/first-worker/index.md
在终端中查找、创建和删除资源	https://developers.cloudflare.com/cf/get-started/resources/index.md
面向 Wrangler 用户的 cf	https://developers.cloudflare.com/cf/wrangler/index.md
使用 cf migrate 迁移 Wrangler 项目	https://developers.cloudflare.com/cf/wrangler/migrate/index.md
Wrangler 到 cf 的命令和配置参考	https://developers.cloudflare.com/cf/wrangler/reference/index.md
开发、构建和部署；模式与预览	https://developers.cloudflare.com/cf/projects/index.md
类型化的 cloudflare.config.ts	https://developers.cloudflare.com/cf/projects/cloudflare-config/index.md
将 cf 与编码 Agent 配合使用（安全规则）	https://developers.cloudflare.com/cf/agents/index.md
CI、API 令牌、无人值守身份验证	https://developers.cloudflare.com/cf/ci/index.md
环境变量	https://developers.cloudflare.com/cf/environment-variables/index.md

首先：检查安装并登录

npm install --global cf   # installs two equivalent commands: `cf` and `cloudflare`
cf --version
cf auth whoami

• 需要 Node.js 22.18 或更高版本。不支持 Bun。
• 如果你的 PATH 中有另一个名为 cf 的工具，请改用 cloudflare——该软件包会同时安装这两个命令。
• cf auth login 会打印链接和一次性代码，然后打开浏览器。在远程计算机、SSH 会话或容器中，请添加 --no-browser，让 cf 只打印链接；然后从另一台设备批准登录。添加 --force 可重新登录。
• cf 使用自己的凭据，不会复用 Wrangler 登录信息。
• 无人值守 Agent 和 CI 无法完成 cf auth login——请改为设置 CLOUDFLARE_API_TOKEN（参见 https://developers.cloudflare.com/cf/ci/index.md）。

如需让 Agent 优先使用 cf，请将以下内容添加到用户级别的 AGENTS.md、CLAUDE.md 或同等文件中：

When interacting with Cloudflare, use the `cf` CLI unless the project has a
Wrangler configuration file.

查找命令

cf cli search "create a DNS record"   # local, no credentials; quote the whole task; up to 5 JSON matches
cf schema d1 create                   # API request shape: method, path, params, body fields
cf <command> --help                   # arguments and options (e.g. cf deploy --help)

cf cli search 将任务作为一个参数接收——第一个词之后未加引号的词会被解析为未知命令。cf schema 涵盖生成的 API 命令；有关命令参数和选项，请使用 --help。

读取输出

• 结果以 JSON 格式输出到标准输出；状态消息和错误输出到标准错误，因此通过管道传给 jq 或进行重定向时无需额外标志。
• 列表会输出一个 JSON 数组页面；分页选项因命令而异——请查看 --help。
• 命令失败时会以非零状态码退出，并将错误打印到标准错误。

安全运行命令

• 先预览。 --dry-run 会以 JSON 格式打印请求，但不会发送请求，且无需凭据。
• 已中止的删除仍以 0 退出。 在非交互式会话中，未使用 --force 的破坏性命令会将 Aborted. 打印到标准错误，并以 0 退出——退出状态为 0 不代表资源已被删除。
• 允许使用前先审查 --force。 对于某些命令，--force 也是 API 参数（例如，cf workers delete --force 还会删除其他 Workers 所引用的 Worker）。
• --local 适用范围有限。 它适用于 KV 键、D1 数据库（cf d1 raw、cf d1 migrations list|apply）和 R2 对象；其他命令（包括 cf d1 query）会返回错误，而不会调用 API。

为此项目选择 CLI

• 存在 cloudflare.config.ts：使用 cf。
• 存在 wrangler.jsonc、wrangler.json 或 wrangler.toml，且不存在 cloudflare.config.ts：dev、build 和 deploy 继续使用 Wrangler。不要在此处运行 cf dev、cf build 或 cf deploy——这些命令可能会生成新的配置并忽略 Wrangler 文件，或执行失败。可以同时使用 cf 资源命令（DNS、区域、存储）。仅在用户提出要求时运行 cf migrate，并遵循迁移 Wrangler 项目：使用 cf migrate --dry-run 预览，运行 cf migrate，然后处理生成的 cloudflare.config.ts 中的 TODO(@cloudflare) 注释。
• 两者均不存在：使用 cf，这是 与编码 Agent 搭配使用 cf 的建议。不要安装 Wrangler，也不要创建 Wrangler 配置文件。

对于 Wrangler 的等效命令，请使用 Wrangler 到 cf 参考或 cf cli search。不要凭记忆转换 Wrangler 命令。如需查看完整对比，请参阅面向 Wrangler 用户的 cf。

cf 尚不支持的命令

cf 尚不支持所有 Wrangler 命令。请改用 npx wrangler 运行这些命令，而不是将 Wrangler 添加到项目中。Wrangler 不会读取 cloudflare.config.ts，因此请传入 Worker 名称：

• 实时日志：npx wrangler tail <WORKER_NAME>。
• 单个机密：npx wrangler secret put <SECRET_NAME> --name <WORKER_NAME>。也可以将 --secrets-file <PATH> 传给 cf deploy 或 cf workers versions create，随新版 Worker 上传机密。

如需查看当前列表，请参阅 Wrangler 到 cf 参考中的“尚未支持的命令”。