USAGE_GUIDE.md

Cloudflare Manager - Complete Usage Guide

Table of Contents

1. Installation
2. Quick Start
3. Interactive CLI
4. Python API Examples
5. Complete Workflows
6. Equivalent curl Commands

Installation

# Install dependencies
pip install -r requirements.txt

# Or install manually
pip install requests

Quick Start

Option 1: Quickstart Script (Recommended for Beginners)

python3 quickstart.py

This will guide you through:

• Creating a Pages project
• Deploying from a directory
• Binding a domain
• Getting nameservers

Option 2: Interactive CLI

python3 cloudflare_manager.py

This provides a full-featured menu with all operations.

Option 3: Example Script

python3 example_usage.py

This runs pre-configured examples.

Interactive CLI

The interactive CLI provides these operations:

Operations Menu:
1. List Pages Projects
2. Create Pages Project
3. Deploy Pages Project (from directory)
4. Add Domain to Pages Project
5. List Domains for Pages Project
6. Create Zone and Get Nameservers
7. Get Nameservers for Existing Domain
8. List Zones
9. Create Worker Route
10. List Worker Routes
11. Add Worker Custom Domain
0. Exit

Python API Examples

1. Basic Setup

from cloudflare_manager import CloudflareManager, CloudflareAccount

# Initialize with your credentials
account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

2. Deploy Pages Project

# Create project
project = cf.create_pages_project("my-site", "main")

# Deploy from directory
deployment = cf.deploy_pages_project(
    project_name="my-site",
    directory="./public",  # Your static files directory
    branch="main",
    commit_message="Deploy via API"
)

print(f"Deployed to: {deployment['url']}")

3. Bind Domain and Get Nameservers

# Create zone (adds domain to Cloudflare)
zone = cf.create_zone("example.com")
nameservers = zone["name_servers"]

print("Add these nameservers to your domain registrar:")
for ns in nameservers:
    print(f"  {ns}")

# Bind domain to Pages project
result = cf.add_pages_domain("my-site", "example.com")
print(f"Domain status: {result['status']}")

# If DNS validation is needed
if result.get("validation_data"):
    val = result["validation_data"]
    print(f"Add DNS record: {val['type']} {val['name']} = {val['value']}")

4. Configure Worker Routes

# Get zone ID
zone = cf.get_zone_by_name("example.com")
zone_id = zone["id"]

# Create worker route
cf.create_worker_route(
    zone_id=zone_id,
    pattern="example.com/api/*",
    script_name="my-api-worker"
)

# Add custom domain to worker
cf.add_worker_domain(
    hostname="api.example.com",
    service="my-api-worker",
    zone_id=zone_id,
    environment="production"
)

Complete Workflows

Workflow 1: Deploy Static Website

from cloudflare_manager import CloudflareManager, CloudflareAccount

# 1. Setup
account = CloudflareAccount(
    email="exslym@closedbyme.com",
    token="21f3fb278a15b732a4f52c95d5042d78d1a21"
)
cf = CloudflareManager(account)

# 2. Create and deploy
cf.create_pages_project("my-blog", "main")
cf.deploy_pages_project("my-blog", "./public", "main")

# 3. Add custom domain
zone = cf.create_zone("myblog.com")
cf.add_pages_domain("my-blog", "myblog.com")
cf.add_pages_domain("my-blog", "www.myblog.com")

print("✓ Website deployed!")
print(f"Nameservers: {zone['name_servers']}")

Workflow 2: API with Custom Domain

# 1. Setup (same as above)
# ...

# 2. Get zone
zone = cf.get_zone_by_name("example.com")
zone_id = zone["id"]

# 3. Configure routes
cf.create_worker_route(
    zone_id=zone_id,
    pattern="example.com/api/*",
    script_name="api-worker"
)

# 4. Add subdomain
cf.add_worker_domain(
    hostname="api.example.com",
    service="api-worker",
    zone_id=zone_id
)

print("✓ API configured at api.example.com")

Workflow 3: Multiple Domains on One Project

# 1. Deploy project
cf.create_pages_project("multi-domain-site", "main")
cf.deploy_pages_project("multi-domain-site", "./dist", "main")

# 2. Add multiple domains
domains = ["example.com", "www.example.com", "example.org", "www.example.org"]

for domain in domains:
    # Create zone for each root domain
    if not domain.startswith("www."):
        cf.create_zone(domain)
    
    # Bind to Pages
    cf.add_pages_domain("multi-domain-site", domain)

print("✓ All domains configured")

Equivalent curl Commands

For reference, here are the equivalent curl commands for key operations:

1. List Accounts

curl https://api.cloudflare.com/client/v4/accounts \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

2. Create Pages Project

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{
    "name": "my-pages-app",
    "production_branch": "main"
  }'

3. Deploy Pages Project

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/$PROJECT_NAME/deployments \
  -H 'Content-Type: multipart/form-data' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -F branch=main \
  -F commit_message='Deploy via curl' \
  -F manifest='{"index.html": "abc123"}' \
  -F index.html=@./index.html

4. Add Domain to Pages

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/$PROJECT_NAME/domains \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{"name": "example.com"}'

5. Create Zone (Get Nameservers)

curl https://api.cloudflare.com/client/v4/zones \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{
    "account": {"id": "'$ACCOUNT_ID'"},
    "name": "example.com",
    "type": "full"
  }'

6. Get Zone Details (Including Nameservers)

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

7. Create Worker Route

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/workers/routes \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{
    "pattern": "example.com/*",
    "script": "my-workers-script"
  }'

8. Add Worker Custom Domain

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/domains \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{
    "hostname": "api.example.com",
    "service": "my-worker",
    "zone_id": "'$ZONE_ID'",
    "environment": "production"
  }'

Testing with Provided Credentials

Using the provided test account:

from cloudflare_manager import CloudflareManager, CloudflareAccount

account = CloudflareAccount(
    email="exslym@closedbyme.com",
    token="21f3fb278a15b732a4f52c95d5042d78d1a21"
)
cf = CloudflareManager(account)

# Test 1: List existing projects
projects = cf.list_pages_projects()
print(f"Found {len(projects)} project(s)")

# Test 2: List zones
zones = cf.list_zones()
for zone in zones:
    print(f"Domain: {zone['name']}")
    print(f"Nameservers: {zone['name_servers']}")

# Test 3: Deploy current directory
cf.create_pages_project("test-deploy", "main")
cf.deploy_pages_project("test-deploy", ".", "main")

Environment Variables (Optional)

You can also use environment variables:

export CLOUDFLARE_EMAIL="your-email@example.com"
export CLOUDFLARE_API_TOKEN="your-token"

Then in Python:

import os
from cloudflare_manager import CloudflareManager, CloudflareAccount

account = CloudflareAccount(
    email=os.getenv("CLOUDFLARE_EMAIL"),
    token=os.getenv("CLOUDFLARE_API_TOKEN")
)
cf = CloudflareManager(account)

Troubleshooting

Issue: "Invalid request headers" or "Invalid format for Authorization header"

Solution: Check that your API token is correct and has the required permissions.

Issue: "Zone not found"

Solution: The domain must first be added to Cloudflare using create_zone().

Issue: "Failed to deploy"

Solution: Ensure:

1. The directory exists and contains files
2. There's an index.html file
3. Files are not too large (25MB limit per file)

Issue: Domain validation required

Solution: Add the DNS validation record shown in the response to your DNS settings.

Advanced Usage

Using Multiple Accounts

from cloudflare_manager import MultiAccountManager

manager = MultiAccountManager()

# Add multiple accounts
manager.add_account("personal", "personal@example.com", "token1")
manager.add_account("work", "work@example.com", "token2")

# Use specific account
personal_cf = manager.get_account("personal")
work_cf = manager.get_account("work")

# Deploy to both accounts
personal_cf.deploy_pages_project("my-site", "./public", "main")
work_cf.deploy_pages_project("company-site", "./dist", "main")

Batch Operations

# Deploy to multiple projects
projects = ["site1", "site2", "site3"]

for project in projects:
    cf.create_pages_project(project, "main")
    cf.deploy_pages_project(project, f"./projects/{project}", "main")
    print(f"✓ Deployed {project}")

API Rate Limits

Cloudflare has rate limits:

• Standard: 1,200 requests per 5 minutes
• Per endpoint: Varies

The manager handles errors gracefully, but for bulk operations, consider adding delays:

import time

for project in large_project_list:
    cf.deploy_pages_project(project, f"./{project}", "main")
    time.sleep(1)  # Add 1 second delay

Support

For issues or questions:

1. Check the Cloudflare API docs
2. Review error messages carefully
3. Ensure API token has correct permissions
4. Verify account limits (zones, projects, etc.)

License

MIT License - Use freely in your projects!