CFAD - CloudFlare Admin CLI
A fast, type-safe Rust CLI for managing Cloudflare DNS, zones, and cache from the command line.
Current Status: v0.2.0 - DNS features complete (show, update, delete, import)
Features
✅ Implemented Features
- 🚀 Fast & Efficient - Built in Rust for optimal performance
- 🔒 Type-Safe - Leverages Rust's type system for reliability
- 🎨 Beautiful Output - Colored tables and formatted output
- 🔄 Smart Retries - Automatic retry with exponential backoff
- ⚡ Rate Limited - Respects Cloudflare API rate limits (4 req/s)
- 🔐 Secure - Multiple authentication methods with credential redaction
- 📊 Progress Tracking - Visual feedback for operations
🎯 Core Capabilities
| Feature | Status | Commands |
|---|---|---|
| DNS Management | ✅ Complete | list, show, add, update, delete, import |
| Zone Management | ✅ Complete | list, show, create, delete, settings, update |
| Cache Management | ✅ Complete | purge (all, files, tags, hosts, prefixes) |
| Config Management | ✅ Complete | init, show, profiles |
| Firewall Rules | 🔮 Planned | Firewall rule CRUD, IP access rules |
| Analytics | 🔮 Planned | Dashboard queries, metrics export |
| Workers | 🔮 Planned | Worker deployment and management |
| R2 Integration | 🔮 Planned | Integrate cfr2 functionality |
Installation
From Release Binary (Recommended)
Download the latest release for your platform from the Releases page.
Windows
# Download and extract
Invoke-WebRequest -Uri "https://github.com/davidcforbes/cfad/releases/latest/download/cfad-0.2.0-x86_64-pc-windows-msvc.zip" -OutFile cfad.zip
Expand-Archive cfad.zip
Move-Item cfad\cfad.exe $env:USERPROFILE\.cargo\bin\
# Verify installation
cfad --version
Linux (Ubuntu/Debian)
# Download and install
# Verify installation
macOS (Intel)
# Download and install
# Verify installation
macOS (Apple Silicon - M1/M2/M3)
# Download and install
# Verify installation
From Source
# Clone repository
# Build and install
# Verify installation
Using Cargo
# Install directly from source (once published to crates.io)
# Verify installation
Quick Start
-
Initialize configuration:
-
Add your API token:
Edit your config file (
~/.config/cfad/config.tomlon Linux/Mac or%APPDATA%\cfad\config.tomlon Windows):= "default" [] = "your_cloudflare_api_token" = "example.com" = "table" -
Start managing your Cloudflare resources:
Authentication
CFAD supports multiple authentication methods with the following priority:
-
CLI Flags (highest priority)
-
Environment Variables
-
Configuration File
API Token (Recommended)
Create an API token at https://dash.cloudflare.com/profile/api-tokens
Required permissions:
- Zone:Read (for zone list/show)
- Zone:Edit (for zone create/update/delete)
- DNS:Read (for DNS list/show)
- DNS:Edit (for DNS create/update/delete)
- Cache Purge (for cache operations)
Legacy API Key + Email
Or in config file:
[]
= "your_api_key"
= "your@email.com"
Usage
DNS Management
List DNS Records
# List all DNS records for a zone
# Filter by record type
# Filter by name
Output:
DNS Records for example.com:
╔══════╦═══════════════════╦════════════════╦══════╦═════════╦══════════╗
║ Type ║ Name ║ Content ║ TTL ║ Proxied ║ ID ║
╠══════╬═══════════════════╬════════════════╬══════╬═════════╬══════════╣
║ A ║ example.com ║ 203.0.113.1 ║ Auto ║ ✓ ║ abc12345 ║
║ A ║ www.example.com ║ 203.0.113.1 ║ Auto ║ ✓ ║ def67890 ║
║ MX ║ example.com ║ mail.example. ║ Auto ║ ✗ ║ ghi11213 ║
╚══════╩═══════════════════╩════════════════╩══════╩═════════╩══════════╝
Total: 3 records
Create DNS Record
# Create an A record
# With TTL and proxied
# Create MX record with priority
Show DNS Record
# Show DNS record details
Output:
DNS Record Details:
ID: abc123...
Type: A
Name: www.example.com
Content: 203.0.113.1
TTL: Auto
Proxied: ✓
Created: 2026-01-15T10:30:00Z
Modified: 2026-01-20T14:22:00Z
Update DNS Record
# Update record content
# Update TTL and proxy status
# Update name
Delete DNS Record
# Delete with confirmation
Import DNS Records
# Import from CSV file
# Import from BIND zone file
CSV Format:
type,name,content,ttl,proxied,priority
A,@,203.0.113.1,3600,true,
A,www,203.0.113.1,3600,true,
MX,@,mail.example.com,3600,false,10
TXT,@,"v=spf1 mx ~all",3600,false,
BIND Format:
$ORIGIN example.com.
$TTL 3600
@ IN A 203.0.113.1
www IN A 203.0.113.1
mail IN A 203.0.113.2
@ IN MX 10 mail.example.com.
@ IN TXT "v=spf1 mx ~all"
Zone Management
List Zones
# List all zones
# Filter by status
Output:
Zones:
╔═══════════════════╦════════╦══════════╗
║ Name ║ Status ║ ID ║
╠═══════════════════╬════════╬══════════╣
║ example.com ║ active ║ abc12345 ║
║ example.org ║ active ║ def67890 ║
║ pending.com ║ pending║ ghi11213 ║
╚═══════════════════╩════════╩══════════╝
Total: 3 zones
Show Zone Details
# Show by name or ID
Output:
Zone: example.com
ID: abc123...
Status: active
Name Servers: ["ns1.cloudflare.com", "ns2.cloudflare.com"]
Create Zone
# Create a new zone
Delete Zone
# Delete with confirmation
Show Zone Settings
Update Zone Settings
# Update SSL mode
# Update multiple settings
# Available options:
# --security-level: off, low, medium, high, under_attack
# --cache-level: aggressive, basic, simplified
# --dev-mode: on, off
# --ipv6: on, off
# --ssl: off, flexible, full, strict
# --always-https: on, off
Cache Management
Purge All Cache
Purge Specific Files
# Single file
# Multiple files (comma-separated)
Purge by Cache Tags
# Requires Cloudflare Enterprise
Purge by Hosts
Purge by Prefixes
# Requires Cloudflare Enterprise
Configuration Management
Initialize Config
Show Configuration
# Show default profile
# Show specific profile
Output:
Profile configuration:
API Token: Some("abcd****")
API Key: None
API Email: None
Default Zone: Some("example.com")
Output Format: Some("table")
Manage Profiles
# List all profiles
# Add a new profile
# Set default profile
Global Options
All commands support these global options:
Examples
# Use production profile
# Override with API token
# JSON output for scripting
|
# Verbose mode for debugging
# Quiet mode
Output Formats
Table (Default)
Beautifully formatted tables with colors
JSON
Machine-readable output for scripting:
|
CSV
Spreadsheet-compatible output:
Configuration File
Location:
- Linux/Mac:
~/.config/cfad/config.toml - Windows:
%APPDATA%\cfad\config.toml
Format:
= "default"
[]
= "your_cloudflare_api_token"
= "example.com"
= "table"
[]
= "prod_token"
= "prod-example.com"
= "json"
[]
= "staging_token"
= "staging-example.com"
Architecture
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ CFAD CLI (v0.2.0) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Config │ │ Command │ │ Output │ │
│ │ Manager │ │ Parser │ │ Formatter │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────┬───────┴──────────────────┘ │
│ │ │
│ ┌─────────▼──────────────────────┐ │
│ │ CloudflareClient │ │
│ │ (Async HTTP + Rate Limiting) │ │
│ └─────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┬──────────────┐ │
│ │ │ │ │ │
│ ┌─▼───────┐ ┌──▼─────┐ ┌────▼────┐ ┌──────▼──────┐ │
│ │ DNS │ │ Zone │ │ Cache │ │ Config │ │
│ │ Module │ │ Module │ │ Module │ │ Module │ │
│ └─────────┘ └────────┘ └─────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Cloudflare REST API v4 │
│ https://api.cloudflare.com │
└─────────────────────────────┘
Project Structure
cfad/
├── src/
│ ├── main.rs # Entry point, command routing
│ ├── cli/ # CLI definitions
│ │ ├── mod.rs # Main CLI structure
│ │ ├── config.rs # Config commands
│ │ ├── dns.rs # DNS commands
│ │ ├── zone.rs # Zone commands
│ │ └── cache.rs # Cache commands
│ ├── client/ # HTTP client
│ │ ├── mod.rs # CloudflareClient
│ │ └── retry.rs # Retry logic
│ ├── config/ # Configuration
│ │ ├── mod.rs # Profile management
│ │ └── validation.rs # Validators
│ ├── error/ # Error handling
│ │ ├── mod.rs # Error types
│ │ └── category.rs # Error categories
│ ├── api/ # API models
│ │ ├── dns.rs # DNS models
│ │ ├── zone.rs # Zone models
│ │ ├── cache.rs # Cache models
│ │ └── response.rs # Response wrappers
│ ├── ops/ # Operations
│ │ ├── dns.rs # DNS operations
│ │ ├── zone.rs # Zone operations
│ │ └── cache.rs # Cache operations
│ ├── output/ # Output formatting
│ │ └── table.rs # Table formatter
│ ├── utils/ # Utilities
│ │ └── validation.rs # Input validators
│ └── metrics/ # Metrics (stub)
├── Cargo.toml # Dependencies
├── LICENSE # MIT License
└── README.md # This file
Key Design Patterns
- Async-First: Tokio runtime for all I/O operations
- Type-Safe: Rust's type system for API request/response validation
- Modular: Clear separation of concerns (CLI → Ops → Client → API)
- Error Resilient: Comprehensive error handling with automatic retries
- User-Friendly: Colored output, progress indicators, helpful error messages
- Configurable: Multiple credential sources with priority order
Error Handling
CFAD provides clear error messages with categories:
- API Errors - Issues with Cloudflare API responses
- Authentication Errors - Invalid or missing credentials
- Network Errors - Connection issues (auto-retried)
- Validation Errors - Invalid input parameters
- Configuration Errors - Config file or profile issues
Automatic Retries
Network errors are automatically retried with exponential backoff:
- Max attempts: 3
- Initial delay: 100ms
- Max delay: 30s
- Multiplier: 2x
Rate Limiting
CFAD respects Cloudflare's rate limits:
- Default: 4 requests/second
- Automatic throttling via tokio::sync::Semaphore
- Prevents API quota exhaustion
Advanced Usage
Scripting
#!/bin/bash
# Update all zones to strict SSL
for; do
done
Multi-Profile Workflow
# Development
# Staging
# Production
Troubleshooting
Command Not Found
# Ensure ~/.cargo/bin is in PATH
|
# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
Authentication Errors
# Verify API token
# Test with explicit token
# Check token permissions at:
# https://dash.cloudflare.com/profile/api-tokens
Rate Limit Errors
# Use --verbose to see retry attempts
# Wait a few minutes and try again
# CFAD automatically retries with backoff
Network Errors
# Check connectivity
# Use verbose mode
# Check proxy settings if behind corporate firewall
Development
Building from Source
# Clone repository
# Build debug version
# Build release version (optimized)
# Run tests
# Check for errors
# Run linter
# Format code
Quality Metrics
- ✅ Compilation Errors: 0
- ✅ Compilation Warnings: 0
- ✅ Clippy Warnings: 0
- ✅ Tests: 68 (54 unit + 14 integration)
- ✅ Binary Size: 5.3 MB (release)
- ✅ Build Time: ~55s (release)
Code Quality Checks
Run all quality checks before pushing:
# Using Claude Code (recommended)
# Using scripts
# Windows: .\scripts\quality-check.ps1
# Linux/macOS: ./scripts/quality-check.sh
# Using Make
The /quality Claude Skill runs comprehensive checks:
- Code formatting (cargo fmt)
- Linting (cargo clippy with zero warnings)
- Tests (all 68 tests)
- Security audit (cargo audit)
- Release build verification
See DEVELOPMENT.md for:
- Setting up development tools
- Running local code quality checks
- Git hooks for automated checking
- Complexity analysis
- Contributing guidelines
Dependencies
Core Dependencies (14 production dependencies - 30% reduction)
- CLI: clap 4.5
- Async: tokio 1.40
- HTTP: reqwest 0.13
- Serialization: serde 1.0, serde_json 1.0, toml 0.9, csv 1.3
- Error Handling: thiserror 2.0
- Logging: tracing 0.1, tracing-subscriber 0.3
- Config: dirs 6.0
- UI: comfy-table 7.1
- Utils: regex 1.10, url 2.5
Dev Dependencies
- Mocking: wiremock 0.6
Removed unused dependencies: chrono, futures, anyhow, colored, clap_complete, indicatif, assert_cmd, predicates, tempfile, serial_test
Roadmap
v0.2.0 - Bulk Operations (Planned)
- DNS import from BIND zone files
- DNS import from CSV files
- Bulk DNS record updates
- Zone migration tools
v0.3.0 - Security Features (Planned)
- Firewall rule management
- IP access rules (whitelist/block/challenge)
- Country-based blocking
- WAF custom rules
v0.4.0 - Analytics & Reporting (Planned)
- Dashboard analytics queries
- Request/bandwidth/threat metrics
- Time-range filtering
- CSV/JSON report export
v0.5.0 - Workers & Edge (Planned)
- Worker script deployment
- Worker log tailing
- KV namespace management
- Durable Objects support
v1.0.0 - Full Integration (Planned)
- R2 bucket management (integrate cfr2)
- Pages deployment
- Stream video management
- Shell completions (bash/zsh/fish)
- Comprehensive test coverage
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Areas for Contribution
- DNS Import - BIND and CSV file parsers
- Firewall Management - Firewall rule CRUD operations
- Analytics - Cloudflare Analytics API integration
- Workers - Worker deployment and management
- Test Coverage - Integration and unit tests
- Documentation - Usage examples and guides
License
MIT License - see LICENSE file for details.
Acknowledgments
- Built with Rust
- CLI framework: Clap
- HTTP client: Reqwest
- Table formatting: Comfy Table
- Async runtime: Tokio
- Inspired by cloudflare-cli
- Architecture patterns from cfr2
Support
- Documentation: This README
- Issues: GitHub Issues
- Cloudflare API Docs: https://developers.cloudflare.com/api/
Migration Guide
Upgrading from v0.1.0 to v0.2.0
Breaking Changes:
v0.2.0 introduces breaking changes to DNS record operations to align with Cloudflare API requirements and industry standards.
DNS Show Command
v0.1.0 (non-functional):
v0.2.0:
DNS Update Command
v0.1.0 (non-functional):
v0.2.0:
DNS Delete Command
v0.1.0 (non-functional):
v0.2.0:
Why the Change?
The Cloudflare API requires both zone_id and record_id for all DNS record operations. There is no API endpoint to search for a DNS record across all zones. This change:
- Matches industry standard (cloudflare-cli)
- Provides clear user intent
- Eliminates unnecessary API calls
- Ensures predictable performance
No Breaking Changes
These commands remain unchanged:
cfad dns list <zone>- No changecfad dns add <zone> <type> <name> <content>- No change- All zone, cache, config commands - No change
Changelog
v0.2.0 (2026-02-02)
Completed:
- ✅ DNS show command - View detailed record information
- ✅ DNS update command - Modify existing records (now functional)
- ✅ DNS delete command - Remove records (now functional)
- ✅ DNS import - Bulk import from CSV files
- ✅ DNS import - Bulk import from BIND zone files
- ✅ Auto-detect file format (CSV vs BIND)
- ✅ Support for A, AAAA, CNAME, MX, TXT, NS record types
- ✅ Progress indicators for bulk operations
- ✅ Comprehensive error handling with partial import support
- ✅ Zero compilation errors/warnings
- ✅ Zero clippy warnings
Breaking Changes:
- DNS show, update, delete commands now require
<zone>parameter - Old:
cfad dns update <record-id> --content X - New:
cfad dns update <zone> <record-id> --content X - See Migration Guide above for details
Architecture:
- Aligned with Cloudflare API zone-scoped requirements
- Matches industry standard (jordantrizz/cloudflare-cli)
- Single API call per operation (improved performance)
v0.1.0 (2026-02-01)
Implemented:
- ✅ DNS management (list, add, update, delete)
- ✅ Zone management (list, show, create, delete, update settings)
- ✅ Cache management (purge all, files, tags, hosts, prefixes)
- ✅ Configuration management with profiles
- ✅ Multiple authentication methods (API token, legacy key/email)
- ✅ Colored table output with comfy-table
- ✅ Automatic retries with exponential backoff
- ✅ Rate limiting (4 req/s)
- ✅ JSON/CSV/Table output formats
- ✅ Zero compilation warnings
- ✅ Production-ready release build
Not Implemented (Future):
- DNS import (BIND/CSV)
- Firewall rules
- Analytics queries
- Workers management
- R2 integration
- Shell completions
Made with ❤️ using Rust