Wrangler CLI - Cloudflare Workers SDK

Wrangler is the official command-line tool for developing, testing, and deploying Cloudflare Workers. It provides a complete development workflow from local development to production deployment.

Current Version: 4.69.0Wrangler requires Node.js 20.0.0 or higher and is supported on macOS 13.5+, Windows 11, and Linux distros with glib 2.35+.

Installation

Install Wrangler globally or as a project dependency:

# Install globally
npm install -g wrangler

# Or as a dev dependency
npm install --save-dev wrangler

Verify installation:

wrangler --version

Quick Start

Initialize a new Worker project:

wrangler init my-worker -y

This creates a new Worker with:

A wrangler.jsonc configuration file
A basic Worker script in src/index.ts
TypeScript configuration
Package.json with necessary dependencies

Core Features

Local Development

Run your Worker locally with live reloading and Chrome DevTools debugging

One-Click Deploy

Deploy to Cloudflare’s global network with a single command

Resource Management

Create and manage KV namespaces, R2 buckets, D1 databases, and more

Secrets Management

Securely manage environment variables and secrets

Essential Commands

Development

Start a local development server with live reloading:

wrangler dev

The dev server provides:

Hot module reloading for instant updates
Chrome DevTools integration for debugging
Local bindings simulation (KV, R2, D1, Durable Objects)
Request/response inspection

Access DevTools by visiting chrome://inspect in a Chromium-based browser and clicking “inspect” next to your Worker.

Deployment

Deploy your Worker to production:

wrangler deploy

Deploy to a specific environment:

wrangler deploy --env production

By default, Workers are deployed to <worker-name>.<subdomain>.workers.dev. You can add custom domains in the Cloudflare dashboard.

Tail Logs

Stream live logs from your deployed Worker:

wrangler tail

Filter logs by status:

wrangler tail --status error

Configuration

Wrangler uses a wrangler.jsonc, wrangler.json, or wrangler.toml file for configuration. The JSON format is recommended for better IDE support.

Basic Configuration

wrangler.jsonc

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

Configuration with Bindings

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2024-03-01",
  "kv_namespaces": [
    { "binding": "MY_KV", "id": "abc123..." }
  ],
  "r2_buckets": [
    { "binding": "MY_BUCKET", "bucket_name": "my-bucket" }
  ],
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "xyz789..." }
  ],
  "vars": {
    "API_URL": "https://api.example.com"
  }
}

Multi-Environment Configuration

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2024-03-01",
  "vars": {
    "ENVIRONMENT": "development"
  },
  "env": {
    "staging": {
      "vars": {
        "ENVIRONMENT": "staging"
      }
    },
    "production": {
      "vars": {
        "ENVIRONMENT": "production"
      },
      "routes": [
        { "pattern": "example.com/*", "zone_name": "example.com" }
      ]
    }
  }
}

Resource Management

KV Namespaces

Create a KV namespace:

wrangler kv namespace create MY_KV

List namespaces:

wrangler kv namespace list

Manage keys:

# Put a key
wrangler kv key put --binding MY_KV "my-key" "my-value"

# Get a key
wrangler kv key get --binding MY_KV "my-key"

# Delete a key
wrangler kv key delete --binding MY_KV "my-key"

# List all keys
wrangler kv key list --binding MY_KV

R2 Buckets

Create an R2 bucket:

wrangler r2 bucket create my-bucket

List buckets:

wrangler r2 bucket list

Manage objects:

# Put an object
wrangler r2 object put my-bucket/file.txt --file ./local-file.txt

# Get an object
wrangler r2 object get my-bucket/file.txt

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

D1 Databases

Create a D1 database:

wrangler d1 create my-database

Execute SQL:

wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"

Run migrations:

wrangler d1 migrations apply my-database

Queues

Create a queue:

wrangler queues create my-queue

List queues:

wrangler queues list

Secrets Management

Secrets are encrypted environment variables that aren’t visible in your code. Add a secret:

wrangler secret put API_KEY
# You'll be prompted to enter the value

List secrets:

wrangler secret list

Delete a secret:

wrangler secret delete API_KEY

Bulk upload secrets from a file:

wrangler secret bulk .env.production

Deployments & Versions

Gradual Rollouts

Wrangler supports gradual rollouts to test changes with a percentage of traffic:

# Upload a new version without deploying
wrangler versions upload

# Deploy with traffic split
wrangler versions deploy --percentage 10

Rollback

Quickly rollback to a previous deployment:

wrangler rollback

View deployment history:

wrangler deployments list

Advanced Features

Durable Objects

Generate a Durable Object class:

wrangler init my-do --type durable-object

Workers for Platforms

Manage dispatch namespaces:

# Create a namespace
wrangler dispatch-namespace create my-namespace

# List namespaces
wrangler dispatch-namespace list

Analytics Engine

Query analytics data:

wrangler analytics-engine sql --dataset my-dataset --query "SELECT * FROM my-dataset LIMIT 10"

Workflows

Manage Cloudflare Workflows:

# List workflow instances
wrangler workflows list

# Describe a workflow
wrangler workflows describe my-workflow

# Trigger a workflow
wrangler workflows trigger my-workflow

Programmatic API

Wrangler can be used programmatically in Node.js applications:

import { unstable_dev } from "wrangler";

// Start a dev server programmatically
const worker = await unstable_dev("src/index.ts", {
  experimental: { disableExperimentalWarning: true },
});

// Send requests
const response = await worker.fetch("http://localhost");
console.log(await response.text());

// Stop the server
await worker.stop();

Debugging

Chrome DevTools

Wrangler integrates with Chrome DevTools for debugging:

Start dev server with inspector:
wrangler dev --inspector-port 9229
Open chrome://inspect in Chrome
Click “inspect” next to your Worker
Use breakpoints, console, and profiler

Verbose Logging

Enable verbose output for troubleshooting:

wrangler dev --verbose

Configuration Schema

Wrangler provides a JSON schema for IDE autocompletion:

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  // Your IDE will now provide autocomplete and validation
}

Common Workflows

Local Development to Production

Initialize project:
wrangler init my-worker
Develop locally:
wrangler dev

Create resources:

wrangler kv namespace create MY_KV
wrangler d1 create my-db

Update configuration:

wrangler.jsonc

{
  "kv_namespaces": [
    { "binding": "MY_KV", "id": "..." }
  ],
  "d1_databases": [
    { "binding": "DB", "database_id": "..." }
  ]
}

Deploy:
wrangler deploy
Monitor:
wrangler tail

Testing with Different Bindings

Test with local bindings during development:

# Development uses local simulator
wrangler dev

# Preview with production bindings
wrangler dev --remote

Using --remote runs your code on Cloudflare’s network with production bindings. Use carefully to avoid unintended changes.

Best Practices

Use TypeScript

TypeScript provides better IDE support and catches errors before deployment:

wrangler init my-worker --type typescript

Version Control Configuration

Commit wrangler.jsonc but use secrets for sensitive data:

# Good: Use secrets for API keys
wrangler secret put API_KEY

# Bad: Don't put secrets in wrangler.jsonc

Environment-Specific Configuration

Use environments for different deployment targets:

{
  "env": {
    "staging": { ... },
    "production": { ... }
  }
}

Test Before Deploying

Always test locally before deploying:

wrangler dev  # Test locally first
wrangler deploy --dry-run  # Validate without deploying
wrangler deploy  # Deploy to production

Troubleshooting

Common Issues

Authentication errors:

# Login to Cloudflare
wrangler login

# Or use API token
export CLOUDFLARE_API_TOKEN=your-token

Build errors:

# Clear cache and rebuild
rm -rf node_modules/.cache
wrangler deploy

Port already in use:

# Use a different port
wrangler dev --port 8788

​Installation

​Quick Start

​Core Features

Local Development

One-Click Deploy

Resource Management

Secrets Management

​Essential Commands

​Development

​Deployment

​Tail Logs

​Configuration

​Basic Configuration

​Configuration with Bindings

​Multi-Environment Configuration

​Resource Management

​KV Namespaces

​R2 Buckets

​D1 Databases

​Queues

​Secrets Management

​Deployments & Versions

​Gradual Rollouts

​Rollback

​Advanced Features

​Durable Objects

​Workers for Platforms

​Analytics Engine

​Workflows

​Programmatic API

​Debugging

​Chrome DevTools

​Verbose Logging

​Configuration Schema

​Common Workflows

​Local Development to Production

​Testing with Different Bindings

​Best Practices

​Troubleshooting

​Common Issues

​Additional Resources

​Related Tools

Miniflare

Create Cloudflare

Installation

Quick Start

Core Features

Essential Commands

Development

Deployment

Tail Logs

Configuration

Basic Configuration

Configuration with Bindings

Multi-Environment Configuration

Resource Management

KV Namespaces

R2 Buckets

D1 Databases

Queues

Secrets Management

Deployments & Versions

Gradual Rollouts

Rollback

Advanced Features

Durable Objects

Workers for Platforms

Analytics Engine

Workflows

Programmatic API

Debugging

Chrome DevTools

Verbose Logging

Configuration Schema

Common Workflows

Local Development to Production

Testing with Different Bindings

Best Practices

Troubleshooting

Common Issues

Additional Resources

Related Tools