| 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
- Check the installed Wrangler version or project dependency before writing commands.
- Retrieve current Cloudflare docs or the local
node_modules/wrangler/config-schema.json for flags, config fields, and binding shapes.
- Choose the smallest relevant reference below and verify syntax against docs/schema before running commands.
- Prefer
wrangler.jsonc, generate types after binding/config edits, and validate with local dev, dry-run deploy, or the safest available project check.
- 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:
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.
