Wrangler

Cloudflare (Wrangler CLI)

Manage Cloudflare Workers and associated services via the wrangler CLI.

Prerequisites

Quick Reference

Workers

# Initialize new worker
wrangler init 
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

# Add/update secret (interactive)
wrangler secret put 
Add secret from stdin
echo "value" | wrangler secret put 
List secrets
wrangler secret list
Delete secret
wrangler secret delete 
Bulk upload from JSON file
wrangler secret bulk secrets.json

KV (Key-Value Store)

# Create namespace
wrangler kv namespace create 
List namespaces
wrangler kv namespace list
Delete namespace
wrangler kv namespace delete --namespace-id 
Put key
wrangler kv key put   --namespace-id 
Get key
wrangler kv key get  --namespace-id 
Delete key
wrangler kv key delete  --namespace-id 
List keys
wrangler kv key list --namespace-id 
Bulk operations (JSON file)
wrangler kv bulk put  --namespace-id 
wrangler kv bulk delete  --namespace-id 

D1 (SQL Database)

# Create database
wrangler d1 create 
List databases
wrangler d1 list
Database info
wrangler d1 info 
Execute SQL
wrangler d1 execute  --command "SELECT * FROM users"
Execute SQL file
wrangler d1 execute  --file schema.sql
Local execution (for dev)
wrangler d1 execute  --local --command "..."
Export database
wrangler d1 export  --output backup.sql
Delete database
wrangler d1 delete 
Migrations
wrangler d1 migrations create  
wrangler d1 migrations apply 
wrangler d1 migrations list 

R2 (Object Storage)

# Create bucket
wrangler r2 bucket create 
List buckets
wrangler r2 bucket list
Delete bucket
wrangler r2 bucket delete 
Upload object
wrangler r2 object put / --file 
Download object
wrangler r2 object get / --file 
Delete object
wrangler r2 object delete /

Queues

# Create queue
wrangler queues create 
List queues
wrangler queues list
Delete queue
wrangler queues delete 

Configuration Files

Wrangler supports both TOML and JSON/JSONC config formats:

⚠️ Important: If both exist, JSON takes precedence. Pick one format to avoid confusion where edits to TOML are ignored.

JSONC format (with schema autocomplete)

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-30"
}

TOML format

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"

With bindings:

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):

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

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

# Creates local D1/KV/R2 for dev
wrangler dev --local

Checking deployment status

wrangler deployments list
wrangler deployments view

What Wrangler Does NOT Do

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

| 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 |