software-cloudflare-wrangler

name	software-cloudflare-wrangler
description	Guides Cloudflare Wrangler CLI usage for Workers, bindings, deploys, local dev, and config. Use when running or reviewing wrangler commands.
version	1.1
last_validated	2026-07-11T00:00:00.000Z

Wrangler CLI

Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. Prefer retrieval over pre-training for any Wrangler task.

Quick Reference

Task	Read or Run	Outcome
Check install/version and core commands	references/getting-started.md	Current Wrangler source, install, and command basics
Edit config or bindings	references/configuration.md	wrangler.jsonc shape and generated types
Run locally or deploy safely	references/local-development-and-deployment.md	Dev modes, remote bindings, dry runs, secrets, rollbacks
Manage storage/data resources	references/storage-and-data.md	KV, R2, and D1 commands/config
Manage Cloudflare platform services	references/platform-services.md	Vectorize, Hyperdrive, Workers AI, Queues, Containers, Workflows, Pipelines, Secrets Store
Debug, observe, test, or deploy Pages	references/pages-observability-testing.md	Pages, logs, tests, troubleshooting, best practices

Workflow

1. Check the installed Wrangler version or project dependency before writing commands.
2. Retrieve current Cloudflare docs or the local node_modules/wrangler/config-schema.json for flags, config fields, and binding shapes.
3. Choose the smallest relevant reference below and verify syntax against docs/schema before running commands.
4. Prefer wrangler.jsonc, generate types after binding/config edits, and validate with local dev, dry-run deploy, or the safest available project check.
5. Surface any command that can mutate production resources before running it.

Navigation

Need	Read
Install/version check, retrieval sources, core commands	references/getting-started.md
wrangler.jsonc, bindings, environments, generated types	references/configuration.md
Local dev, remote bindings, deploys, secrets, rollbacks	references/local-development-and-deployment.md
KV, R2, and D1 commands/config	references/storage-and-data.md
Vectorize, Hyperdrive, Workers AI, Queues, Containers, Workflows, Pipelines, Secrets Store	references/platform-services.md
Pages, logs, tests, troubleshooting, best practices	references/pages-observability-testing.md

Fact-Checking

• Treat Cloudflare docs and the local Wrangler schema as authoritative.
• Re-check flags, binding shapes, compatibility dates, and newly released products before quoting exact syntax.
• Mark any command unverified if docs or schema cannot be retrieved.
• Treat every specific number in this skill (CPU-ms, MB, GB, $/unit, row counts) as a snapshot that can move between Cloudflare pricing revisions — re-verify at the cited developers.cloudflare.com/<product>/platform/limits/ or .../pricing/ page before it drives a customer-facing estimate or a hard architectural commitment.
• Wrangler itself ships weekly-ish minor/patch releases (v4.x line, e.g. v4.110 as of 2026-07); re-run wrangler --version and npm view wrangler version rather than assuming a specific patch is current. There is no wrangler v5 as of this writing — verify at developers.cloudflare.com/workers/wrangler/.

Expert Judgment

Apply this judgment before reaching for a command — a syntactically correct wrangler invocation on the wrong primitive is still the wrong answer.

When not to reach for Workers at all

• Jobs that run longer than the CPU-time ceiling (10ms/request on Free; up to 5 minutes/request on Paid, configurable via limits.cpu_ms — verify at developers.cloudflare.com/workers/platform/limits/) belong in Containers, Queues consumers with checkpointing, or an external batch system — don't fight the limit with busy-loops or artificial chunking that fragments one logical job across many invocations.
• Payloads or working sets that approach or exceed the 128MB isolate memory ceiling (same on Free and Paid) need Containers, R2 streaming, or an external compute tier — Workers isolates are not a general-purpose memory-heavy runtime.
• Anything that needs a persistent local filesystem, native binaries, GPUs, or a full Linux process model is a Containers workload, not a Worker — Containers reached GA in 2026 with active-CPU pricing (billed for cycles actually consumed, not wall-clock) but they are a genuinely different compute model with real cold starts, unlike Worker isolates. Verify current GA scope and pricing at developers.cloudflare.com/containers/.

Cold-start reality, not folklore

• V8 isolates (Workers) start in low single-digit milliseconds and are effectively "no cold start" for request-serving traffic — that is the architectural reason to prefer a Worker over a container when the workload fits.
• Containers/Sandboxes are real VMs/processes underneath; they have measurable cold-start and warm-pool considerations even at GA. Don't sell Containers with the same latency story as Workers.

Durable Objects: single point of serialization

• Every DO id maps to exactly one instance with single-threaded, serialized execution — it is a strongly-consistent bottleneck by design, not an accident. A single "global" DO id fronting all traffic for a feature will cap that feature's throughput; shard by user/tenant/room/document id instead, and only route to one global DO for state that genuinely must be totally ordered (e.g., a single counter or lock).
• SQLite-backed storage is the default for new DO classes and is the one to reach for; verify at developers.cloudflare.com/durable-objects/what-are-durable-objects/ before assuming legacy key-value-only storage. New classes still need an explicit migration entry (e.g., new_sqlite_classes) in config — DOs do not exist until a migration creates the class.
• DO compute is billed on wall-clock GB-seconds while an instance is active or idle-but-non-hibernating, plus per-request charges; SQLite storage billing (rows read/written, GB stored) mirrors D1's pricing. Verify current thresholds at developers.cloudflare.com/durable-objects/platform/pricing/ — these numbers have moved at least once (SQLite storage billing itself only started being enforced in Jan 2026) and will move again.

KV vs D1 vs Durable Objects — pick by consistency and access shape, not by familiarity

Need	Reach for
Read-heavy, eventually-consistent, small values (config, feature flags, cached HTML)	KV — cheap reads, ~60s global propagation, weak consistency is a feature here
Relational data, per-tenant/per-user SQL, joins within one ~10GB shard	D1 — verify the current per-database size cap at developers.cloudflare.com/d1/platform/limits/; D1 is designed for horizontal fan-out across many small databases, not one large one
Strongly consistent, low-latency coordination or per-entity state (WebSocket room, single-writer document, rate limiter, in-memory-then-flush aggregation)	Durable Objects
Large binary objects, user uploads, static/media assets	R2 — no egress fee, S3-compatible API

D1 vs external Postgres/MySQL — pick D1 when the data naturally partitions per-tenant/per-user and stays under the current per-database size cap with modest write volume. Reach for Hyperdrive-fronted Postgres/MySQL when you need cross-tenant joins, complex analytical queries, existing relational infrastructure, or write volume/size that would require sharding D1 artificially just to fit the cap.

Pages vs Workers — for new projects, Cloudflare has converged the two: a Worker with static assets is the current recommended starting point (single deployment for frontend + backend, full feature parity with Pages for static assets/SSR/custom domains as of 2026). Existing Pages projects remain fully supported with no forced migration deadline — migrate opportunistically when adding substantial backend logic or hitting a Pages-only limitation. Verify current guidance at developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/.

Operating Rules

• Use wrangler.jsonc unless the project already standardizes on another supported config format.
• Run wrangler types after config or binding changes when the project uses TypeScript.
• Use wrangler deploy --dry-run or the safest available validation before production deploys.
• Prefer Wrangler commands over manually constructed Cloudflare API requests when Wrangler supports the operation.
• Never echo secrets; use wrangler secret put or equivalent secure project flow.

Deployment Checklist

Before deploying to production:

• wrangler deploy --dry-run passes without errors
• wrangler types run and generated types committed (TypeScript projects)
• All binding names in wrangler.jsonc match the names used in Worker code
• Secrets set via wrangler secret put — not embedded in config or code
• Compatibility date set explicitly; no unintended compatibility flag changes
• Environment-specific config ([env.production]) verified separately from staging

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.