Wrangler CLI
Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. Prefer retrieval over pre-training for any Wrangler task.
Retrieval Sources
Fetch the latest information before writing or reviewing Wrangler commands and config. Do not rely on baked-in knowledge for CLI flags, config fields, or binding shapes.
| Source |
How to retrieve |
Use for |
| Wrangler docs |
https://developers.cloudflare.com/workers/wrangler/ |
CLI commands, flags, config reference |
| Wrangler config schema |
node_modules/wrangler/config-schema.json |
Config fields, binding shapes, allowed values |
| Cloudflare docs |
Search tool or https://developers.cloudflare.com/workers/ |
API reference, compatibility dates/flags |
Reference Files
Detailed commands and config snippets live in references/. Read the file matching the task:
| Task area |
File |
wrangler.jsonc config, bindings, wrangler types |
references/configuration.md |
wrangler dev, remote bindings, .dev.vars, deploy, secrets, rollback |
references/dev-deploy.md |
| KV, R2, D1 (namespaces, objects, SQL, migrations) |
references/storage.md |
| Vectorize, Hyperdrive, Workers AI |
references/data-ai.md |
| Queues, Containers, Workflows, Pipelines, Secrets Store, Pages |
references/services.md |
wrangler tail, Vitest testing, troubleshooting |
references/observability-testing.md |
FIRST: Check if Wrangler is installed, and if not, install it
Check if Wrangler is installed by running:
wrangler --version # Requires v4.x+
If Wrangler is not installed, you should install it by running:
npm install -D wrangler@latest
Wherever possible, you should use Wrangler instead of manually constructing API requests.
Key Guidelines
- Use
wrangler.jsonc: Prefer JSON config over TOML. Newer features are JSON-only.
- Set
compatibility_date: Use a recent date (within 30 days). Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/
- Generate types after config changes: Run
wrangler types to update TypeScript bindings.
- Local dev defaults to local storage: Bindings use local simulation unless
remote: true.
- Profile Worker startup: Run
wrangler check startup to measure startup time and detect scripts that exceed the startup time limit.
- Use environments for staging/prod: Define
env.staging and env.production in config.
Quick Start: New Worker
# Initialize new project
npx wrangler init my-worker
# Or with a framework
npx create-cloudflare@latest my-app
Quick Reference: Core Commands
| Task |
Command |
| Start local dev server |
wrangler dev |
| Deploy to Cloudflare |
wrangler deploy |
| Deploy dry run |
wrangler deploy --dry-run |
| Generate TypeScript types |
wrangler types |
| Profile Worker startup time |
wrangler check startup |
| View live logs |
wrangler tail |
| Delete Worker |
wrangler delete |
| Auth status |
wrangler whoami |
Best Practices
- Version control
wrangler.jsonc: Treat as source of truth for Worker config.
- Use automatic provisioning: Omit resource IDs for auto-creation on deploy.
- Run
wrangler types in CI: Add to build step to catch binding mismatches.
- Use environments: Separate staging/production with
env.staging, env.production.
- Set
compatibility_date: Update quarterly to get new runtime features.
- Use
.dev.vars for local secrets: Never commit secrets to config.
- Test locally first:
wrangler dev with local bindings before deploying.
- Use
--dry-run before major deploys: Validate changes without deployment.
- Never embed secrets in commands: Use interactive prompts (
wrangler secret put), file-based input (wrangler secret bulk), or secure CI environment variables. Never echo, log, or pass secret values as CLI arguments.
1---2name: wrangler3description: Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.4---56# Wrangler CLI78Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. **Prefer retrieval over pre-training** for any Wrangler task.910## Retrieval Sources1112Fetch the **latest** information before writing or reviewing Wrangler commands and config. Do not rely on baked-in knowledge for CLI flags, config fields, or binding shapes.1314| Source | How to retrieve | Use for |15|--------|----------------|---------|16| Wrangler docs | `https://developers.cloudflare.com/workers/wrangler/` | CLI commands, flags, config reference |17| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |18| Cloudflare docs | Search tool or `https://developers.cloudflare.com/workers/` | API reference, compatibility dates/flags |1920## Reference Files2122Detailed commands and config snippets live in `references/`. Read the file matching the task:2324| Task area | File |25|-----------|------|26| wrangler.jsonc config, bindings, `wrangler types` | `references/configuration.md` |27| `wrangler dev`, remote bindings, `.dev.vars`, deploy, secrets, rollback | `references/dev-deploy.md` |28| KV, R2, D1 (namespaces, objects, SQL, migrations) | `references/storage.md` |29| Vectorize, Hyperdrive, Workers AI | `references/data-ai.md` |30| Queues, Containers, Workflows, Pipelines, Secrets Store, Pages | `references/services.md` |31| `wrangler tail`, Vitest testing, troubleshooting | `references/observability-testing.md` |3233## FIRST: Check if Wrangler is installed, and if not, install it3435Check if Wrangler is installed by running:3637```bash38wrangler --version # Requires v4.x+39```4041If Wrangler is not installed, you should install it by running:4243```bash44npm install -D wrangler@latest45```4647Wherever possible, you should use Wrangler instead of manually constructing API requests.4849## Key Guidelines5051- **Use `wrangler.jsonc`**: Prefer JSON config over TOML. Newer features are JSON-only.52- **Set `compatibility_date`**: Use a recent date (within 30 days). Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/53- **Generate types after config changes**: Run `wrangler types` to update TypeScript bindings.54- **Local dev defaults to local storage**: Bindings use local simulation unless `remote: true`.55- **Profile Worker startup**: Run `wrangler check startup` to measure startup time and detect scripts that exceed the startup time limit.56- **Use environments for staging/prod**: Define `env.staging` and `env.production` in config.5758## Quick Start: New Worker5960```bash61# Initialize new project62npx wrangler init my-worker6364# Or with a framework65npx create-cloudflare@latest my-app66```6768## Quick Reference: Core Commands6970| Task | Command |71|------|---------|72| Start local dev server | `wrangler dev` |73| Deploy to Cloudflare | `wrangler deploy` |74| Deploy dry run | `wrangler deploy --dry-run` |75| Generate TypeScript types | `wrangler types` |76| Profile Worker startup time | `wrangler check startup` |77| View live logs | `wrangler tail` |78| Delete Worker | `wrangler delete` |79| Auth status | `wrangler whoami` |8081## Best Practices82831. **Version control `wrangler.jsonc`**: Treat as source of truth for Worker config.842. **Use automatic provisioning**: Omit resource IDs for auto-creation on deploy.853. **Run `wrangler types` in CI**: Add to build step to catch binding mismatches.864. **Use environments**: Separate staging/production with `env.staging`, `env.production`.875. **Set `compatibility_date`**: Update quarterly to get new runtime features.886. **Use `.dev.vars` for local secrets**: Never commit secrets to config.897. **Test locally first**: `wrangler dev` with local bindings before deploying.908. **Use `--dry-run` before major deploys**: Validate changes without deployment.919. **Never embed secrets in commands**: Use interactive prompts (`wrangler secret put`), file-based input (`wrangler secret bulk`), or secure CI environment variables. Never echo, log, or pass secret values as CLI arguments.
fubira