Using Wrangler

Version: 4.59.2+ (Jan 2026). Config format: wrangler.jsonc recommended over .toml.

Quick Start

# Create new project
npx create-cloudflare@latest my-worker

# Local dev
wrangler dev

# Deploy
wrangler deploy

# View logs
wrangler tail

THE EXACT PROMPT — Deploy a Worker

Deploy Worker to Cloudflare:
1. Check wrangler.jsonc exists with name, main, compatibility_date
2. wrangler deploy (auto-provisions KV/R2/D1 bindings if IDs missing)
3. wrangler tail to verify

Core Commands

Config (wrangler.jsonc)

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",

  // Routes
  "routes": [
    { "pattern": "example.com/*", "zone_name": "example.com" }
  ],

  // Bindings (IDs optional - auto-provisioned on deploy)
  "kv_namespaces": [{ "binding": "KV", "id": "..." }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_id": "..." }],

  // Environment variables
  "vars": { "ENV": "production" }
}

Auto-Provisioning (v4.57+)

Add bindings WITHOUT IDs — Wrangler creates resources on deploy:

{
  "kv_namespaces": [{ "binding": "CACHE" }],  // No id - auto-created
  "r2_buckets": [{ "binding": "ASSETS" }],    // No bucket_name - auto-created
  "d1_databases": [{ "binding": "DB" }]       // No database_id - auto-created
}

Hidden/Experimental Flags

Environment Variables

Decision Tree

What to do?
├─ New project → npx create-cloudflare@latest
├─ Local dev → wrangler dev
├─ Deploy → wrangler deploy
├─ Add secret → wrangler secret put NAME
├─ View logs → wrangler tail
├─ Database ops → wrangler d1 ...
├─ Storage ops → wrangler r2 ... or wrangler kv ...
└─ Scheduled jobs → Add [triggers] to config

Common Patterns

Add a Secret

wrangler secret put API_KEY
# Enter value when prompted (or pipe: echo "value" | wrangler secret put API_KEY)

Multiple Environments

{
  "name": "my-worker",
  "env": {
    "staging": {
      "vars": { "ENV": "staging" },
      "routes": [{ "pattern": "staging.example.com/*" }]
    },
    "production": {
      "vars": { "ENV": "production" },
      "routes": [{ "pattern": "example.com/*" }]
    }
  }
}

wrangler deploy --env staging
wrangler deploy --env production

D1 Database

wrangler d1 create my-db
wrangler d1 execute my-db --file schema.sql
wrangler d1 execute my-db --command "SELECT * FROM users"

R2 Storage

wrangler r2 bucket create my-bucket
wrangler r2 object put my-bucket/file.txt --file ./local.txt
wrangler r2 object get my-bucket/file.txt

AGENTS.md Blurb

Copy this to your project's AGENTS.md:

### Cloudflare Wrangler

Wrangler is installed and authenticated.

R2 bucket: `<BUCKET_NAME>`
Account ID: `<ACCOUNT_ID>`

Common commands:

\`\`\`bash
wrangler r2 object put <BUCKET>/<path> --file ./local-file
wrangler r2 object get <BUCKET>/<path> --file ./downloaded
wrangler r2 bucket list
wrangler d1 execute <DB> --command "SELECT * FROM users"
wrangler deploy
\`\`\`

Reference Index

Gotchas

• Dashboard changes overwritten: Add "keep_vars": true to preserve dashboard edits
• Secrets not in config: Use wrangler secret put, never put secrets in config
• Types outdated: Run wrangler types after config changes
• Old compatibility_date: Update yearly for new features

Sources

• Repo: cloudflare/workers-sdk @ v4.59.2
• Docs: developers.cloudflare.com/workers/wrangler