cloudflare-deploy

Cloudflare Deploy

Use cf for Cloudflare operations. Use the decision trees below to pick a product, then read its runtime/API references and the current cf CLI guide.

Prerequisites

• Node.js 24+ and pnpm. Install the npm package cf, not @cloudflare/cf.
• Keep cf in project devDependencies and commit the lockfile. The checked example uses [email protected] and @cloudflare/vite-plugin@beta; recheck help and types when upgrading.
• Workers use cloudflare.config.ts. For an existing Wrangler project, run cf migrate --dry-run, then cf migrate and resolve its follow-up items before project commands. Automatic configuration does not import the old bindings.

Authentication (Required Before Deploy)

Verify auth before publishing or mutating account resources:

pnpm exec cf auth whoami

See authentication. Use pnpm exec cf auth login locally; cf has its own login credentials. In CI set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. A deploy dry run needs no credentials.

Discover Commands Before Running Them

pnpm exec cf cli search "create a D1 database"
pnpm exec cf schema d1 create
pnpm exec cf d1 create --help

Describe only the operation and resource type in search queries. Pass names and IDs to the discovered command, not to search. API commands return JSON on stdout and progress on stderr. Resource commands usually use IDs and remote data; inspect --local support instead of copying Wrangler's --remote, --env, --json, or --yes flags.

When to Read references/

Current CLI, migration, configuration and build guidance lives in references/cf/. Product references retain SDK and runtime knowledge; files marked as legacy preserve old CLI/config examples only as migration input. Do not execute those Wrangler examples or generate new Wrangler configuration from them. Translate the intended operation using cf search/schema and typed bindings.

Rules of thumb:

• Picking a product? Use decision trees below, then load references/<picked-product>/
• Writing cloudflare.config.ts? Read configuration first.
• CI/CD setup? Read GitHub Actions.
• Deploy fails? Read cf gotchas, then the product's runtime gotchas.
• The minimal example below covers Workers + KV + secret — for anything beyond that, descend into references

Minimal Worker Example (copy-paste starter)

Start with this Worker, one KV binding and one secret. Apply the TypeScript setup from the configuration reference before typechecking:

// cloudflare.config.ts
import { bindings, defineConfig } from "cf/config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({
  worker: {
    name: "my-worker",
    entrypoint,
    compatibilityDate: "2026-09-30", // Today's date for a new Worker
    observability: { enabled: true },
    env: {
      CACHE: bindings.kv({ id: "REPLACE_WITH_KV_ID" }),
      API_SECRET: bindings.secret(),
    },
  },
});

// vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [cloudflare()] });

// src/index.ts
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const hit = await env.CACHE.get("greeting");
    return new Response(hit ?? "hello");
  }
} satisfies ExportedHandler<Env>;

Bootstrap commands:

pnpm add -D cf @cloudflare/vite-plugin@beta vite typescript
pnpm exec cf kv namespaces create --title CACHE # Copy the returned ID into config
pnpm exec cf workers types                      # Generates .cloudflare/types/index.d.ts
pnpm exec cf dev                                # Vite reports the local URL
pnpm exec cf deploy --dry-run --secrets-file .env.production
pnpm exec cf deploy --secrets-file .env.production

Put API_SECRET in an ignored .env.production for deployment and .dev.vars for local development. Declaring bindings.secret() makes that value required at deploy validation; dotenvx values in the CLI process are not automatically Worker secrets. Include .cloudflare/types in tsconfig.json; see the configuration reference for the full TypeScript setup. Change an existing Worker's compatibility date deliberately.

Live log streaming and legacy Pages asset deployment are not implemented in the checked cf beta, even when a command appears in search/help. Use Workers Logs in the dashboard for inspection and Workers static assets for new web projects. For a legacy Pages project, keep its deployment working while planning migration; do not invent a cf pages deploy replacement. See limitations.

For Pages / D1 / Durable Objects / multi-env / CI — descend into references/.

Quick Decision Trees

"I need to run code"

Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → workers/ (framework) + static-assets/
├─ Maintain or migrate an existing Pages app → pages/ (legacy reference)
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/

"I need to store data"

Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/

"I need AI/ML"

Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/

"I need networking/connectivity"

Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/

"I need security"

Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)

"I need media/content"

Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/

"I need infrastructure-as-code"

Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)

Product Index

Compute & Runtime

Product	Reference
Workers	references/workers/
Pages	references/pages/
Pages Functions	references/pages-functions/
Durable Objects	references/durable-objects/
Workflows	references/workflows/
Containers	references/containers/
Workers for Platforms	references/workers-for-platforms/
Cron Triggers	references/cron-triggers/
Tail Workers	references/tail-workers/
Snippets	references/snippets/
Smart Placement	references/smart-placement/

Storage & Data

Product	Reference
KV	references/kv/
D1	references/d1/
R2	references/r2/
Queues	references/queues/
Hyperdrive	references/hyperdrive/
DO Storage	references/do-storage/
Secrets Store	references/secrets-store/
Pipelines	references/pipelines/
R2 Data Catalog	references/r2-data-catalog/
R2 SQL	references/r2-sql/

AI & Machine Learning

Product	Reference
Workers AI	references/workers-ai/
Vectorize	references/vectorize/
Agents SDK	references/agents-sdk/
AI Gateway	references/ai-gateway/
AI Search	references/ai-search/

Networking & Connectivity

Product	Reference
Tunnel	references/tunnel/
Spectrum	references/spectrum/
TURN	references/turn/
Network Interconnect	references/network-interconnect/
Argo Smart Routing	references/argo-smart-routing/
Workers VPC	references/workers-vpc/

Security

Product	Reference
WAF	references/waf/
DDoS Protection	references/ddos/
Bot Management	references/bot-management/
API Shield	references/api-shield/
Turnstile	references/turnstile/

Media & Content

Product	Reference
Images	references/images/
Stream	references/stream/
Browser Rendering	references/browser-rendering/
Zaraz	references/zaraz/

Real-Time Communication

Product	Reference
RealtimeKit	references/realtimekit/
Realtime SFU	references/realtime-sfu/

Developer Tools

Product	Reference
cf CLI	references/cf/
Miniflare	references/miniflare/
C3	references/c3/
Observability	references/observability/
Analytics Engine	references/analytics-engine/
Web Analytics	references/web-analytics/
Sandbox	references/sandbox/
Workerd	references/workerd/
Workers Playground	references/workers-playground/

Infrastructure as Code

Product	Reference
Pulumi	references/pulumi/
Terraform	references/terraform/
API	references/api/

Other Services

Product	Reference
Email Routing	references/email-routing/
Email Workers	references/email-workers/
Static Assets	references/static-assets/
Bindings	references/bindings/
Cache Reserve	references/cache-reserve/

Troubleshooting

Escalated Network Access

If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use sandbox_permissions=require_escalated). The deploy requires escalated network access when sandbox networking blocks outbound requests.

Example guidance to the user:

The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?