// LLM knowledge base for Cloudflare's Wrangler CLI · Workers · Pages · Queues · Dynamic Workers · Tunnel
#id, a type badge, a one-paragraph description, and chips linking to neighbors. Load this page as context when an LLM needs to reason about Wrangler instead of crawling the docs.
┌─────────────────────────────┐
│ wrangler.toml │
│ (or wrangler.jsonc) │
└────────────┬────────────────┘
│
┌────────────┬────────────┬─────────┴─────────┬────────────┐
▼ ▼ ▼ ▼ ▼
Worker Pages Queues Dynamic Workers Containers
│ │ │ (dispatch ns) │
└─ bindings ─┴─ KV ─ R2 ─ D1 ─ Vectorize ─ AI ─ Hyperdrive ─┘
│
└── Workflows (durable execution) · Cron · DOs
sibling: cloudflared (Tunnel) · companion: c3 (create-cloudflare)
Bootstrap a new project. Modern flow: npm create cloudflare@latest (alias c3) — picks Worker/Pages/Workflow/Queue template, scaffolds.
Local dev server using workerd (the actual edge runtime). Hot reload on save. --remote runs against real edge for real KV/R2/D1.
Push the Worker to production. --env staging for environments. --dispatch-namespace for Workers for Platforms.
Live-tail logs from a deployed Worker. Filter by status, sampling rate, IP. Last-resort prod debugger.
Gradual deploys. upload stages a version without promoting; deploy promotes with a traffic split. Pair with rollback.
Roll back the live deployment to a prior version id. Effectively instant — no rebuild.
OAuth flow with optional --scopes for least-privilege. whoami prints account + scopes. CLOUDFLARE_API_TOKEN bypasses for CI.
Auto-generates worker-configuration.d.ts from your bindings. Re-run after editing wrangler.toml. --x-include-runtime pulls in workers-types.
Encrypted env vars. secret bulk ./secrets.json for upload. Local dev uses .dev.vars file (gitignored).
Sync trigger config (cron, custom domains, routes) without redeploying code.
ESM module exporting handlers — fetch, scheduled, queue, email, tail, trace. Bundled, uploaded, bound to a workers.dev subdomain or custom route.
Static site + optional Functions. wrangler pages {project,deploy,deployment}. Used by every site under organized-ai-hub.
Eventually-consistent key/value. wrangler kv namespace create. Read-after-write may lag tens of seconds globally.
S3-compatible object storage, no egress fees. wrangler r2 bucket create + r2 object put/get/delete.
Serverless SQLite at the edge. wrangler d1 create, execute, migrations create/apply, export.
Durable message bus. wrangler queues create. At-least-once delivery; configure max-retries + DLQ.
Vector index for RAG. wrangler vectorize create --dimensions=1536 --metric=cosine. Insert/query NDJSON or via binding.
Model catalog at the edge. wrangler ai models, ai run @cf/meta/llama-3.1-8b-instruct. Bound as env.AI.run(model, input).
Connection-pool front of Postgres / MySQL — for Workers that need a real RDBMS. wrangler hyperdrive create --connection-string=....
Strongly-consistent stateful actors. One DO instance per id, globally. SQLite-storage DOs are the modern default.
Durable execution — multi-step processes that survive failures. Each step's result is checkpointed; resumes from the last completed step.
Real OCI containers alongside Workers. For ffmpeg, headless Chromium, Python ML — anything that doesn't fit the V8 isolate model.
Holds tenant Workers for Workers for Platforms. wrangler dispatch-namespace create/list/delete. Tenants wrangler deploy --dispatch-namespace=....
Scheduled invocations. Configure under [triggers] crons = [...] in wrangler.toml. Maps to scheduled() handler.
Encrypted env var bound at runtime. Set with wrangler secret put NAME. Local dev mirror is .dev.vars.
env.MY_KV.get(key) · put(key, value, { expirationTtl }) · list({ prefix }). Eventually consistent.
env.MY_BUCKET.put(key, body) · get(key) · list() · delete(key). Multipart for large objects.
env.DB.prepare(sql).bind(args).all() · first() · run() · batch([stmt1, stmt2]). SQLite at the edge.
env.MY_Q.send(msg) · sendBatch([msg1, msg2]). Producer Worker → Queue.
Worker exports queue(batch, env, ctx). Per-message msg.ack() · msg.retry({ delaySeconds }) · DLQ on max-retries.
env.AI.run(model, input). Models are catalog ids like @cf/meta/llama-3.1-8b-instruct · @cf/openai/whisper.
env.IDX.insert([{id, values, metadata}]) · query(vec, { topK }) · getByIds().
env.PG.connectionString — pass to your pg/mysql client. Hyperdrive pools and caches under the hood.
env.NS.idFromName(name).get() returns a stub. stub.fetch(req) routes to that DO instance globally.
Worker → Worker call without leaving Cloudflare's network. env.OTHER.fetch(req). Zero-egress, in-isolate.
env.DISPATCHER.get(scriptName).fetch(req) — load and run a tenant Worker by name. Heart of WFP.
Reach a containerized sidecar from a Worker. Implemented as a class similar to a DO; instances live across Cloudflare's network.
Project-root config. Declares name, main, compatibility_date, compatibility_flags, bindings, environments, triggers, builds.
Local dev secrets file at repo root. Gitignored. Mirrors what wrangler secret put sets in prod.
Auto-generated TS interface for Env — every binding declared in wrangler.toml becomes a typed property. Re-run wrangler types after edits.
Wrangler's local cache + state dir. Local D1 sqlite, KV simulators, build artifacts. Gitignored.
Named environments inside one config file. [env.staging], [env.staging.vars], [[env.staging.kv_namespaces]]. Deploy with --env staging.
Pins runtime semantics. Cloudflare ships breaking changes behind dated flags; compatibility_date freezes you to a known build. Update deliberately.
Opt into / out of specific runtime features (nodejs_compat, web_socket_compression, etc.) independent of date.
Typed handles injected as env.<NAME>. Each Cloudflare resource a Worker uses is declared as a binding. Generates types via wrangler types.
Modern Workers are ESM (export default { fetch }). Service Worker syntax (addEventListener('fetch', …)) is legacy — don't start new projects there.
wrangler dev = workerd locally with stub bindings. wrangler dev --remote = real edge with real KV/R2/D1. Trade speed for fidelity.
Workflows checkpoint each step's result (not local variables). If the Worker dies mid-flow, it resumes from the last completed step. Wrap stateful ops in step.do().
Adding/renaming a DO class needs a migration entry under [[migrations]] with a unique tag. new_sqlite_classes for SQLite-storage DOs.
Stage a version with wrangler versions upload; promote with traffic split via wrangler versions deploy. Roll back instantly with wrangler rollback.
Local: wrangler login OAuth. CI: CLOUDFLARE_API_TOKEN env var with scoped token. Use scopes, not global keys.
Run user-supplied Workers inside your own Worker. Multi-tenant, per-tenant isolated, per-tenant quota. Used by Shopify Hydrogen, Snyk Composer, and similar.
(1) Create dispatch namespace · (2) Tenants wrangler deploy --dispatch-namespace=<ns> · (3) Your dispatch Worker calls env.DISPATCHER.get(name).fetch(req).
Configure outbound = { service = "outbound-proxy" } on the dispatch binding so every fetch() from tenant code is funneled through your proxy Worker — for rate limiting, cost capping, allowlists.
Producer Worker calls env.Q.send(msg). Consumer Worker exports queue(batch, env, ctx). Same Worker can do both.
max_batch_size (count) · max_batch_timeout (seconds, not ms — easy gotcha) · max_batch_bytes.
After max_retries, message moves to dead_letter_queue. Always create the DLQ before going live; otherwise bad batches drop silently.
wrangler queues consumer http add <queue> exposes pull/ack/retry endpoints — for non-Worker consumers (e.g. a process on claw draining the queue).
Outbound-only encrypted tunnel from a private origin (laptop, claw, home-lab) to Cloudflare's edge. Different binary from wrangler; brew install cloudflared.
cloudflared tunnel create my-tunnel mints a UUID and credentials file. list enumerates, delete tears down.
Map a hostname to a tunnel: cloudflared tunnel route dns my-tunnel app.example.com. Creates a CNAME pointing at the tunnel.
Ingress rules — host → local URL. Last rule typically service: http_status:404 as catch-all. Run with cloudflared tunnel run my-tunnel.
Run as a system service (launchd / systemd) so the tunnel stays up across reboots. Pair with service uninstall to tear down.
Worker on edge enforces auth (Cloudflare Access or JWT); Tunnel exposes the origin only to traffic that's already passed. Free WAF + edge rate limiting in front of localhost.
npm create cloudflare@latest. Templated bootstrap for Worker / Pages / Queue / Workflow / Vectorize / D1 projects. Generates wrangler.toml.
The actual Workers runtime, open-source. wrangler dev uses it locally — same code path as production, not a simulator.
Used internally by wrangler dev for binding stubs (KV, R2, D1, DO). Programmatic API for embedding Workers in tests.
Vitest pool that runs tests inside workerd with real bindings. The supported Workers test path.
GitHub Actions wrapper. uses: cloudflare/wrangler-action@v3 + scoped CLOUDFLARE_API_TOKEN.
Ambient TS types for the Workers runtime — Request, Response, KVNamespace, R2Bucket, etc. Re-exported by wrangler types --x-include-runtime.
Canonical reference for every command and config option.
Dispatch namespaces, outbound proxies, tags, tenant management.
Source for wrangler, miniflare, c3, workers-types — all in one monorepo.
Narrative how-to companion to this wiki — install, dev loop, every primitive, queues + dynamic workers + tunnel walkthroughs.