Wrangler CLI

--- name: Wrangler CLI description: Use this skill when working with Cloudflare Workers - deploying serverless functions, managing KV storage, handling D1 databases, configuring routes, and debugging Workers applications. category: infrastructure metadata: author: skynet version: 1.0.0 --- # Wrangler CLI Cloudflare's command-line tool for managing Workers, KV storage, D1 databases, and other Cloudflare developer platform services. ## Installation & Authentication ```bash # Install Wrangler npm install -g wrangler # Authenticate with Cloudflare wrangler login # Verify authentication wrangler whoami ``` ## Project Initialization ```bash # Create new Worker project wrangler init my-worker wrangler init my-worker --type javascript wrangler init my-worker --type typescript # Initialize in existing directory wrangler init # Create with specific template wrangler init my-api --template worker-typescript wrangler init my-site --template worker-sites ``` ## Development Workflow ```bash # Start local development server wrangler dev # Dev with specific port wrangler dev --port 8787 # Dev with remote resources (KV, D1) wrangler dev --remote # Dev with custom host wrangler dev --host 0.0.0.0 # Test with specific compatibility date wrangler dev --compatibility-date 2023-10-01 ``` ## Deployment Commands ```bash # Deploy to production wrangler deploy # Deploy with custom name wrangler deploy --name my-worker-prod # Deploy specific script wrangler deploy src/worker.js # Deploy with environment variables wrangler deploy --env production # Dry run deployment wrangler deploy --dry-run # Deploy with compatibility flags wrangler deploy --compatibility-flags nodejs_compat ``` ## Environment Management ```bash # List environments wrangler env list # Deploy to specific environment wrangler deploy --env staging wrangler deploy --env production # Example wrangler.toml for environments ``` ```toml name = "my-worker" main = "src/index.js" compatibility_date = "2023-10-01" [env.staging] name = "my-worker-staging" vars = { ENVIRONMENT = "staging" } [env.production] name = "my-worker-prod" vars = { ENVIRONMENT = "production" } routes = ["api.example.com/*"] ``` ## KV Storage Management ```bash # Create KV namespace wrangler kv:namespace create "MY_NAMESPACE" wrangler kv:namespace create "MY_NAMESPACE" --env production # List namespaces wrangler kv:namespace list # Put key-value pair wrangler kv:key put --binding MY_NAMESPACE "key" "value" wrangler kv:key put --binding MY_NAMESPACE "config" '{"api": "v1"}' # Get value wrangler kv:key get --binding MY_NAMESPACE "key" # List keys wrangler kv:key list --binding MY_NAMESPACE # Delete key wrangler kv:key delete --binding MY_NAMESPACE "key" # Bulk operations wrangler kv:bulk put --binding MY_NAMESPACE data.json wrangler kv:bulk delete --binding MY_NAMESPACE keys.json ``` ## D1 Database Management ```bash # Create D1 database wrangler d1 create my-database # List databases wrangler d1 list # Execute SQL commands wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)" wrangler d1 execute my-database --file schema.sql # Query database wrangler d1 execute my-database --command "SELECT * FROM users" # Local D1 development wrangler d1 execute my-database --local --command "INSERT INTO users (name) VALUES ('test')" ``` ## R2 Storage Management ```bash # Create R2 bucket wrangler r2 bucket create my-bucket # List buckets wrangler r2 bucket list # Upload file wrangler r2 object put my-bucket/file.txt --file local-file.txt # Download file wrangler r2 object get my-bucket/file.txt --file downloaded-file.txt # List objects wrangler r2 object list my-bucket # Delete object wrangler r2 object delete my-bucket/file.txt ``` ## Worker Management ```bash # List Workers wrangler list # Get Worker details wrangler status # View logs wrangler tail wrangler tail --format pretty # Delete Worker wrangler delete wrangler delete --name my-worker # Update Worker settings wrangler dispatch-namespace create my-namespace ``` ## Secrets Management ```bash # Set secret wrangler secret put API_KEY wrangler secret put API_KEY --env production # List secrets wrangler secret list # Delete secret wrangler secret delete API_KEY ``` ## Routes & Domains ```bash # List routes wrangler route list # Add route wrangler route add "api.example.com/*" my-worker # Delete route wrangler route delete route-id ``` ## Decision Tree: Deployment Strategy ``` Need to deploy Worker? ├─ First time deployment? │ ├─ Yes → wrangler deploy │ └─ No → Continue below ├─ Multiple environments? │ ├─ Yes → wrangler deploy --env [staging|production] │ └─ No → wrangler deploy ├─ Using external resources (KV, D1)? │ ├─ Yes → Ensure bindings in wrangler.toml → wrangler deploy │ └─ No → wrangler deploy └─ Custom domain/routes? ├─ Yes → Add routes in wrangler.toml or use wrangler route add └─ No → Use default workers.dev subdomain ``` ## Troubleshooting ### Common Errors & Solutions **Error: "No wrangler.toml file found"** ```bash # Solution: Initialize project or create wrangler.toml wrangler init # Or create minimal wrangler.toml: echo 'name = "my-worker"\nmain = "src/index.js"' > wrangler.toml ``` **Error: "Authentication required"** ```bash # Solution: Login to Cloudflare wrangler login # Or use API token export CLOUDFLARE_API_TOKEN="your-token" ``` **Error: "Worker exceeded CPU time limit"** ```bash # Solution: Optimize code or check for infinite loops wrangler tail # Monitor execution # Add compatibility flags if needed ``` **Error: "KV binding not found"** ```bash # Solution: Check wrangler.toml bindings # Add to wrangler.toml: [[kv_namespaces]] binding = "MY_KV" id = "your-namespace-id" ``` **Error: "Module not found" in development** ```bash # Solution: Check module resolution wrangler dev --compatibility-flags nodejs_compat # Or update compatibility_date in wrangler.toml ``` **Error: "Route already exists"** ```bash # Solution: List and remove conflicting routes wrangler route list wrangler route delete <route-id> ``` ### Debug Commands ```bash # Verbose logging wrangler deploy --verbose # Check Worker limits wrangler status --verbose # Validate configuration wrangler deploy --dry-run # Monitor real-time logs wrangler tail --debug ``` ### Configuration Validation ```bash # Test local development wrangler dev --inspect # Verify bindings work wrangler dev --remote # Check compatibility wrangler deploy --compatibility-date 2023-10-01 --dry-run ```