wrangler

name	wrangler
description	Runs Cloudflare Wrangler v4+: wrangler.jsonc, deploy/dev, KV/R2/D1/Vectorize/Hyperdrive/Queues/Workflows/Pages, secrets, types, and tail. Use when editing wrangler config, bindings, or any wrangler command. Not for Cloudflare Agents SDK application code (building-ai-agent-on-cloudflare) or Vercel/Netlify CLIs. Never trust baked-in flag knowledge — fetch developers.cloudflare.com/workers/wrangler first.
version	1.0.1

Wrangler CLI

Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. Prefer retrieval over pre-training for any Wrangler task. Fetch the latest docs before writing or reviewing commands and config.

When to Use

Load this skill whenever you need to:

• Create, deploy, or manage Cloudflare Workers (wrangler init, wrangler deploy, wrangler dev)
• Edit wrangler.jsonc or wrangler.toml configuration files
• Provision or manage bindings: KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Queues, Workflows, Pipelines, Containers, Secrets Store, Durable Objects
• Debug Worker deployment, local dev, or type generation issues
• Run migrations, manage secrets, or tail logs
• Set up Cloudflare Pages projects

Trigger keywords: wrangler, cloudflare workers, wrangler.jsonc, wrangler.toml, worker deploy, kv namespace, r2 bucket, d1 database, vectorize, hyperdrive, workers ai, cloudflare pages, durable objects, wrangler tail, wrangler types.

Prerequisites

1. Node.js installed (LTS recommended).
2. Wrangler v4.x+ installed locally or as a dev dependency.
3. Cloudflare account authenticated via wrangler login or CLOUDFLARE_API_TOKEN env var.
4. On Windows (PowerShell), use npx wrangler or ensure wrangler is in PATH. Line continuations differ: use backtick ` in PowerShell instead of \.

Procedure

1. Verify Installation

wrangler --version  # Requires v4.x+

If not installed:

npm install -D wrangler@latest

2. Retrieve Latest Docs Before Writing Commands

Before writing or reviewing Wrangler commands and config, fetch the latest information. Do not rely on baked-in knowledge for CLI flags, config fields, or binding shapes.

Source	How to retrieve	Use for
Wrangler docs	https://developers.cloudflare.com/workers/wrangler/	CLI commands, flags, config reference
Wrangler config schema	node_modules/wrangler/config-schema.json	Config fields, binding shapes, allowed values
Cloudflare docs	Search tool or https://developers.cloudflare.com/workers/	API reference, compatibility dates/flags

3. Initialize a New Worker

# Initialize new project
npx wrangler init my-worker

# Or with a framework
npx create-cloudflare@latest my-app

4. Configure wrangler.jsonc

Prefer JSON config (wrangler.jsonc) over TOML. Newer features are JSON-only.

Minimal config:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-03-18"
}

Full config with bindings:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-03-18",
  "compatibility_flags": ["nodejs_compat_v2"],

  // Environment variables
  "vars": {
    "ENVIRONMENT": "production"
  },

  // KV Namespace
  "kv_namespaces": [
    { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }
  ],

  // R2 Bucket
  "r2_buckets": [
    { "binding": "BUCKET",   
  

  
   
           
  

  
      

  
   
         
  

  
   
         
  

  
   
     
           
    
  

  
   
     
  

  
   
     
       
          
    
  

5. Generate TypeScript Types After Config Changes

# Generate worker-configuration.d.ts
wrangler types

# Custom output path
wrangler types ./src/env.d.ts

# Check types are up to date (CI)
wrangler types --check

6. Local Development

# Local mode (default) - uses local storage simulation
wrangler dev

# With specific environment
wrangler dev --env staging

# Force local-only (disable remote bindings)
wrangler dev --local

# Remote mode - runs on Cloudflare edge (legacy)
wrangler dev --remote

# Custom port
wrangler dev --port 8787

# Live reload for HTML changes
wrangler dev --live-reload

# Test scheduled/cron handlers
wrangler dev --test-scheduled
# Then visit: http://localhost:8787/__scheduled

Remote bindings for local dev — use remote: true in binding config to connect to real resources while running locally:

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
  ],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [
    { "binding": "INDEX", "index_name": "my-index", "remote": true }
  ]
}

Recommended remote bindings: AI (required), Vectorize, Browser Rendering, mTLS, Images.

Local secrets — create .dev.vars for local development secrets:

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

7. Deploy

# Deploy to production
wrangler deploy

# Deploy specific environment
wrangler deploy --env staging

# Dry run (validate without deploying)
wrangler deploy --dry-run

# Keep dashboard-set variables
wrangler deploy --keep-vars

# Minify code
wrangler deploy --minify

8. Manage Secrets

# Set secret interactively
wrangler secret put API_KEY

# Set from stdin
echo "secret-value" | wrangler secret put API_KEY

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete API_KEY

# Bulk secrets from JSON file
wrangler secret bulk secrets.json

9. Versions and Rollback

# List recent versions
wrangler versions list

# View specific version
wrangler versions view <VERSION_ID>

# Rollback to previous version
wrangler rollback

# Rollback to specific version
wrangler rollback <VERSION_ID>

10. KV (Key-Value Store)

Manage namespaces:

# Create namespace
wrangler kv namespace create MY_KV

# List namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id <ID>

Manage keys:

# Put value
wrangler kv key put --namespace-id <ID> "key" "value"

# Put with expiration (seconds)
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# Get value
wrangler kv key get --namespace-id <ID> "key"

# List keys
wrangler kv key list --namespace-id <ID>

# Delete key
wrangler kv key delete --namespace-id <ID> "key"

# Bulk put from JSON
wrangler kv bulk put --namespace-id <ID> data.json

Config binding:

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<NAMESPACE_ID>" }
  ]
}

11. R2 (Object Storage)

Manage buckets:

# Create bucket
wrangler r2 bucket create my-bucket

# Create with location hint
wrangler r2 bucket create my-bucket --location wnam

# List buckets
wrangler r2 bucket list

# Get bucket info
wrangler r2 bucket info my-bucket

# Delete bucket
wrangler r2 bucket delete my-bucket

Manage objects:

# Upload object
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# Download object
wrangler r2 object get my-bucket/path/file.txt

# Delete object
wrangler r2 object delete my-bucket/path/file.txt

Config binding:

{
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-bucket" }
  ]
}

12. D1 (SQL Database)

Manage databases:

# Create database
wrangler d1 create my-database

# Create with location
wrangler d1 create my-database --location wnam

# List databases
wrangler d1 list

# Get database info
wrangler d1 info my-database

# Delete database
wrangler d1 delete my-database

Execute SQL:

# Execute SQL command (remote)
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# Execute SQL file (remote)
wrangler d1 execute my-database --remote --file ./schema.sql

# Execute locally
wrangler d1 execute my-database --local --command "SELECT * FROM users"

Migrations:

# Create migration
wrangler d1 migrations create my-database create_users_table

# List pending migrations
wrangler d1 migrations list my-database --local

# Apply migrations locally
wrangler d1 migrations apply my-database --local

# Apply migrations to remote
wrangler d1 migrations apply my-database --remote

Export/Backup:

# Export schema and data
wrangler d1 export my-database --remote --output backup.sql

# Export schema only
wrangler d1 export my-database --remote --output schema.sql --no-data

Config binding:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"
    }
  ]
}

13. Vectorize (Vector Database)

Manage indexes:

# Create index with dimensions
wrangler vectorize create my-index --dimensions 768 --metric cosine

# Create with preset (auto-configures dimensions/metric)
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# List indexes
wrangler vectorize list

# Get index info
wrangler vectorize get my-index

# Delete index
wrangler vectorize delete my-index

Manage vectors:

# Insert vectors from NDJSON file
wrangler vectorize insert my-index --file vectors.ndjson

# Query vectors
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

Config binding:

{
  "vectorize": [
    { "binding": "SEARCH_INDEX", "index_name": "my-index" }
  ]
}

14. Hyperdrive (Database Accelerator)

Manage configs:

# Create config
wrangler hyperdrive create my-hyperdrive --connection-string "postgres://user:pass@host:5432/database"

# List configs
wrangler hyperdrive list

# Get config details
wrangler hyperdrive get <HYPERDRIVE_ID>

# Update config
wrangler hyperdrive update <HYPERDRIVE_ID> --origin-password "new-password"

# Delete config
wrangler hyperdrive delete <HYPERDRIVE_ID>

Config binding:

{
  "compatibility_flags": ["nodejs_compat_v2"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ]
}

15. Workers AI

# List available models
wrangler ai models

# List finetunes
wrangler ai finetune list

Config binding:

{
  "ai": { "binding": "AI" }
}

HARD RULE: Workers AI always runs remotely and incurs usage charges even in local dev. Never assume local simulation for AI bindings.

16. Queues

Manage queues:

# Create queue
wrangler queues create my-queue

# List queues
wrangler queues list

# Delete queue
wrangler queues delete my-queue

# Add consumer to queue
wrangler queues consumer add my-queue my-worker

# Remove consumer
wrangler queues consumer remove my-queue my-worker

Config binding:

{
  "queues": {
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue" }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30
      }
    ]
  }
}

17. Containers

Build and push images:

# Build container image
wrangler containers build -t my-app:latest .

# Build and push in one command
wrangler containers build -t my-app:latest . --push

# Push existing image to Cloudflare registry
wrangler containers push my-app:latest

Manage containers:

# List containers
wrangler containers list

# Get container info
wrangler containers info <CONTAINER_ID>

# Delete container
wrangler containers delete <CONTAINER_ID>

Manage images:

# List images in registry
wrangler containers images list

# Delete image
wrangler containers images delete my-app:latest

Manage external registries:

# List configured registries
wrangler containers registries list

# Configure external registry (e.g., ECR)
wrangler containers registries configure <DOMAIN> --public-credential <AWS_ACCESS_KEY_ID>

# Delete registry configuration
wrangler containers registries delete <DOMAIN>

18. Workflows

Manage workflows:

# List workflows
wrangler workflows list

# Describe workflow
wrangler workflows describe my-workflow

# Trigger workflow instance
wrangler workflows trigger my-workflow

# Trigger with parameters
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Delete workflow
wrangler workflows delete my-workflow

Manage workflow instances:

# List instances
wrangler workflows instances list my-workflow

# Describe instance
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# Terminate instance
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

Config binding:

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

19. Pipelines

Manage pipelines:

# Create pipeline
wrangler pipelines create my-pipeline --r2 my-bucket

# List pipelines
wrangler pipelines list

# Show pipeline details
wrangler pipelines show my-pipeline

# Update pipeline
wrangler pipelines update my-pipeline --batch-max-mb 100

# Delete pipeline
wrangler pipelines delete my-pipeline

Config binding:

{
  "pipelines": [
    { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }
  ]
}

20. Secrets Store

Manage stores:

# Create store
wrangler secrets-store store create my-store

# List stores
wrangler secrets-store store list

# Delete store
wrangler secrets-store store delete <STORE_ID>

Manage secrets in store:

# Add secret to store
wrangler secrets-store secret put <STORE_ID> my-secret

# List secrets in store
wrangler secrets-store secret list <STORE_ID>

# Get secret
wrangler secrets-store secret get <STORE_ID> my-secret

# Delete secret from store
wrangler secrets-store secret delete <STORE_ID> my-secret

Config binding:

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret"
    }
  ]
}

21. Pages (Frontend Deployment)

# Create Pages project
wrangler pages project create my-site

# Deploy directory to Pages
wrangler pages deploy ./dist

# Deploy with specific branch
wrangler pages deploy ./dist --branch main

# List deployments
wrangler pages deployment list --project-name my-site

22. Observability

Tail logs:

# Stream live logs
wrangler tail

# Tail specific Worker
wrangler tail my-worker

# Filter by status
wrangler tail --status error

# Filter by search term
wrangler tail --search "error"

# JSON output
wrangler tail --format json

Config logging:

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

23. Testing with Vitest

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts:

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

Test scheduled events:

# Enable in dev
wrangler dev --test-scheduled

# Trigger via HTTP
curl http://localhost:8787/__scheduled

Pitfalls

Issue	Solution
command not found: wrangler	Install: npm install -D wrangler
Auth errors	Run wrangler login or set CLOUDFLARE_API_TOKEN
Config validation errors	Run wrangler check before deploy
Type errors after config change	Run wrangler types to regenerate bindings
Local storage not persisting	Check .wrangler/state directory exists and is writable
Binding undefined in Worker	Verify binding name in code matches config binding field exactly
Workers AI charges in local dev	AI always runs remotely; there is no local simulation
compatibility_date too old	Update to a date within 30 days of today; check compatibility dates docs
TOML config missing newer features	Switch to wrangler.jsonc; newer features are JSON-only
Secrets committed to config	Use .dev.vars for local secrets; use wrangler secret put for production
PowerShell line continuation errors	Use backtick ` instead of \ for multi-line commands on Windows
Binding name mismatch	The binding field in config must match the property accessed on env in code

HARD RULES:

1. Never commit real secrets to wrangler.jsonc, .dev.vars, or any tracked file. Use wrangler secret put for production and .dev.vars (gitignored) for local dev.
2. Always run wrangler types after changing any binding in config. Stale types cause silent runtime errors.
3. Always run wrangler deploy --dry-run before major deploys to validate without pushing.
4. Workers AI is always remote — it incurs charges even during wrangler dev. Never assume local simulation.
5. Prefer retrieval over pre-training — Wrangler CLI flags and config fields change frequently. Fetch docs before writing commands.
6. Use wrangler.jsonc over wrangler.toml — newer features are JSON-only.
7. Never delete resources (KV namespaces, R2 buckets, D1 databases, Vectorize indexes) without explicit user confirmation. Data loss is irreversible.

Verification

Check Wrangler Version

wrangler --version
# Expected: 4.x.x or higher

Check Auth Status

wrangler whoami
# Expected: shows account email and account ID

Validate Config

wrangler check
# Expected: no errors; config is valid

Verify Types Are Current

wrangler types --check
# Expected: exit code 0 if types match config

Dry-Run Deploy

wrangler deploy --dry-run
# Expected: build succeeds, no deployment made, shows bundle size

Verify Local Dev Server

wrangler dev --port 8787
# Expected: server starts on http://localhost:8787
# Then in another terminal:
curl http://localhost:8787/

Verify Bindings Are Accessible

Check that generated types include your bindings:

wrangler types
# Then inspect worker-configuration.d.ts for expected binding names

Verify KV Namespace

wrangler kv namespace list
# Expected: lists all KV namespaces with IDs

Verify D1 Migration Status

wrangler d1 migrations list my-database --local
# Expected: shows applied and pending migrations

Best Practices

1. Version control wrangler.jsonc — treat as source of truth for Worker config.
2. Use automatic provisioning — omit resource IDs for auto-creation on deploy where supported.
3. Run wrangler types in CI — add to build step to catch binding mismatches early.
4. Use environments — separate staging/production with env.staging, env.production.
5. Set compatibility_date — update quarterly to get new runtime features.
6. Use .dev.vars for local secrets — never commit secrets to config.
7. Test locally first — wrangler dev with local bindings before deploying.
8. Use --dry-run before major deploys — validate changes without deployment.

Quick Reference: Core Commands

Task	Command
Start local dev server	wrangler dev
Deploy to Cloudflare	wrangler deploy
Deploy dry run	wrangler deploy --dry-run
Generate TypeScript types	wrangler types
Validate configuration	wrangler check
View live logs	wrangler tail
Delete Worker	wrangler delete
Auth status	wrangler whoami