⚙️ Configuration Guide

Complete guide to configuring the Cloudflare CLI for your environment

Table of Contents

• Quick Setup
• Configuration Methods
• Environment Variables
• Configuration File
• Authentication
• Advanced Configuration
• Profile Management
• Security Best Practices

Quick Setup

Minimal Configuration (2 minutes)

# Set your API token
export CLOUDFLARE_API_TOKEN="your_token_here"

# Set your account ID
export CLOUDFLARE_ACCOUNT_ID="your_account_id"

# Test the configuration
cf auth test

Recommended Configuration (5 minutes)

# Create configuration file
cf config init

# Follow the interactive setup
# Enter your API token when prompted
# Select your account
# Choose default zone

# Verify configuration
cf config show

Configuration Methods

The CLI supports three configuration methods (in order of precedence):

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (lowest priority)

Priority Example

# Configuration file has token: "token_from_file"
# Environment has: CLOUDFLARE_API_TOKEN="token_from_env"
# Command uses: --token "token_from_cli"

cf scan --token "token_from_cli"  # Uses: token_from_cli
cf scan                            # Uses: token_from_env
unset CLOUDFLARE_API_TOKEN
cf scan                            # Uses: token_from_file

Environment Variables

Required Variables

# API Authentication (choose one)
CLOUDFLARE_API_TOKEN="your_api_token"        # Recommended
# OR
CLOUDFLARE_EMAIL="your_email"
CLOUDFLARE_API_KEY="your_global_api_key"     # Not recommended

# Account Information
CLOUDFLARE_ACCOUNT_ID="your_account_id"      # Required for most operations

Optional Variables

# Default targets
CLOUDFLARE_ZONE_ID="zone_id"                 # Default zone for operations
CLOUDFLARE_ZONE_NAME="example.com"           # Alternative to zone ID

# CLI behavior
CF_CLI_OUTPUT_FORMAT="json"                  # Output format: json, yaml, table
CF_CLI_LOG_LEVEL="info"                      # Log level: debug, info, warn, error
CF_CLI_COLOR="auto"                          # Color output: always, never, auto
CF_CLI_TIMEOUT="30"                          # API timeout in seconds
CF_CLI_PARALLEL="4"                          # Parallel operations limit

# Performance
CF_CLI_CACHE_DIR="~/.cf-cli/cache"          # Cache directory
CF_CLI_CACHE_TTL="300"                       # Cache TTL in seconds
CF_CLI_MAX_RETRIES="3"                       # API retry attempts

# Development
CF_CLI_API_URL="https://api.cloudflare.com/client/v4"  # API endpoint
CF_CLI_DEBUG="false"                         # Debug mode
CF_CLI_DRY_RUN="false"                       # Dry run mode

Configuration File

Default Location

• macOS/Linux: ~/.cf-cli/config.json
• Windows: %USERPROFILE%\.cf-cli\config.json

File Format

{
  "version": "1.0.0",
  "default_profile": "production",
  "profiles": {
    "production": {
      "api_token": "your_production_token",
      "account_id": "your_account_id",
      "zone_id": "default_zone_id",
      "settings": {
        "output_format": "table",
        "log_level": "info",
        "color": "auto",
        "timeout": 30,
        "parallel": 4
      }
    },
    "development": {
      "api_token": "your_dev_token",
      "account_id": "dev_account_id",
      "settings": {
        "log_level": "debug",
        "dry_run": true
      }
    }
  },
  "aliases": {
    "ls": "list",
    "rm": "delete",
    "cp": "copy"
  },
  "defaults": {
    "confirmation": true,
    "backup": true,
    "verbose": false
  }
}

Creating Configuration

# Interactive setup
cf config init

# From template
cf config init --template production

# Import existing
cf config import cloudflare.config.json

Managing Configuration

# Show current configuration
cf config show

# Get specific value
cf config get api_token
cf config get profiles.production.account_id

# Set values
cf config set api_token "new_token"
cf config set settings.output_format "json"

# Add profile
cf config profile add staging

# Switch profile
cf config profile use staging

# List profiles
cf config profile list

Authentication

API Token (Recommended)

Creating an API Token

1. Go to Cloudflare Dashboard
2. Click Create Token
3. Choose a template or create custom token

Required Permissions

Account:
  - Account:Read

Zone:
  - Zone:Read
  - Zone:Edit

DNS:
  - DNS:Read
  - DNS:Edit

Workers:
  - Workers Scripts:Read
  - Workers Scripts:Edit
  - Workers KV Storage:Read
  - Workers KV Storage:Edit
  - Workers Routes:Read
  - Workers Routes:Edit

Storage:
  - D1:Read
  - D1:Write
  - R2:Read
  - R2:Write

Durable Objects:
  - Durable Objects:Read
  - Durable Objects:Write

Using API Token

# Set token
export CLOUDFLARE_API_TOKEN="your_token"

# Or in config file
cf config set api_token "your_token"

# Test authentication
cf auth test

Global API Key (Not Recommended)

# Requires email and key
export CLOUDFLARE_EMAIL="your_email"
export CLOUDFLARE_API_KEY="your_global_key"

# Test
cf auth test

OAuth Token

# Login with browser
cf auth login

# This will:
# 1. Open browser for authentication
# 2. Save token securely
# 3. Configure CLI automatically

Advanced Configuration

Multiple Accounts

# Add accounts
cf config account add personal --token "token1"
cf config account add work --token "token2"

# Switch accounts
cf config account use work

# Run command with specific account
cf --account personal zones list

Environment-Specific Config

# Development
export CF_CLI_ENV=development
export CF_CLI_DRY_RUN=true
export CF_CLI_LOG_LEVEL=debug

# Staging
export CF_CLI_ENV=staging
export CF_CLI_API_URL="https://staging-api.example.com"

# Production
export CF_CLI_ENV=production
export CF_CLI_LOG_LEVEL=error
export CF_CLI_TIMEOUT=60

Proxy Configuration

# HTTP proxy
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

# SOCKS proxy
export ALL_PROXY="socks5://proxy.example.com:1080"

# No proxy for local
export NO_PROXY="localhost,127.0.0.1,.local"

Custom API Endpoint

# Use custom endpoint
export CF_CLI_API_URL="https://custom-api.example.com/v4"

# Or in config
cf config set api_url "https://custom-api.example.com/v4"

Profile Management

Creating Profiles

# Create new profile
cf config profile create staging \
  --token "staging_token" \
  --account "staging_account_id"

# Copy existing profile
cf config profile copy production staging

# Import profile
cf config profile import staging.json

Using Profiles

# Set default profile
cf config profile default production

# Use profile for single command
cf --profile staging zones list

# Use profile for session
export CF_CLI_PROFILE=staging

Profile Templates

# Development template
cf config profile create dev --template development

# Production template
cf config profile create prod --template production

# Custom template
cf config profile create custom --from-file template.json

Security Best Practices

Secure Token Storage

macOS Keychain

# Store token in keychain
security add-generic-password \
  -a "$USER" \
  -s "cf-cli-token" \
  -w "your_token"

# Retrieve token
export CLOUDFLARE_API_TOKEN=$(security find-generic-password \
  -a "$USER" \
  -s "cf-cli-token" \
  -w)

Linux Secret Service

# Store using secret-tool
echo -n "your_token" | secret-tool store \
  --label="Cloudflare CLI Token" \
  application cf-cli \
  service api-token

# Retrieve token
export CLOUDFLARE_API_TOKEN=$(secret-tool lookup \
  application cf-cli \
  service api-token)

Environment File Security

# Create secure env file
touch ~/.cf-cli/.env
chmod 600 ~/.cf-cli/.env

# Add to .env
echo "CLOUDFLARE_API_TOKEN=your_token" >> ~/.cf-cli/.env

# Source in shell profile
echo 'source ~/.cf-cli/.env' >> ~/.bashrc

Token Rotation

# Generate new token
cf auth rotate-token

# Update all profiles
cf config profile update-all --token "new_token"

# Verify new token
cf auth test --all-profiles

Audit Logging

# Enable audit logging
export CF_CLI_AUDIT_LOG="/var/log/cf-cli-audit.log"

# Configure detailed logging
export CF_CLI_LOG_LEVEL=debug
export CF_CLI_LOG_SENSITIVE=false  # Don't log sensitive data

Configuration Examples

Minimal Setup

{
  "api_token": "your_token",
  "account_id": "your_account_id"
}

Developer Setup

{
  "api_token": "your_token",
  "account_id": "your_account_id",
  "settings": {
    "output_format": "json",
    "log_level": "debug",
    "dry_run": true,
    "verbose": true
  }
}

Production Setup

{
  "api_token": "your_token",
  "account_id": "your_account_id",
  "settings": {
    "output_format": "json",
    "log_level": "error",
    "timeout": 60,
    "parallel": 8,
    "confirmation": true,
    "backup": true
  },
  "notifications": {
    "slack_webhook": "https://hooks.slack.com/...",
    "email": "ops@example.com"
  }
}

CI/CD Setup

# .github/workflows/deploy.yml
env:
  CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
  CF_CLI_OUTPUT_FORMAT: json
  CF_CLI_LOG_LEVEL: info
  CF_CLI_COLOR: never

Validation

Test Configuration

# Full validation
cf config validate

# Test authentication
cf auth test

# Test permissions
cf auth permissions

# Test connectivity
cf auth ping

Debugging Configuration

# Show resolved configuration
cf config debug

# Show configuration sources
cf config sources

# Test specific profile
cf config test --profile production

Troubleshooting

Common Issues

Token Not Found

# Check environment
env | grep CLOUDFLARE

# Check config file
cat ~/.cf-cli/config.json

# Check keychain/secret service
# macOS
security find-generic-password -s "cf-cli-token"
# Linux
secret-tool search application cf-cli

Permission Denied

# Check token permissions
cf auth permissions

# Verify token scopes
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Configuration Not Loading

# Check file permissions
ls -la ~/.cf-cli/config.json

# Validate JSON syntax
jq . ~/.cf-cli/config.json

# Check for conflicts
cf config conflicts

Next Steps

• 🚀 Follow the Quick Start Guide
• 📚 Explore CLI Commands
• 🔒 Review Security Best Practices
• 🔧 Learn about Advanced Features

Last Updated: December 2024
Version: 1.0.0