cloudflare

Cloudflare & Wrangler CLI

Manage Cloudflare infrastructure from the terminal: Pages, Workers, KV, R2, D1, Queues, Vectorize, and more.

Prerequisites

# Install
npm install -g wrangler

# Authenticate (opens browser OAuth flow)
wrangler login

# Verify
wrangler whoami

Environment variables (alternative to wrangler login):

• CLOUDFLARE_API_TOKEN — scoped API token (recommended for CI/CD)
• CLOUDFLARE_ACCOUNT_ID — your account ID (found in dashboard URL)

Quick Start

# Deploy a static site to Cloudflare Pages
npm run build && wrangler pages deploy out --project-name mysite

Quick Reference

| Command | Purpose | Example | |---------|---------|---------| | wrangler pages deploy | Deploy static site | wrangler pages deploy out --project-name mysite | | wrangler pages project list | List Pages projects | wrangler pages project list | | wrangler deploy | Deploy Worker | wrangler deploy | | wrangler dev | Local dev server | wrangler dev | | wrangler tail | Stream live logs | wrangler tail my-worker | | wrangler kv namespace list | List KV namespaces | wrangler kv namespace list | | wrangler r2 bucket list | List R2 buckets | wrangler r2 bucket list | | wrangler d1 list | List D1 databases | wrangler d1 list | | wrangler secret put | Set encrypted secret | wrangler secret put API_KEY | | wrangler whoami | Check auth status | wrangler whoami |

Full CLI reference: references/wrangler-commands.md

Pages

Primary use case for static site deployment (Next.js output: 'export', Astro, etc.).

Deploy

# Direct deploy (no git integration needed)
npm run build
wrangler pages deploy out --project-name worldwarwatcher

# With commit tracking
wrangler pages deploy out --project-name mysite --commit-hash $(git rev-parse HEAD) --commit-message "$(git log -1 --format=%s)"

# Preview deploy (non-production branch)
wrangler pages deploy out --project-name mysite --branch staging

Project Management

wrangler pages project create mysite --production-branch main
wrangler pages project list
wrangler pages project delete mysite

Deployment History & Rollback

wrangler pages deployment list --project-name mysite
wrangler pages deployment tail --project-name mysite    # Stream logs

To rollback: redeploy a previous build directory, or use the dashboard to promote an earlier deployment.

Custom Domains

Custom domain management is dashboard-only — wrangler cannot add/remove custom domains for Pages projects. Use the Cloudflare dashboard:

1. Workers & Pages → project → Custom Domains → Add
2. CF auto-creates DNS records and provisions TLS

Pages Config Files

Place _headers and _redirects in your static assets directory (e.g., public/ for Next.js, Astro, Vite) — the build process copies them to the output root.

Details: references/pages-config.md — _headers format, _redirects format, framework presets, preview deploys.

Workers

# Create new Worker project (C3 scaffolding)
npm create cloudflare@latest my-worker

# Local development (with hot reload)
wrangler dev

# Deploy to production
wrangler deploy

# Stream live logs
wrangler tail my-worker

Note: wrangler init is deprecated — use npm create cloudflare@latest instead.

Agents SDK & Code Mode

Build stateful AI agents on Cloudflare Workers with durable state, chat persistence, voice, sub-agents, durable execution, MCP tools, and sandboxed code execution. SDK at agents@0.13.2 (May 2026).

Quick Start

# Scaffold with the starter (includes chat, tools, HITL, scheduling)
npx create-cloudflare@latest --template cloudflare/agents-starter

# Or install packages individually
npm install agents @cloudflare/ai-chat @cloudflare/think @cloudflare/voice @cloudflare/codemode

Class Hierarchy

| Class | Package | Purpose | |-------|---------|---------| | Agent<Env, State> | agents | Base: state, scheduling, fibers, sub-agents, RPC, MCP | | AIChatAgent | @cloudflare/ai-chat | Chat: message persistence, streaming, tool approval, data parts | | Think | @cloudflare/think | Opinionated chat: full agentic loop, extensions, auto-continuation | | withVoice(Agent) | @cloudflare/voice | Mixin: real-time STT/TTS over WebSocket (beta) |

Key Concepts

| Concept | Description | |---------|-------------| | this.subAgent(Class, id) | Spawn co-located child agents with typed RPC and isolated SQLite | | runAgentTool / agentTool | Run sub-agents as retained, streaming tools from a parent | | runFiber() / stash() | Durable execution — work survives DO eviction with checkpoint recovery | | needsApproval | Human-in-the-loop tool approval (5 patterns available) | | this.schedule() / scheduleEvery() | Persistent scheduling: delayed, cron, interval (survives restarts) | | this.retry() | Built-in exponential backoff with jitter | | keepAlive() | Prevent DO eviction during long-running work | | diagnostics_channel | Structured observability across 7 typed event channels | | addMcpServer() | Consume MCP tools via HTTP/SSE or RPC (DO binding, no HTTP overhead) | | createCodeTool() | Code Mode: wraps tools into TypeScript API for LLM-generated code | | DynamicWorkerExecutor | Runs LLM code in isolated V8 sandbox (Dynamic Workers, open beta) | | Chat Recovery | Server turns survive client disconnect, resume on reconnect (v0.12.4+) | | codeMcpServer() | Wrap an MCP server with Code Mode — all tools become typed sandbox APIs |

When to Use

| Need | Approach | |------|----------| | Static API endpoint or cron | Standard Worker (wrangler deploy) | | Custom protocol, non-chat agent | Agent base class | | Chat with full control over agentic loop | AIChatAgent | | Chat with minimal boilerplate | Think (handles everything) | | Voice interaction | withVoice(Agent) or withVoice(AIChatAgent) | | Orchestrating multiple agents | Agent + subAgent() | | LLM composing multiple tools via code | Code Mode (@cloudflare/codemode) | | Durable multi-step workflow | AgentWorkflow (Workflows integration) |

Full API references: references/agents-sdk-core.md, references/agents-sdk-chat-voice.md, references/codemode.md

Storage & Data Services

| Service | Purpose | Key Commands | |---------|---------|-------------| | KV | Key-value store | kv namespace create/list, kv key put/get/list/delete | | R2 | Object storage (S3-compatible) | r2 bucket create/list, r2 object put/get/delete | | D1 | SQLite database | d1 create/list, d1 execute --remote, d1 migrations apply --remote | | Queues | Message queues between Workers | queues create/list/delete, queues consumer add/remove | | Vectorize | Vector DB for AI/embeddings | vectorize create/list/delete, vectorize insert | | Hyperdrive | Connection pooling for external DBs | hyperdrive create/list/delete |

Important: D1 commands default to the local dev database. Add --remote to target production:

wrangler d1 execute my-database --command "SELECT * FROM users" --remote

Full command reference with all flags: references/wrangler-commands.md

Secrets

wrangler secret put SECRET_NAME          # Prompts for value
echo "value" | wrangler secret put SECRET_NAME  # From stdin
wrangler secret list
wrangler secret bulk secrets.json        # Bulk upload

Common Workflows

CI/CD with GitHub Actions

# .github/workflows/deploy.yml
- name: Deploy to Cloudflare Pages
  uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    command: pages deploy out --project-name mysite

Note: In CI/CD (non-interactive), create the project first with wrangler pages project create — auto-creation only works interactively.

Tail Production Logs

``