cloudflare

# Cloudflare (Wrangler CLI) Manage Cloudflare Workers and associated services via the `wrangler` CLI. ## Prerequisites - Node.js v20+ required - Install: `npm install -g wrangler` or use project-local `npx wrangler` - Auth: `wrangler login` (opens browser for OAuth) - Verify: `wrangler whoami` ## Quick Reference ### Workers ```bash # Initialize new worker wrangler init <name> # Local development wrangler dev [script] # Deploy wrangler deploy [script] # List deployments wrangler deployments list # View deployment wrangler deployments view [deployment-id] # Rollback wrangler rollback [version-id] # Delete worker wrangler delete [name] # Tail logs (live) wrangler tail [worker] ``` ### Secrets ```bash # Add/update secret (interactive) wrangler secret put <key> # Add secret from stdin echo "value" | wrangler secret put <key> # List secrets wrangler secret list # Delete secret wrangler secret delete <key> # Bulk upload from JSON file wrangler secret bulk secrets.json ``` ### KV (Key-Value Store) ```bash # Create namespace wrangler kv namespace create <name> # List namespaces wrangler kv namespace list # Delete namespace wrangler kv namespace delete --namespace-id <id> # Put key wrangler kv key put <key> <value> --namespace-id <id> # Get key wrangler kv key get <key> --namespace-id <id> # Delete key wrangler kv key delete <key> --namespace-id <id> # List keys wrangler kv key list --namespace-id <id> # Bulk operations (JSON file) wrangler kv bulk put <file> --namespace-id <id> wrangler kv bulk delete <file> --namespace-id <id> ``` ### D1 (SQL Database) ```bash # Create database wrangler d1 create <name> # List databases wrangler d1 list # Database info wrangler d1 info <name> # Execute SQL wrangler d1 execute <database> --command "SELECT * FROM users" # Execute SQL file wrangler d1 execute <database> --file schema.sql # Local execution (for dev) wrangler d1 execute <database> --local --command "..." # Export database wrangler d1 export <name> --output backup.sql # Delete database wrangler d1 delete <name> # Migrations wrangler d1 migrations create <database> <name> wrangler d1 migrations apply <database> wrangler d1 migrations list <database> ``` ### R2 (Object Storage) ```bash # Create bucket wrangler r2 bucket create <name> # List buckets wrangler r2 bucket list # Delete bucket wrangler r2 bucket delete <name> # Upload object wrangler r2 object put <bucket>/<key> --file <path> # Download object wrangler r2 object get <bucket>/<key> --file <path> # Delete object wrangler r2 object delete <bucket>/<key> ``` ### Queues ```bash # Create queue wrangler queues create <name> # List queues wrangler queues list # Delete queue wrangler queues delete <name> ``` ## Configuration Files Wrangler supports both TOML and JSON/JSONC config formats: - `wrangler.toml` — traditional format - `wrangler.json` or `wrangler.jsonc` — newer, with JSON schema support **⚠️ Important:** If both exist, JSON takes precedence. Pick one format to avoid confusion where edits to TOML are ignored. ### JSONC format (with schema autocomplete) ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2024-12-30" } ``` ### TOML format ```toml name = "my-worker" main = "src/index.ts" compatibility_date = "2024-12-30" ``` With bindings: ```toml name = "my-worker" main = "src/index.ts" compatibility_date = "2024-12-30" # KV binding [[kv_namespaces]] binding = "MY_KV" id = "xxx" # D1 binding [[d1_databases]] binding = "DB" database_name = "my-db" database_id = "xxx" # R2 binding [[r2_buckets]] binding = "BUCKET" bucket_name = "my-bucket" # Environment variables [vars] API_URL = "https://api.example.com" # Secrets (set via `wrangler secret put`) # Referenced as env.SECRET_NAME in worker code ``` Static assets (for frameworks like Next.js): ```toml name = "my-site" main = ".open-next/worker.js" compatibility_date = "2024-12-30" compatibility_flags = ["nodejs_compat"] [assets] directory = ".open-next/assets" binding = "ASSETS" ``` ## Common Patterns ### Deploy with environment ```bash wrangler deploy -e production wrangler deploy -e staging ``` ### Custom domain (via dashboard or API) Custom domains must be configured in the Cloudflare dashboard under Worker Settings > Domains & Routes, or via the Cloudflare API. Wrangler doesn't directly manage custom domains. ### Local development with bindings ```bash # Creates local D1/KV/R2 for dev wrangler dev --local ``` ### Checking deployment status ```bash wrangler deployments list wrangler deployments view ``` ## What Wrangler Does NOT Do - **DNS management** — Use the Cloudflare dashboard or API for DNS records - **Custom domains** — Configure via dashboard (Worker Settings > Domains & Routes) or API - **SSL certificates** — Managed automatically by Cloudflare when custom domains are added - **Firewall/WAF rules** — Use dashboard or API For DNS/domain management, see the `cloudflare` skill (uses Cloudflare API directly). ## Troubleshooting | Issue | Solution | |-------|----------| | "Not authenticated" | Run `wrangler login` | | Node version error | Requires Node.js v20+ | | "No config found" | Ensure config file exists (`wrangler.toml` or `wrangler.jsonc`) or use `-c path/to/config` | | Config changes ignored | Check for `wrangler.json`/`wrangler.jsonc` — JSON takes precedence over TOML | | Binding not found | Check `wrangler.toml` bindings match code references | ## Resources - [Wrangler Docs](https://developers.cloudflare.com/workers/wrangler/) - [Workers Docs](https://developers.cloudflare.com/workers/) - [D1 Docs](https://developers.cloudflare.com/d1/) - [R2 Docs](https://developers.cloudflare.com/r2/) - [KV Docs](https://developers.cloudflare.com/kv/)