cloudflare

# Cloudflare (Wrangler CLI)

Manage Cloudflare Workers and associated services via the `wrangler` CLI.

## Prerequisites

- Node.js v20+ required
- Install: `npm install -g wrangler` or use project-local `npx wrangler`
- Auth: `wrangler login` (opens browser for OAuth)
- Verify: `wrangler whoami`

## Quick Reference

### Workers

```bash
# Initialize new worker
wrangler init <name>

# Local development
wrangler dev [script]

# Deploy
wrangler deploy [script]

# List deployments
wrangler deployments list

# View deployment
wrangler deployments view [deployment-id]

# Rollback
wrangler rollback [version-id]

# Delete worker
wrangler delete [name]

# Tail logs (live)
wrangler tail [worker]
```

### Secrets

```bash
# Add/update secret (interactive)
wrangler secret put <key>

# Add secret from stdin
echo "value" | wrangler secret put <key>

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete <key>

# Bulk upload from JSON file
wrangler secret bulk secrets.json
```

### KV (Key-Value Store)

```bash
# Create namespace
wrangler kv namespace create <name>

# List namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id <id>

# Put key
wrangler kv key put <key> <value> --namespace-id <id>

# Get key
wrangler kv key get <key> --namespace-id <id>

# Delete key
wrangler kv key delete <key> --namespace-id <id>

# List keys
wrangler kv key list --namespace-id <id>

# Bulk operations (JSON file)
wrangler kv bulk put <file> --namespace-id <id>
wrangler kv bulk delete <file> --namespace-id <id>
```

### D1 (SQL Database)

```bash
# Create database
wrangler d1 create <name>

# List databases
wrangler d1 list

# Database info
wrangler d1 info <name>

# Execute SQL
wrangler d1 execute <database> --command "SELECT * FROM users"

# Execute SQL file
wrangler d1 execute <database> --file schema.sql

# Local execution (for dev)
wrangler d1 execute <database> --local --command "..."

# Export database
wrangler d1 export <name> --output backup.sql

# Delete database
wrangler d1 delete <name>

# Migrations
wrangler d1 migrations create <database> <name>
wrangler d1 migrations apply <database>
wrangler d1 migrations list <database>
```

### R2 (Object Storage)

```bash
# Create bucket
wrangler r2 bucket create <name>

# List buckets
wrangler r2 bucket list

# Delete bucket
wrangler r2 bucket delete <name>

# Upload object
wrangler r2 object put <bucket>/<key> --file <path>

# Download object
wrangler r2 object get <bucket>/<key> --file <path>

# Delete object
wrangler r2 object delete <bucket>/<key>
```

### Queues

```bash
# Create queue
wrangler queues create <name>

# List queues
wrangler queues list

# Delete queue
wrangler queues delete <name>
```

## Configuration Files

Wrangler supports both TOML and JSON/JSONC config formats:

- `wrangler.toml` — traditional format
- `wrangler.json` or `wrangler.jsonc` — newer, with JSON schema support

**⚠️ Important:** If both exist, JSON takes precedence. Pick one format to avoid confusion where edits to TOML are ignored.

### JSONC format (with schema autocomplete)

```jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-30"
}
```

### TOML format

```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"
```

With bindings:

```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"

# KV binding
[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

# D1 binding
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"

# R2 binding
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

# Environment variables
[vars]
API_URL = "https://api.example.com"

# Secrets (set via `wrangler secret put`)
# Referenced as env.SECRET_NAME in worker code
```

Static assets (for frameworks like Next.js):

```toml
name = "my-site"
main = ".open-next/worker.js"
compatibility_date = "2024-12-30"
compatibility_flags = ["nodejs_compat"]

[assets]
directory = ".open-next/assets"
binding = "ASSETS"
```

## Common Patterns

### Deploy with environment

```bash
wrangler deploy -e production
wrangler deploy -e staging
```

### Custom domain (via dashboard or API)

Custom domains must be configured in the Cloudflare dashboard under Worker Settings > Domains & Routes, or via the Cloudflare API. Wrangler doesn't directly manage custom domains.

### Local development with bindings

```bash
# Creates local D1/KV/R2 for dev
wrangler dev --local
```

### Checking deployment status

```bash
wrangler deployments list
wrangler deployments view
```

## What Wrangler Does NOT Do

- **DNS management** — Use the Cloudflare dashboard or API for DNS records
- **Custom domains** — Configure via dashboard (Worker Settings > Domains & Routes) or API
- **SSL certificates** — Managed automatically by Cloudflare when custom domains are added
- **Firewall/WAF rules** — Use dashboard or API

For DNS/domain management, see the `cloudflare` skill (uses Cloudflare API directly).

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Not authenticated" | Run `wrangler login` |
| Node version error | Requires Node.js v20+ |
| "No config found" | Ensure config file exists (`wrangler.toml` or `wrangler.jsonc`) or use `-c path/to/config` |
| Config changes ignored | Check for `wrangler.json`/`wrangler.jsonc` — JSON takes precedence over TOML |
| Binding not found | Check `wrangler.toml` bindings match code references |

## Resources

- [Wrangler Docs](https://developers.cloudflare.com/workers/wrangler/)
- [Workers Docs](https://developers.cloudflare.com/workers/)
- [D1 Docs](https://developers.cloudflare.com/d1/)
- [R2 Docs](https://developers.cloudflare.com/r2/)
- [KV Docs](https://developers.cloudflare.com/kv/)