cloudflare-cli

Cloudflare CLI（cf）

快速入门（3 分钟）

1. 安装

# Linux/macOS (global)
curl -fsSL https://raw.githubusercontent.com/coollabsio/cloudflare-cli/main/scripts/install.sh | bash

# Linux/macOS (user, no sudo)
curl -fsSL https://raw.githubusercontent.com/coollabsio/cloudflare-cli/main/scripts/install.sh | bash -s -- --user

# Via Go
go install github.com/coollabsio/cloudflare-cli@latest

# From source
git clone https://github.com/coollabsio/cloudflare-cli.git
cd cloudflare-cli && go build -o cf .

Windows：从 GitHub Releases 下载二进制文件，或使用 go build -o cf.exe . 从源代码构建。

2. 身份验证

在 Cloudflare Dashboard → My Profile → API Tokens 中创建 API 令牌，并授予以下权限：

• Zone:Read（列出区域）
• DNS:Read（查看记录）
• DNS:Edit（创建／更新／删除记录）

# Save token to config (recommended)
cf auth save <YOUR_API_TOKEN>

# Verify connection
cf auth verify

3. 首批命令

cf zones list
cf dns list example.com
cf dns create example.com -t A -n www -c 192.0.2.1 --proxied

---

身份验证

提供三种方法，按优先级排序（高优先级会覆盖低优先级）：

1. 配置文件（推荐）

cf auth save <token>
# Saves to ~/.cloudflare/config.yaml

配置文件内容：

api_token: your-api-token-here
output_format: table

2. 环境变量

export CLOUDFLARE_API_TOKEN=your-api-token
# OR
export CF_API_TOKEN=your-api-token

3. 旧版 API 密钥

export CLOUDFLARE_API_KEY=your-api-key
export CLOUDFLARE_API_EMAIL=your-email

优先级：环境变量会覆盖配置文件中的值。

所需的令牌权限

权限	范围	用途
Zone:Read	所有区域（推荐）	cf zones list、区域名称解析
DNS:Read	目标区域	cf dns list、cf dns get、cf dns find
DNS:Edit	目标区域	cf dns create、cf dns update、cf dns delete

重要：受限于特定区域的区域级令牌无法列出区域，也无法将区域名称解析为 ID。请参阅已知问题。

---

区域管理

cf zones list                            # List all zones in account
cf zones get example.com                 # Get zone details by name
cf zones get 023e105f4ecef8ad9ca31a...   # Get zone details by ID

所有命令均接受区域名称和区域 ID。

---

DNS 记录管理

列出记录

cf dns list <zone>                           # All records
cf dns list <zone> --type A                  # Filter by type
cf dns list <zone> --type A -t CNAME         # Multiple types
cf dns list <zone> --name www                # Filter by name
cf dns list <zone> --search "production"     # Search in comments/content
cf dns list <zone> -t A -n www              # Combined filters

获取记录详情

cf dns get <zone> <record-id>

创建记录

# A record
cf dns create <zone> -t A -n www -c 192.0.2.1

# CNAME with proxy
cf dns create <zone> -t CNAME -n blog -c example.com --proxied

# MX with priority
cf dns create <zone> -t MX -n mail -c mail.example.com --priority 10

# TXT record
cf dns create <zone> -t TXT -n _acme -c "verification-string"

# A record with comment
cf dns create <zone> -t A -n api -c 192.0.2.10 --comment "Production API"

创建选项：

选项	短选项	必需	用途
--type	-t	是	记录类型（A、AAAA、CNAME、MX、TXT 等）
--name	-n	是	记录名称（子域名或 @）
--content	-c	是	记录值（IP、主机名、文本）
--ttl		否	TTL，单位为秒（默认值：1 = 自动）
--proxied		否	通过 Cloudflare CDN 路由（布尔值）
--priority		否	优先级（MX、SRV 记录）
--comment		否	记录备注／说明

更新记录

cf dns update <zone> <record-id> --content 192.0.2.2
cf dns update <zone> <record-id> --proxied
cf dns update <zone> <record-id> --proxied=false
cf dns update <zone> <record-id> --comment "Updated comment"
cf dns update <zone> <record-id> --comment ""           # Clear comment
cf dns update <zone> <record-id> -t A -n newname -c 192.0.2.3  # Multiple fields

更新支持与创建相同的选项。只有指定的选项会被修改。

删除记录

cf dns delete <zone> <record-id>

查找记录

cf dns find <zone> --name www --type A
cf dns find <zone> -n api -t A
cf dns find <zone> --type MX

find 会返回匹配的记录。当你需要在更新或删除记录前查找记录 ID 时，可将其用于脚本。

---

配置

cf config set <key> <value>    # Set configuration value
cf config get <key>            # Get configuration value
cf config list                 # List all settings

可用键：

键	值	默认值	用途
output_format	table、json	table	默认输出格式

---

输出格式与脚本

cf dns list example.com                  # Table (default, human-readable)
cf dns list example.com --output json    # JSON for automation
cf dns list example.com -o json          # Short flag

# Set JSON as default
cf config set output_format json

# Pipe to jq for filtering
cf dns list example.com -o json | jq '.[].name'

# Extract record IDs
cf dns list example.com -o json | jq -r '.[].id'

---

重要规则

务必执行

• 首次使用前验证身份验证：cf auth verify
• 在脚本中使用 --output json，并将输出传递给 jq
• 使用区域级令牌时，使用区域 ID（而非名称）
• 为记录添加 --comment，以便记录说明
• 在生产环境中应用前，先在预发布区域测试 DNS 变更

切勿执行

• 使用 cf zones list 搭配区域级令牌（会因权限错误而失败）
• 将 API 令牌存入 Shell 历史记录——请改用 cf auth save
• 未先确认记录 ID 就删除记录（使用 cf dns find 或 cf dns get）
• 认为 --proxied 适用于所有记录类型（仅适用于 A、AAAA、CNAME）

命令名称更正

Claude 关于 cf CLI 的训练数据有限（该 CLI 于 2024 年 12 月发布）。常见的幻觉包括：

• 二进制文件名是 cf，而非 cloudflare 或 cloudflare-cli
• 应使用 cf zones list，而非 cf zone list（zones 为复数）
• 应使用 cf dns create，而非 cf dns add
• 应使用 cf dns delete，而非 cf dns remove
• 应使用 cf auth save <token>，而非 cf auth login 或 cf login
• 应使用 --output json／-o json，而非 --format json 或 --json
• 区域是位置参数：应使用 cf dns list example.com，而非 cf dns list --zone example.com

完整的更正规则请参阅 references/correction-rules.md。

---

已知问题预防

此技能可预防已记录的 3 个问题：

问题 #1：区域范围令牌权限错误

错误：使用 cf zones list 或解析区域名称时出现权限错误
原因：仅限特定区域的 API 令牌无法列出所有区域或将名称解析为 ID
预防措施：授予“所有区域”读取权限，或直接使用区域 ID：

# Instead of zone name (fails with scoped token):
cf dns list example.com

# Use zone ID (always works):
cf dns list 023e105f4ecef8ad9ca31a8b...

问题 #2：Windows 上找不到配置文件

错误：找不到配置文件或身份验证信息无法持久保存
原因：Windows 上不存在 ~/.cloudflare/ 目录
预防措施：保存身份验证信息前，确保目录存在：

mkdir -p ~/.cloudflare
cf auth save <token>

Windows 配置文件位置：%USERPROFILE%\.cloudflare\config.yaml

问题 #3：安装后出现“cf: command not found”

错误：运行安装脚本后出现 cf: command not found
原因：二进制文件不在 PATH 中，或安装到了意外位置
预防措施：检查安装位置并将其添加到 PATH：

# Check if binary exists
which cf || ls /usr/local/bin/cf || ls ~/bin/cf

# User install adds to ~/bin — ensure it's on PATH
export PATH="$HOME/bin:$PATH"

---

自我更新

cf update    # Download and install latest version
cf version   # Show current version

---

全局标志参考

标志	短标志	用途
--config		配置文件路径（默认：~/.cloudflare/config.yaml）
--output	-o	输出格式：table（默认）或 json