7.7 KiB
7.7 KiB
Wrangler Commands for Cloudflare Queues
Complete reference for managing Cloudflare Queues via the wrangler CLI.
Queue Management
Create Queue
npx wrangler queues create <NAME> [OPTIONS]
Options:
--delivery-delay-secs <SECONDS>- Default delay for all messages (0-43200)--message-retention-period-secs <SECONDS>- How long messages persist (60-1209600, default: 345600 / 4 days)
Examples:
# Create basic queue
npx wrangler queues create my-queue
# Create with custom retention (7 days)
npx wrangler queues create my-queue --message-retention-period-secs 604800
# Create with default delivery delay (5 minutes)
npx wrangler queues create delayed-queue --delivery-delay-secs 300
List Queues
npx wrangler queues list
Output:
┌──────────────────┬─────────────┬──────────┐
│ Name │ Consumers │ Messages │
├──────────────────┼─────────────┼──────────┤
│ my-queue │ 1 │ 0 │
│ high-priority │ 2 │ 142 │
│ my-dlq │ 1 │ 5 │
└──────────────────┴─────────────┴──────────┘
Get Queue Info
npx wrangler queues info <NAME>
Example:
npx wrangler queues info my-queue
# Output:
# Queue: my-queue
# Message Retention: 345600 seconds (4 days)
# Delivery Delay: 0 seconds
# Consumers: 1
# - my-consumer (batch_size: 10, batch_timeout: 5s, max_retries: 3)
# Backlog: 0 messages
Update Queue
npx wrangler queues update <NAME> [OPTIONS]
Options:
--delivery-delay-secs <SECONDS>- Update default delay--message-retention-period-secs <SECONDS>- Update retention period
Examples:
# Update retention to 14 days (max)
npx wrangler queues update my-queue --message-retention-period-secs 1209600
# Update delivery delay to 10 minutes
npx wrangler queues update my-queue --delivery-delay-secs 600
Delete Queue
npx wrangler queues delete <NAME>
⚠️ WARNING:
- Deletes ALL messages in the queue
- Cannot be undone
- Use with extreme caution in production
Example:
npx wrangler queues delete old-queue
Consumer Management
Add Consumer
npx wrangler queues consumer add <QUEUE-NAME> <WORKER-SCRIPT-NAME> [OPTIONS]
Options:
--batch-size <NUMBER>- Max messages per batch (1-100, default: 10)--batch-timeout <SECONDS>- Max wait time (0-60, default: 5)--message-retries <NUMBER>- Max retry attempts (0-100, default: 3)--max-concurrency <NUMBER>- Limit concurrent consumers (default: auto-scale to 250)--retry-delay-secs <SECONDS>- Default retry delay--dead-letter-queue <QUEUE-NAME>- DLQ for failed messages
Examples:
# Basic consumer
npx wrangler queues consumer add my-queue my-consumer
# Optimized for high throughput
npx wrangler queues consumer add my-queue my-consumer \
--batch-size 100 \
--batch-timeout 1
# With DLQ and retry settings
npx wrangler queues consumer add my-queue my-consumer \
--batch-size 50 \
--message-retries 5 \
--retry-delay-secs 300 \
--dead-letter-queue my-dlq
# Limit concurrency for rate-limited APIs
npx wrangler queues consumer add api-queue api-consumer \
--max-concurrency 10
Remove Consumer
npx wrangler queues consumer remove <QUEUE-NAME> <WORKER-SCRIPT-NAME>
Example:
npx wrangler queues consumer remove my-queue my-consumer
Queue Operations
Purge Queue
npx wrangler queues purge <QUEUE-NAME>
⚠️ WARNING:
- Permanently deletes ALL messages
- Cannot be undone
- Use for clearing test data or stuck queues
Example:
npx wrangler queues purge test-queue
Pause Delivery
npx wrangler queues pause-delivery <QUEUE-NAME>
Use cases:
- Maintenance on consumer Workers
- Debugging consumer issues
- Temporarily stop processing without deleting messages
Example:
npx wrangler queues pause-delivery my-queue
Resume Delivery
npx wrangler queues resume-delivery <QUEUE-NAME>
Example:
npx wrangler queues resume-delivery my-queue
Event Subscriptions
Event subscriptions automatically send messages to a queue when events occur in other Cloudflare services.
Create Subscription
npx wrangler queues subscription create <QUEUE-NAME> [OPTIONS]
Options:
--source <TYPE>- Event source (kv, r2, superSlurper, vectorize, workersAi.model, workersBuilds.worker, workflows.workflow)--events <EVENTS>- Comma-separated list of event types--name <NAME>- Subscription name (auto-generated if omitted)--enabled- Whether subscription is active (default: true)
Examples:
# Subscribe to R2 bucket events
npx wrangler queues subscription create my-queue \
--source r2 \
--events object-create,object-delete \
--bucket-name my-bucket
# Subscribe to KV namespace events
npx wrangler queues subscription create my-queue \
--source kv \
--events key-write,key-delete \
--namespace-id abc123
# Subscribe to Worker build events
npx wrangler queues subscription create build-queue \
--source workersBuilds.worker \
--events build-complete,build-failed \
--worker-name my-worker
List Subscriptions
npx wrangler queues subscription list <QUEUE-NAME> [OPTIONS]
Options:
--page <NUMBER>- Page number--per-page <NUMBER>- Results per page--json- Output as JSON
Example:
npx wrangler queues subscription list my-queue --json
Get Subscription
npx wrangler queues subscription get <QUEUE-NAME> --id <SUBSCRIPTION-ID> [--json]
Example:
npx wrangler queues subscription get my-queue --id sub_123 --json
Delete Subscription
npx wrangler queues subscription delete <QUEUE-NAME> --id <SUBSCRIPTION-ID>
Example:
npx wrangler queues subscription delete my-queue --id sub_123
Global Flags
These flags work on all commands:
--help- Show help--config <PATH>- Path to wrangler.toml or wrangler.jsonc--cwd <PATH>- Run as if started in specified directory
Complete Workflow Example
# 1. Create queues
npx wrangler queues create my-queue
npx wrangler queues create my-dlq
# 2. Create and deploy producer Worker
cd my-producer
npm create cloudflare@latest -- --type hello-world --ts
# Add producer binding to wrangler.jsonc
npm run deploy
# 3. Create and deploy consumer Worker
cd ../my-consumer
npm create cloudflare@latest -- --type hello-world --ts
# Add consumer handler
npm run deploy
# 4. Add consumer to queue
npx wrangler queues consumer add my-queue my-consumer \
--batch-size 50 \
--message-retries 5 \
--dead-letter-queue my-dlq
# 5. Monitor queue
npx wrangler queues info my-queue
# 6. Watch consumer logs
npx wrangler tail my-consumer
# 7. If needed, pause delivery
npx wrangler queues pause-delivery my-queue
# 8. Resume delivery
npx wrangler queues resume-delivery my-queue
Troubleshooting
Check queue backlog
npx wrangler queues info my-queue | grep "Backlog"
Clear stuck queue
npx wrangler queues purge my-queue
Verify consumer is attached
npx wrangler queues info my-queue | grep "Consumers"
Check for delivery paused
npx wrangler queues info my-queue
# Look for "Delivery: paused"
Last Updated: 2025-10-21 Wrangler Version: 4.43.0+