wrangler

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

Task	Command
Local dev	wrangler dev
Deploy	wrangler deploy
View logs	wrangler tail
Add secret	wrangler secret put NAME
List secrets	wrangler secret list
Generate types	wrangler types
Check config	wrangler check startup

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

Flag	Purpose
--x-provision	Force auto-provision resources
--x-auto-create	Auto-create bindings with new resources
--x-autoconfig	Auto-detect framework (Next.js, Remix, etc.)

Environment Variables

Variable	Purpose
CLOUDFLARE_API_TOKEN	Auth for CI/CD
CLOUDFLARE_ACCOUNT_ID	Override account

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

Topic	Reference
All commands	COMMANDS.md
Config options	CONFIG.md
Pages deployment	PAGES.md

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