Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices.
Add this skill
npx mdskills install cloudflare/cloudflare-wranglerComprehensive Wrangler CLI reference with clear command syntax and config examples across all Cloudflare services
1---2name: wrangler3description: Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices.4---56# Wrangler CLI78Deploy, develop, and manage Cloudflare Workers and associated resources.910## FIRST: Verify Wrangler Installation1112```bash13wrangler --version # Requires v4.x+14```1516If not installed:17```bash18npm install -D wrangler@latest19```2021## Key Guidelines2223- **Use `wrangler.jsonc`**: Prefer JSON config over TOML. Newer features are JSON-only.24- **Set `compatibility_date`**: Use a recent date (within 30 days). Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/25- **Generate types after config changes**: Run `wrangler types` to update TypeScript bindings.26- **Local dev defaults to local storage**: Bindings use local simulation unless `remote: true`.27- **Validate config before deploy**: Run `wrangler check` to catch errors early.28- **Use environments for staging/prod**: Define `env.staging` and `env.production` in config.2930## Quick Start: New Worker3132```bash33# Initialize new project34npx wrangler init my-worker3536# Or with a framework37npx create-cloudflare@latest my-app38```3940## Quick Reference: Core Commands4142| Task | Command |43|------|---------|44| Start local dev server | `wrangler dev` |45| Deploy to Cloudflare | `wrangler deploy` |46| Deploy dry run | `wrangler deploy --dry-run` |47| Generate TypeScript types | `wrangler types` |48| Validate configuration | `wrangler check` |49| View live logs | `wrangler tail` |50| Delete Worker | `wrangler delete` |51| Auth status | `wrangler whoami` |5253---5455## Configuration (wrangler.jsonc)5657### Minimal Config5859```jsonc60{61 "$schema": "./node_modules/wrangler/config-schema.json",62 "name": "my-worker",63 "main": "src/index.ts",64 "compatibility_date": "2026-01-01"65}66```6768### Full Config with Bindings6970```jsonc71{72 "$schema": "./node_modules/wrangler/config-schema.json",73 "name": "my-worker",74 "main": "src/index.ts",75 "compatibility_date": "2026-01-01",76 "compatibility_flags": ["nodejs_compat_v2"],7778 // Environment variables79 "vars": {80 "ENVIRONMENT": "production"81 },8283 // KV Namespace84 "kv_namespaces": [85 { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }86 ],8788 // R2 Bucket89 "r2_buckets": [90 { "binding": "BUCKET", "bucket_name": "my-bucket" }91 ],9293 // D1 Database94 "d1_databases": [95 { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }96 ],9798 // Workers AI (always remote)99 "ai": { "binding": "AI" },100101 // Vectorize102 "vectorize": [103 { "binding": "VECTOR_INDEX", "index_name": "my-index" }104 ],105106 // Hyperdrive107 "hyperdrive": [108 { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }109 ],110111 // Durable Objects112 "durable_objects": {113 "bindings": [114 { "name": "COUNTER", "class_name": "Counter" }115 ]116 },117118 // Cron triggers119 "triggers": {120 "crons": ["0 * * * *"]121 },122123 // Environments124 "env": {125 "staging": {126 "name": "my-worker-staging",127 "vars": { "ENVIRONMENT": "staging" }128 }129 }130}131```132133### Generate Types from Config134135```bash136# Generate worker-configuration.d.ts137wrangler types138139# Custom output path140wrangler types ./src/env.d.ts141142# Check types are up to date (CI)143wrangler types --check144```145146---147148## Local Development149150### Start Dev Server151152```bash153# Local mode (default) - uses local storage simulation154wrangler dev155156# With specific environment157wrangler dev --env staging158159# Force local-only (disable remote bindings)160wrangler dev --local161162# Remote mode - runs on Cloudflare edge (legacy)163wrangler dev --remote164165# Custom port166wrangler dev --port 8787167168# Live reload for HTML changes169wrangler dev --live-reload170171# Test scheduled/cron handlers172wrangler dev --test-scheduled173# Then visit: http://localhost:8787/__scheduled174```175176### Remote Bindings for Local Dev177178Use `remote: true` in binding config to connect to real resources while running locally:179180```jsonc181{182 "r2_buckets": [183 { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }184 ],185 "ai": { "binding": "AI", "remote": true },186 "vectorize": [187 { "binding": "INDEX", "index_name": "my-index", "remote": true }188 ]189}190```191192**Recommended remote bindings**: AI (required), Vectorize, Browser Rendering, mTLS, Images.193194### Local Secrets195196Create `.dev.vars` for local development secrets:197198```199API_KEY=local-dev-key200DATABASE_URL=postgres://localhost:5432/dev201```202203---204205## Deployment206207### Deploy Worker208209```bash210# Deploy to production211wrangler deploy212213# Deploy specific environment214wrangler deploy --env staging215216# Dry run (validate without deploying)217wrangler deploy --dry-run218219# Keep dashboard-set variables220wrangler deploy --keep-vars221222# Minify code223wrangler deploy --minify224```225226### Manage Secrets227228```bash229# Set secret interactively230wrangler secret put API_KEY231232# Set from stdin233echo "secret-value" | wrangler secret put API_KEY234235# List secrets236wrangler secret list237238# Delete secret239wrangler secret delete API_KEY240241# Bulk secrets from JSON file242wrangler secret bulk secrets.json243```244245### Versions and Rollback246247```bash248# List recent versions249wrangler versions list250251# View specific version252wrangler versions view <VERSION_ID>253254# Rollback to previous version255wrangler rollback256257# Rollback to specific version258wrangler rollback <VERSION_ID>259```260261---262263## KV (Key-Value Store)264265### Manage Namespaces266267```bash268# Create namespace269wrangler kv namespace create MY_KV270271# List namespaces272wrangler kv namespace list273274# Delete namespace275wrangler kv namespace delete --namespace-id <ID>276```277278### Manage Keys279280```bash281# Put value282wrangler kv key put --namespace-id <ID> "key" "value"283284# Put with expiration (seconds)285wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600286287# Get value288wrangler kv key get --namespace-id <ID> "key"289290# List keys291wrangler kv key list --namespace-id <ID>292293# Delete key294wrangler kv key delete --namespace-id <ID> "key"295296# Bulk put from JSON297wrangler kv bulk put --namespace-id <ID> data.json298```299300### Config Binding301302```jsonc303{304 "kv_namespaces": [305 { "binding": "CACHE", "id": "<NAMESPACE_ID>" }306 ]307}308```309310---311312## R2 (Object Storage)313314### Manage Buckets315316```bash317# Create bucket318wrangler r2 bucket create my-bucket319320# Create with location hint321wrangler r2 bucket create my-bucket --location wnam322323# List buckets324wrangler r2 bucket list325326# Get bucket info327wrangler r2 bucket info my-bucket328329# Delete bucket330wrangler r2 bucket delete my-bucket331```332333### Manage Objects334335```bash336# Upload object337wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt338339# Download object340wrangler r2 object get my-bucket/path/file.txt341342# Delete object343wrangler r2 object delete my-bucket/path/file.txt344```345346### Config Binding347348```jsonc349{350 "r2_buckets": [351 { "binding": "ASSETS", "bucket_name": "my-bucket" }352 ]353}354```355356---357358## D1 (SQL Database)359360### Manage Databases361362```bash363# Create database364wrangler d1 create my-database365366# Create with location367wrangler d1 create my-database --location wnam368369# List databases370wrangler d1 list371372# Get database info373wrangler d1 info my-database374375# Delete database376wrangler d1 delete my-database377```378379### Execute SQL380381```bash382# Execute SQL command (remote)383wrangler d1 execute my-database --remote --command "SELECT * FROM users"384385# Execute SQL file (remote)386wrangler d1 execute my-database --remote --file ./schema.sql387388# Execute locally389wrangler d1 execute my-database --local --command "SELECT * FROM users"390```391392### Migrations393394```bash395# Create migration396wrangler d1 migrations create my-database create_users_table397398# List pending migrations399wrangler d1 migrations list my-database --local400401# Apply migrations locally402wrangler d1 migrations apply my-database --local403404# Apply migrations to remote405wrangler d1 migrations apply my-database --remote406```407408### Export/Backup409410```bash411# Export schema and data412wrangler d1 export my-database --remote --output backup.sql413414# Export schema only415wrangler d1 export my-database --remote --output schema.sql --no-data416```417418### Config Binding419420```jsonc421{422 "d1_databases": [423 {424 "binding": "DB",425 "database_name": "my-database",426 "database_id": "<DATABASE_ID>",427 "migrations_dir": "./migrations"428 }429 ]430}431```432433---434435## Vectorize (Vector Database)436437### Manage Indexes438439```bash440# Create index with dimensions441wrangler vectorize create my-index --dimensions 768 --metric cosine442443# Create with preset (auto-configures dimensions/metric)444wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5445446# List indexes447wrangler vectorize list448449# Get index info450wrangler vectorize get my-index451452# Delete index453wrangler vectorize delete my-index454```455456### Manage Vectors457458```bash459# Insert vectors from NDJSON file460wrangler vectorize insert my-index --file vectors.ndjson461462# Query vectors463wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10464```465466### Config Binding467468```jsonc469{470 "vectorize": [471 { "binding": "SEARCH_INDEX", "index_name": "my-index" }472 ]473}474```475476---477478## Hyperdrive (Database Accelerator)479480### Manage Configs481482```bash483# Create config484wrangler hyperdrive create my-hyperdrive \485 --connection-string "postgres://user:pass@host:5432/database"486487# List configs488wrangler hyperdrive list489490# Get config details491wrangler hyperdrive get <HYPERDRIVE_ID>492493# Update config494wrangler hyperdrive update <HYPERDRIVE_ID> --origin-password "new-password"495496# Delete config497wrangler hyperdrive delete <HYPERDRIVE_ID>498```499500### Config Binding501502```jsonc503{504 "compatibility_flags": ["nodejs_compat_v2"],505 "hyperdrive": [506 { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }507 ]508}509```510511---512513## Workers AI514515### List Models516517```bash518# List available models519wrangler ai models520521# List finetunes522wrangler ai finetune list523```524525### Config Binding526527```jsonc528{529 "ai": { "binding": "AI" }530}531```532533**Note**: Workers AI always runs remotely and incurs usage charges even in local dev.534535---536537## Queues538539### Manage Queues540541```bash542# Create queue543wrangler queues create my-queue544545# List queues546wrangler queues list547548# Delete queue549wrangler queues delete my-queue550551# Add consumer to queue552wrangler queues consumer add my-queue my-worker553554# Remove consumer555wrangler queues consumer remove my-queue my-worker556```557558### Config Binding559560```jsonc561{562 "queues": {563 "producers": [564 { "binding": "MY_QUEUE", "queue": "my-queue" }565 ],566 "consumers": [567 {568 "queue": "my-queue",569 "max_batch_size": 10,570 "max_batch_timeout": 30571 }572 ]573 }574}575```576577---578579## Containers580581### Build and Push Images582583```bash584# Build container image585wrangler containers build -t my-app:latest .586587# Build and push in one command588wrangler containers build -t my-app:latest . --push589590# Push existing image to Cloudflare registry591wrangler containers push my-app:latest592```593594### Manage Containers595596```bash597# List containers598wrangler containers list599600# Get container info601wrangler containers info <CONTAINER_ID>602603# Delete container604wrangler containers delete <CONTAINER_ID>605```606607### Manage Images608609```bash610# List images in registry611wrangler containers images list612613# Delete image614wrangler containers images delete my-app:latest615```616617### Manage External Registries618619```bash620# List configured registries621wrangler containers registries list622623# Configure external registry (e.g., ECR)624wrangler containers registries configure <DOMAIN> \625 --public-credential <AWS_ACCESS_KEY_ID>626627# Delete registry configuration628wrangler containers registries delete <DOMAIN>629```630631---632633## Workflows634635### Manage Workflows636637```bash638# List workflows639wrangler workflows list640641# Describe workflow642wrangler workflows describe my-workflow643644# Trigger workflow instance645wrangler workflows trigger my-workflow646647# Trigger with parameters648wrangler workflows trigger my-workflow --params '{"key": "value"}'649650# Delete workflow651wrangler workflows delete my-workflow652```653654### Manage Workflow Instances655656```bash657# List instances658wrangler workflows instances list my-workflow659660# Describe instance661wrangler workflows instances describe my-workflow <INSTANCE_ID>662663# Terminate instance664wrangler workflows instances terminate my-workflow <INSTANCE_ID>665```666667### Config Binding668669```jsonc670{671 "workflows": [672 {673 "binding": "MY_WORKFLOW",674 "name": "my-workflow",675 "class_name": "MyWorkflow"676 }677 ]678}679```680681---682683## Pipelines684685### Manage Pipelines686687```bash688# Create pipeline689wrangler pipelines create my-pipeline --r2 my-bucket690691# List pipelines692wrangler pipelines list693694# Show pipeline details695wrangler pipelines show my-pipeline696697# Update pipeline698wrangler pipelines update my-pipeline --batch-max-mb 100699700# Delete pipeline701wrangler pipelines delete my-pipeline702```703704### Config Binding705706```jsonc707{708 "pipelines": [709 { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }710 ]711}712```713714---715716## Secrets Store717718### Manage Stores719720```bash721# Create store722wrangler secrets-store store create my-store723724# List stores725wrangler secrets-store store list726727# Delete store728wrangler secrets-store store delete <STORE_ID>729```730731### Manage Secrets in Store732733```bash734# Add secret to store735wrangler secrets-store secret put <STORE_ID> my-secret736737# List secrets in store738wrangler secrets-store secret list <STORE_ID>739740# Get secret741wrangler secrets-store secret get <STORE_ID> my-secret742743# Delete secret from store744wrangler secrets-store secret delete <STORE_ID> my-secret745```746747### Config Binding748749```jsonc750{751 "secrets_store_secrets": [752 {753 "binding": "MY_SECRET",754 "store_id": "<STORE_ID>",755 "secret_name": "my-secret"756 }757 ]758}759```760761---762763## Pages (Frontend Deployment)764765```bash766# Create Pages project767wrangler pages project create my-site768769# Deploy directory to Pages770wrangler pages deploy ./dist771772# Deploy with specific branch773wrangler pages deploy ./dist --branch main774775# List deployments776wrangler pages deployment list --project-name my-site777```778779---780781## Observability782783### Tail Logs784785```bash786# Stream live logs787wrangler tail788789# Tail specific Worker790wrangler tail my-worker791792# Filter by status793wrangler tail --status error794795# Filter by search term796wrangler tail --search "error"797798# JSON output799wrangler tail --format json800```801802### Config Logging803804```jsonc805{806 "observability": {807 "enabled": true,808 "head_sampling_rate": 1809 }810}811```812813---814815## Testing816817### Local Testing with Vitest818819```bash820npm install -D @cloudflare/vitest-pool-workers vitest821```822823`vitest.config.ts`:824```typescript825import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";826827export default defineWorkersConfig({828 test: {829 poolOptions: {830 workers: {831 wrangler: { configPath: "./wrangler.jsonc" },832 },833 },834 },835});836```837838### Test Scheduled Events839840```bash841# Enable in dev842wrangler dev --test-scheduled843844# Trigger via HTTP845curl http://localhost:8787/__scheduled846```847848---849850## Troubleshooting851852### Common Issues853854| Issue | Solution |855|-------|----------|856| `command not found: wrangler` | Install: `npm install -D wrangler` |857| Auth errors | Run `wrangler login` |858| Config validation errors | Run `wrangler check` |859| Type errors after config change | Run `wrangler types` |860| Local storage not persisting | Check `.wrangler/state` directory |861| Binding undefined in Worker | Verify binding name matches config exactly |862863### Debug Commands864865```bash866# Check auth status867wrangler whoami868869# Validate config870wrangler check871872# View config schema873wrangler docs configuration874```875876---877878## Best Practices8798801. **Version control `wrangler.jsonc`**: Treat as source of truth for Worker config.8812. **Use automatic provisioning**: Omit resource IDs for auto-creation on deploy.8823. **Run `wrangler types` in CI**: Add to build step to catch binding mismatches.8834. **Use environments**: Separate staging/production with `env.staging`, `env.production`.8845. **Set `compatibility_date`**: Update quarterly to get new runtime features.8856. **Use `.dev.vars` for local secrets**: Never commit secrets to config.8867. **Test locally first**: `wrangler dev` with local bindings before deploying.8878. **Use `--dry-run` before major deploys**: Validate changes without deployment.888
Full transparency — inspect the skill content before installing.