Wrangler CLI

Deploy, develop, and manage Cloudflare Workers and associated resources.

FIRST: Verify Wrangler Installation

bash
1wrangler --version  # Requires v4.x+

If not installed:

bash
1npm install -D wrangler@latest

Key Guidelines

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

Quick Start: New Worker

bash
1# Initialize new project
2npx wrangler init my-worker
3
4# Or with a framework
5npx create-cloudflare@latest my-app

Quick Reference: Core Commands

Configuration (wrangler.jsonc)

Minimal Config

jsonc
1{
2  "$schema": "./node_modules/wrangler/config-schema.json",
3  "name": "my-worker",
4  "main": "src/index.ts",
5  "compatibility_date": "2026-01-01"
6}

Full Config with Bindings

jsonc
1{
2  "$schema": "./node_modules/wrangler/config-schema.json",
3  "name": "my-worker",
4  "main": "src/index.ts",
5  "compatibility_date": "2026-01-01",
6  "compatibility_flags": ["nodejs_compat_v2"],
7
8  // Environment variables
9  "vars": {
10    "ENVIRONMENT": "production"
11  },
12
13  // KV Namespace
14  "kv_namespaces": [{ "binding": "KV", "id": "<KV_NAMESPACE_ID>" }],
15
16  // R2 Bucket
17  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
18
19  // D1 Database
20  "d1_databases": [
21    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }
22  ],
23
24  // Workers AI (always remote)
25  "ai": { "binding": "AI" },
26
27  // Vectorize
28  "vectorize": [{ "binding": "VECTOR_INDEX", "index_name": "my-index" }],
29
30  // Hyperdrive
31  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }],
32
33  // Durable Objects
34  "durable_objects": {
35    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
36  },
37
38  // Cron triggers
39  "triggers": {
40    "crons": ["0 * * * *"]
41  },
42
43  // Environments
44  "env": {
45    "staging": {
46      "name": "my-worker-staging",
47      "vars": { "ENVIRONMENT": "staging" }
48    }
49  }
50}

Generate Types from Config

bash
1# Generate worker-configuration.d.ts
2wrangler types
3
4# Custom output path
5wrangler types ./src/env.d.ts
6
7# Check types are up to date (CI)
8wrangler types --check

Local Development

Start Dev Server

bash
1# Local mode (default) - uses local storage simulation
2wrangler dev
3
4# With specific environment
5wrangler dev --env staging
6
7# Force local-only (disable remote bindings)
8wrangler dev --local
9
10# Remote mode - runs on Cloudflare edge (legacy)
11wrangler dev --remote
12
13# Custom port
14wrangler dev --port 8787
15
16# Live reload for HTML changes
17wrangler dev --live-reload
18
19# Test scheduled/cron handlers
20wrangler dev --test-scheduled
21# 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
1{
2  "r2_buckets": [
3    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
4  ],
5  "ai": { "binding": "AI", "remote": true },
6  "vectorize": [
7    { "binding": "INDEX", "index_name": "my-index", "remote": true }
8  ]
9}

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

Deployment

Deploy Worker

bash
1# Deploy to production
2wrangler deploy
3
4# Deploy specific environment
5wrangler deploy --env staging
6
7# Dry run (validate without deploying)
8wrangler deploy --dry-run
9
10# Keep dashboard-set variables
11wrangler deploy --keep-vars
12
13# Minify code
14wrangler deploy --minify

Manage Secrets

bash
1# Set secret interactively
2wrangler secret put API_KEY
3
4# Set from stdin
5echo "secret-value" | wrangler secret put API_KEY
6
7# List secrets
8wrangler secret list
9
10# Delete secret
11wrangler secret delete API_KEY
12
13# Bulk secrets from JSON file
14wrangler secret bulk secrets.json

Versions and Rollback

bash
1# List recent versions
2wrangler versions list
3
4# View specific version
5wrangler versions view <VERSION_ID>
6
7# Rollback to previous version
8wrangler rollback
9
10# Rollback to specific version
11wrangler rollback <VERSION_ID>

KV (Key-Value Store)

Manage Namespaces

bash
1# Create namespace
2wrangler kv namespace create MY_KV
3
4# List namespaces
5wrangler kv namespace list
6
7# Delete namespace
8wrangler kv namespace delete --namespace-id <ID>

Manage Keys

bash
1# Put value
2wrangler kv key put --namespace-id <ID> "key" "value"
3
4# Put with expiration (seconds)
5wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600
6
7# Get value
8wrangler kv key get --namespace-id <ID> "key"
9
10# List keys
11wrangler kv key list --namespace-id <ID>
12
13# Delete key
14wrangler kv key delete --namespace-id <ID> "key"
15
16# Bulk put from JSON
17wrangler kv bulk put --namespace-id <ID> data.json

Config Binding

jsonc
1{
2  "kv_namespaces": [{ "binding": "CACHE", "id": "<NAMESPACE_ID>" }]
3}

R2 (Object Storage)

Manage Buckets

bash
1# Create bucket
2wrangler r2 bucket create my-bucket
3
4# Create with location hint
5wrangler r2 bucket create my-bucket --location wnam
6
7# List buckets
8wrangler r2 bucket list
9
10# Get bucket info
11wrangler r2 bucket info my-bucket
12
13# Delete bucket
14wrangler r2 bucket delete my-bucket

Manage Objects

bash
1# Upload object
2wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt
3
4# Download object
5wrangler r2 object get my-bucket/path/file.txt
6
7# Delete object
8wrangler r2 object delete my-bucket/path/file.txt

Config Binding

jsonc
1{
2  "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-bucket" }]
3}

D1 (SQL Database)

Manage Databases

bash
1# Create database
2wrangler d1 create my-database
3
4# Create with location
5wrangler d1 create my-database --location wnam
6
7# List databases
8wrangler d1 list
9
10# Get database info
11wrangler d1 info my-database
12
13# Delete database
14wrangler d1 delete my-database

Execute SQL

bash
1# Execute SQL command (remote)
2wrangler d1 execute my-database --remote --command "SELECT * FROM users"
3
4# Execute SQL file (remote)
5wrangler d1 execute my-database --remote --file ./schema.sql
6
7# Execute locally
8wrangler d1 execute my-database --local --command "SELECT * FROM users"

Migrations

bash
1# Create migration
2wrangler d1 migrations create my-database create_users_table
3
4# List pending migrations
5wrangler d1 migrations list my-database --local
6
7# Apply migrations locally
8wrangler d1 migrations apply my-database --local
9
10# Apply migrations to remote
11wrangler d1 migrations apply my-database --remote

Export/Backup

bash
1# Export schema and data
2wrangler d1 export my-database --remote --output backup.sql
3
4# Export schema only
5wrangler d1 export my-database --remote --output schema.sql --no-data

Config Binding

jsonc
1{
2  "d1_databases": [
3    {
4      "binding": "DB",
5      "database_name": "my-database",
6      "database_id": "<DATABASE_ID>",
7      "migrations_dir": "./migrations"
8    }
9  ]
10}

Vectorize (Vector Database)

Manage Indexes

bash
1# Create index with dimensions
2wrangler vectorize create my-index --dimensions 768 --metric cosine
3
4# Create with preset (auto-configures dimensions/metric)
5wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5
6
7# List indexes
8wrangler vectorize list
9
10# Get index info
11wrangler vectorize get my-index
12
13# Delete index
14wrangler vectorize delete my-index

Manage Vectors

bash
1# Insert vectors from NDJSON file
2wrangler vectorize insert my-index --file vectors.ndjson
3
4# Query vectors
5wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

Config Binding

jsonc
1{
2  "vectorize": [{ "binding": "SEARCH_INDEX", "index_name": "my-index" }]
3}

Hyperdrive (Database Accelerator)

Manage Configs

bash
1# Create config
2wrangler hyperdrive create my-hyperdrive \
3  --connection-string "postgres://user:pass@host:5432/database"
4
5# List configs
6wrangler hyperdrive list
7
8# Get config details
9wrangler hyperdrive get <HYPERDRIVE_ID>
10
11# Update config
12wrangler hyperdrive update <HYPERDRIVE_ID> --origin-password "new-password"
13
14# Delete config
15wrangler hyperdrive delete <HYPERDRIVE_ID>

Config Binding

jsonc
1{
2  "compatibility_flags": ["nodejs_compat_v2"],
3  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }]
4}

Workers AI

List Models

bash
1# List available models
2wrangler ai models
3
4# List finetunes
5wrangler ai finetune list

Config Binding

jsonc
1{
2  "ai": { "binding": "AI" }
3}

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

Queues

Manage Queues

bash
1# Create queue
2wrangler queues create my-queue
3
4# List queues
5wrangler queues list
6
7# Delete queue
8wrangler queues delete my-queue
9
10# Add consumer to queue
11wrangler queues consumer add my-queue my-worker
12
13# Remove consumer
14wrangler queues consumer remove my-queue my-worker

Config Binding

jsonc
1{
2  "queues": {
3    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
4    "consumers": [
5      {
6        "queue": "my-queue",
7        "max_batch_size": 10,
8        "max_batch_timeout": 30
9      }
10    ]
11  }
12}

Containers

Build and Push Images

bash
1# Build container image
2wrangler containers build -t my-app:latest .
3
4# Build and push in one command
5wrangler containers build -t my-app:latest . --push
6
7# Push existing image to Cloudflare registry
8wrangler containers push my-app:latest

Manage Containers

bash
1# List containers
2wrangler containers list
3
4# Get container info
5wrangler containers info <CONTAINER_ID>
6
7# Delete container
8wrangler containers delete <CONTAINER_ID>

Manage Images

bash
1# List images in registry
2wrangler containers images list
3
4# Delete image
5wrangler containers images delete my-app:latest

Manage External Registries

bash
1# List configured registries
2wrangler containers registries list
3
4# Configure external registry (e.g., ECR)
5wrangler containers registries configure <DOMAIN> \
6  --public-credential <AWS_ACCESS_KEY_ID>
7
8# Delete registry configuration
9wrangler containers registries delete <DOMAIN>

Workflows

Manage Workflows

bash
1# List workflows
2wrangler workflows list
3
4# Describe workflow
5wrangler workflows describe my-workflow
6
7# Trigger workflow instance
8wrangler workflows trigger my-workflow
9
10# Trigger with parameters
11wrangler workflows trigger my-workflow --params '{"key": "value"}'
12
13# Delete workflow
14wrangler workflows delete my-workflow

Manage Workflow Instances

bash
1# List instances
2wrangler workflows instances list my-workflow
3
4# Describe instance
5wrangler workflows instances describe my-workflow <INSTANCE_ID>
6
7# Terminate instance
8wrangler workflows instances terminate my-workflow <INSTANCE_ID>

Config Binding

jsonc
1{
2  "workflows": [
3    {
4      "binding": "MY_WORKFLOW",
5      "name": "my-workflow",
6      "class_name": "MyWorkflow"
7    }
8  ]
9}

Pipelines

Manage Pipelines

bash
1# Create pipeline
2wrangler pipelines create my-pipeline --r2 my-bucket
3
4# List pipelines
5wrangler pipelines list
6
7# Show pipeline details
8wrangler pipelines show my-pipeline
9
10# Update pipeline
11wrangler pipelines update my-pipeline --batch-max-mb 100
12
13# Delete pipeline
14wrangler pipelines delete my-pipeline

Config Binding

jsonc
1{
2  "pipelines": [{ "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }]
3}

Secrets Store

Manage Stores

bash
1# Create store
2wrangler secrets-store store create my-store
3
4# List stores
5wrangler secrets-store store list
6
7# Delete store
8wrangler secrets-store store delete <STORE_ID>

Manage Secrets in Store

bash
1# Add secret to store
2wrangler secrets-store secret put <STORE_ID> my-secret
3
4# List secrets in store
5wrangler secrets-store secret list <STORE_ID>
6
7# Get secret
8wrangler secrets-store secret get <STORE_ID> my-secret
9
10# Delete secret from store
11wrangler secrets-store secret delete <STORE_ID> my-secret

Config Binding

jsonc
1{
2  "secrets_store_secrets": [
3    {
4      "binding": "MY_SECRET",
5      "store_id": "<STORE_ID>",
6      "secret_name": "my-secret"
7    }
8  ]
9}

Pages (Frontend Deployment)

bash
1# Create Pages project
2wrangler pages project create my-site
3
4# Deploy directory to Pages
5wrangler pages deploy ./dist
6
7# Deploy with specific branch
8wrangler pages deploy ./dist --branch main
9
10# List deployments
11wrangler pages deployment list --project-name my-site

Observability

Tail Logs

bash
1# Stream live logs
2wrangler tail
3
4# Tail specific Worker
5wrangler tail my-worker
6
7# Filter by status
8wrangler tail --status error
9
10# Filter by search term
11wrangler tail --search "error"
12
13# JSON output
14wrangler tail --format json

Config Logging

jsonc
1{
2  "observability": {
3    "enabled": true,
4    "head_sampling_rate": 1
5  }
6}

Testing

Local Testing with Vitest

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

vitest.config.ts:

typescript
1import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
2
3export default defineWorkersConfig({
4  test: {
5    poolOptions: {
6      workers: {
7        wrangler: { configPath: "./wrangler.jsonc" }
8      }
9    }
10  }
11});

Test Scheduled Events

bash
1# Enable in dev
2wrangler dev --test-scheduled
3
4# Trigger via HTTP
5curl http://localhost:8787/__scheduled

Troubleshooting

Common Issues

Debug Commands

bash
1# Check auth status
2wrangler whoami
3
4# Validate config
5wrangler check
6
7# View config schema
8wrangler docs configuration

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