wrangler

```bash

wrangler --version # Requires v4.x+

```

If not installed:

```bash

npm install -D wrangler@latest

```

• Use wrangler.jsonc: Prefer JSON config over TOML. Newer features are JSON-only.
• Set compatibility_date: Use a recent date (within 30 days). Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/
• Generate types after config changes: Run wrangler types to update TypeScript bindings.
• Local dev defaults to local storage: Bindings use local simulation unless remote: true.
• Validate config before deploy: Run wrangler check to catch errors early.
• Use environments for staging/prod: Define env.staging and env.production in config.

```bash

# Initialize new project

npx wrangler init my-worker

# Or with a framework

npx create-cloudflare@latest my-app

```

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

---

Minimal Config

```jsonc

{

"$schema": "./node_modules/wrangler/config-schema.json",

"name": "my-worker",

"main": "src/index.ts",

"compatibility_date": "2026-01-01"

}

```

Full Config with Bindings

```jsonc

{

"$schema": "./node_modules/wrangler/config-schema.json",

"name": "my-worker",

"main": "src/index.ts",

"compatibility_date": "2026-01-01",

"compatibility_flags": ["nodejs_compat_v2"],

// Environment variables

"vars": {

"ENVIRONMENT": "production"

},

// KV Namespace

"kv_namespaces": [

{ "binding": "KV", "id": "" }

],

// R2 Bucket

"r2_buckets": [

{ "binding": "BUCKET", "bucket_name": "my-bucket" }

],

// D1 Database

"d1_databases": [

{ "binding": "DB", "database_name": "my-db", "database_id": "" }

],

// Workers AI (always remote)

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

// Vectorize

"vectorize": [

{ "binding": "VECTOR_INDEX", "index_name": "my-index" }

],

// Hyperdrive

"hyperdrive": [

{ "binding": "HYPERDRIVE", "id": "" }

],

// Durable Objects

"durable_objects": {

"bindings": [

{ "name": "COUNTER", "class_name": "Counter" }

]

},

// Cron triggers

"triggers": {

"crons": ["0 "]

},

// Environments

"env": {

"staging": {

"name": "my-worker-staging",

"vars": { "ENVIRONMENT": "staging" }

}

}

}

```

Generate Types from Config

```bash

# 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

```

---

Start Dev Server

```bash

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

```jsonc

{

"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

```

---

Deploy Worker

```bash

# 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

```

Manage Secrets

```bash

# 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

```

Versions and Rollback

```bash

# List recent versions

wrangler versions list

# View specific version

wrangler versions view

# Rollback to previous version

wrangler rollback

# Rollback to specific version

wrangler rollback

```

---

Manage Namespaces

```bash

# Create namespace

wrangler kv namespace create MY_KV

# List namespaces

wrangler kv namespace list

# Delete namespace

wrangler kv namespace delete --namespace-id

```

Manage Keys

```bash

# Put value

wrangler kv key put --namespace-id "key" "value"

# Put with expiration (seconds)

wrangler kv key put --namespace-id "key" "value" --expiration-ttl 3600

# Get value

wrangler kv key get --namespace-id "key"

# List keys

wrangler kv key list --namespace-id

# Delete key

wrangler kv key delete --namespace-id "key"

# Bulk put from JSON

wrangler kv bulk put --namespace-id data.json

```

Config Binding

```jsonc

{

"kv_namespaces": [

{ "binding": "CACHE", "id": "" }

]

}

```

---

Manage Buckets

```bash

# 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

```bash

# 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

```jsonc

{

"r2_buckets": [

{ "binding": "ASSETS", "bucket_name": "my-bucket" }

]

}

```

---

Manage Databases

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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

```jsonc

{

"d1_databases": [

{

"binding": "DB",

"database_name": "my-database",

"database_id": "",

"migrations_dir": "./migrations"

}

]

}

```

---

Manage Indexes

```bash

# 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

```bash

# 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

```jsonc

{

"vectorize": [

{ "binding": "SEARCH_INDEX", "index_name": "my-index" }

]

}

```

---

Manage Configs

```bash

# 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

# Update config

wrangler hyperdrive update --origin-password "new-password"

# Delete config

wrangler hyperdrive delete

```

Config Binding

```jsonc

{

"compatibility_flags": ["nodejs_compat_v2"],

"hyperdrive": [

{ "binding": "HYPERDRIVE", "id": "" }

]

}

```

---

List Models

```bash

# List available models

wrangler ai models

# List finetunes

wrangler ai finetune list

```

Config Binding

```jsonc

{

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

}

```

Note: Workers AI always runs remotely and incurs usage charges even in local dev.

---

Manage Queues

```bash

# 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

```jsonc

{

"queues": {

"producers": [

{ "binding": "MY_QUEUE", "queue": "my-queue" }

],

"consumers": [

{

"queue": "my-queue",

"max_batch_size": 10,

"max_batch_timeout": 30

}

]

}

}

```

---

Build and Push Images

```bash

# 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

```bash

# List containers

wrangler containers list

# Get container info

wrangler containers info

# Delete container

wrangler containers delete

```

Manage Images

```bash

# List images in registry

wrangler containers images list

# Delete image

wrangler containers images delete my-app:latest

```

Manage External Registries

```bash

# List configured registries

wrangler containers registries list

# Configure external registry (e.g., ECR)

wrangler containers registries configure \

--public-credential

# Delete registry configuration

wrangler containers registries delete

```

---

Manage Workflows

```bash

# 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

```bash

# List instances

wrangler workflows instances list my-workflow

# Describe instance

wrangler workflows instances describe my-workflow

# Terminate instance

wrangler workflows instances terminate my-workflow

```

Config Binding

```jsonc

{

"workflows": [

{

"binding": "MY_WORKFLOW",

"name": "my-workflow",

"class_name": "MyWorkflow"

}

]

}

```

---

Manage Pipelines

```bash

# 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

```jsonc

{

"pipelines": [

{ "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }

]

}

```

---

Manage Stores

```bash

# Create store

wrangler secrets-store store create my-store

# List stores

wrangler secrets-store store list

# Delete store

wrangler secrets-store store delete

```

Manage Secrets in Store

```bash

# Add secret to store

wrangler secrets-store secret put my-secret

# List secrets in store

wrangler secrets-store secret list

# Get secret

wrangler secrets-store secret get my-secret

# Delete secret from store

wrangler secrets-store secret delete my-secret

```

Config Binding

```jsonc

{

"secrets_store_secrets": [

{

"binding": "MY_SECRET",

"store_id": "",

"secret_name": "my-secret"

}

]

}

```

---

```bash

# 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

```

---

Tail Logs

```bash

# 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

```jsonc

{

"observability": {

"enabled": true,

"head_sampling_rate": 1

}

}

```

---

Local Testing with Vitest

```bash

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

```

vitest.config.ts:

```typescript

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

export default defineWorkersConfig({

test: {

poolOptions: {

workers: {

wrangler: { configPath: "./wrangler.jsonc" },

},

},

},

});

```

Test Scheduled Events

```bash

# Enable in dev

wrangler dev --test-scheduled

# Trigger via HTTP

curl http://localhost:8787/__scheduled

```

---

Common Issues

| Issue | Solution |

|-------|----------|

| command not found: wrangler | Install: npm install -D wrangler |

| Auth errors | Run wrangler login |

| Config validation errors | Run wrangler check |

| Type errors after config change | Run wrangler types |

| Local storage not persisting | Check .wrangler/state directory |

| Binding undefined in Worker | Verify binding name matches config exactly |

Debug Commands

```bash

# Check auth status

wrangler whoami

# Validate config

wrangler check

# View config schema

wrangler docs configuration

```

---

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.
3. Run wrangler types in CI: Add to build step to catch binding mismatches.
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.