Wrangler¶

Purpose¶

The CLI behind every local dev, D1/R2, and deploy command in this repository.

Version¶

^4.32.0, a devDependency at the repo root - use via npx wrangler or the npm scripts already in package.json; no global install required (and none of the documented commands assume one).

Authentication¶

npx wrangler login       # interactive, opens a browser - for a maintainer's own machine

or, for CI/non-interactive use (what ci.yml/deploy-cloudflare.yml actually use):

export CLOUDFLARE_API_TOKEN=<CLOUDFLARE_API_TOKEN>
export CLOUDFLARE_ACCOUNT_ID=<CLOUDFLARE_ACCOUNT_ID>

Which account am I on?¶

npx wrangler whoami       # [READ-ONLY]

Run this before any --remote/deploy command if you're not certain which Cloudflare account your current auth resolves to - infrastructure/cloudflare/README.md's bootstrap step 1 makes the same point.

Commands used in this repository¶

Command	What it does	Safety
`wrangler dev`	Local dev server for a Worker (its own port, local D1/R2 emulators)	Safe, local
`wrangler deploy --config <path>`	Deploy a Worker to production	MUTATING, PRODUCTION
`wrangler d1 migrations apply <db> --local`	Apply migrations to the local emulator	Safe, local
`wrangler d1 migrations apply <db> --remote --config <path>`	Apply migrations to production D1	REMOTE / MUTATING
`wrangler d1 execute <db> --local/--remote --command "..."`	Run a SQL statement	Safe if `--local`; READ-ONLY-if-SELECT but still REMOTE if `--remote`
`wrangler d1 migrations list <db> --local/--remote`	List applied migrations	Read-only either way
`wrangler r2 bucket create <name>`	Create an R2 bucket	MUTATING - only used once, in `scripts/cloudflare-bootstrap.sh`
`wrangler secret put <NAME> --config <path>`	Set a Worker secret	MUTATING - see CI/CD → Secrets
`wrangler tail --config <path>`	Stream a Worker's live logs	Read-only
`wrangler whoami`	Show current auth identity	Read-only

`$schema` reference¶

Every wrangler.jsonc in this repo references node_modules/wrangler/config-schema.json (relative path varies by nesting depth) - editor autocomplete/validation for the config file, not a runtime dependency.

Troubleshooting¶

See Troubleshooting - the Authentication error [code: 10000] row in particular.

Security considerations¶

CLOUDFLARE_API_TOKEN should be scoped narrowly (Workers Scripts: Edit, D1: Edit, R2: Edit, Zone: Read for the relevant zone only) - see docs/DEPLOYMENT.md §6 "Cloudflare API token rotation" for the exact scope list and rotation procedure.
Never pass CLOUDFLARE_API_TOKEN as a CLI argument (shell history, process list) - always an environment variable, as every command above and every workflow in this repo already does.