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

Requires v4.x+

If not installed:

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

.

Profile Worker startup

Run

wrangler check startup

to measure startup time and detect scripts that exceed the startup time limit.

Use environments for staging/prod

Define env.staging and env.production in config. Quick Start: New Worker

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 Profile Worker startup time wrangler check startup View live logs wrangler tail Delete Worker wrangler delete Auth status wrangler whoami Configuration (wrangler.jsonc) Minimal Config { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-01-01" } Full Config with Bindings { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-01-01", "compatibility_flags": ["nodejs_compat"], // 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

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

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 Deployment Deploy Worker

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

Security

Never pass secret values as command arguments or pipe them via echo . Use the interactive prompt (preferred), pipe from a file, or use secret bulk . Never output, log, or hardcode secret values in commands.

Set secret — interactive prompt (preferred, wrangler will ask for the value securely)

wrangler secret put API_KEY

Set secret from a file (useful for PEM keys, CI environments)

wrangler secret put PRIVATE_KEY < path/to/private-key.pem

List secrets

wrangler secret list

Delete secret

wrangler secret delete API_KEY

Bulk secrets from JSON file (do not commit this file to version control)

wrangler secret bulk secrets.json 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

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": "" } ] } 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" } ] } 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": "", "migrations_dir": "./migrations" } ] } 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" } ] } Hyperdrive (Database Accelerator) Manage Configs

Create config

wrangler hyperdrive create my-hyperdrive \ --origin-host db.example.com \ --origin-port 5432 \ --database my-database \ --origin-user db-user \ --origin-password " $DB_PASSWORD "

Or using a connection string from an environment variable

wrangler hyperdrive create my-hyperdrive \ --connection-string " $HYPERDRIVE_CONNECTION_STRING "

List configs

wrangler hyperdrive list

Get config details

wrangler hyperdrive get < HYPERDRIVE_ID

Update config

wrangler hyperdrive update < HYPERDRIVE_ID

\ --origin-password " $DB_PASSWORD "

Delete config

wrangler hyperdrive delete < HYPERDRIVE_ID

Config Binding { "compatibility_flags": ["nodejs_compat"], "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "" } ] } Workers AI List Models

List available models

wrangler ai models

List finetunes

wrangler ai finetune list

Config Binding

{

"ai":

}

Note

Workers AI always runs remotely and incurs usage charges even in local dev. 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 } ] } } 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

Security

Never hardcode registry credentials in commands. Use environment variables.

List configured registries

wrangler containers registries list

Configure external registry (e.g., ECR)

wrangler containers registries configure < DOMAIN

\ --aws-access-key-id " $AWS_ACCESS_KEY_ID "

Configure DockerHub

wrangler containers registries configure < DOMAIN

\ --dockerhub-username " $DOCKERHUB_USERNAME "

Delete registry configuration

wrangler containers registries delete < DOMAIN

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" } ] } 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" } ] } 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": "", "secret_name": "my-secret" } ] } 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 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 } } Testing Local 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 Troubleshooting Common Issues Issue Solution command not found: wrangler Install: npm install -D wrangler Auth errors Run wrangler login Startup time limit exceeded Run wrangler check startup to profile startup and generate CPU profiles 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

Check auth status

wrangler whoami

Profile Worker startup time

wrangler check startup

View config schema

wrangler docs configuration

Best Practices

Version control

wrangler.jsonc

Treat as source of truth for Worker config.

Use automatic provisioning

Omit resource IDs for auto-creation on deploy.

Run

wrangler types

in CI

Add to build step to catch binding mismatches.

Use environments

Separate staging/production with

env.staging

,

env.production

.

Set

compatibility_date

Update quarterly to get new runtime features.

Use

.dev.vars

for local secrets

Never commit secrets to config.

Test locally first

:

wrangler dev

with local bindings before deploying.

Use

--dry-run

before major deploys

Validate changes without deployment.

Never embed secrets in commands

Use interactive prompts ( wrangler secret put ), file-based input ( wrangler secret bulk ), or secure CI environment variables. Never echo, log, or pass secret values as CLI arguments.