Wrangler CLI

# Wrangler CLI

Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. Prefer retrieval over pre-training for any Wrangler task.

Retrieval Sources

Fetch the latest information before writing or reviewing Wrangler commands and config. 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 |

FIRST: Verify Wrangler Installation

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

If not installed: ```bash npm 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 # Initialize new project npx wrangler init my-worker

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

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

---

Configuration (wrangler.jsonc)

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": "<KV_NAMESPACE_ID>" } ],

// R2 Bucket "r2_buckets": [ { "binding": "BUCKET", "bucket_name": "my-bucket" } ],

// D1 Database "d1_databases": [ { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" } ],

// Workers AI (always remote) "ai": { "binding": "AI" },

// Vectorize "vectorize": [ { "binding": "VECTOR_INDEX", "index_name": "my-index" } ],

// Hyperdrive "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<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 ```

---

Local Development

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

---

Deployment

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

# Rollback to previous version wrangler rollback

# Rollback to specific version wrangler rollback <VERSION_ID> ```

---

KV (Key-Value Store)

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

Manage Keys

```bash # 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

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

---

R2 (Object Storage)

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" } ] } ```

---

D1 (SQL Database)

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": "<DATABASE_ID>", "migrations_dir": "./migrations" } ] } ```

---

Vectorize (Vector Database)

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" } ] } ```

---

Hyperdrive (Database Accelerator)

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

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

# Delete config wrangler hyperdrive delete <HYPERDRIVE_ID> ```

Config Binding

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

---

Workers AI

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.

---

Queues

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 } ] } } ```

---

Containers

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

# Delete container wrangler containers delete <CONTAINER_ID> ```

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 <DOMAIN> \ --public-credential <AWS_ACCESS_KEY_ID>

# Delete registry configuration wrangler containers registries delete <DOMAIN> ```

---

Workflows

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

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

Config Binding

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

---

Pipelines

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" } ] } ```

---

Secrets Store

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

Manage Secrets in Store

```bash # 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

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

---

Pages (Frontend Deployment)

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

---

Observability

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

---

Testing

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

---

Troubleshooting

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

---

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.