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. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
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. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
metadata
{"version":"0.1.0"}
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.
# 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:
# 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>
# 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
# 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
# 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.
# 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
# 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.
