wrangler

# 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 | ## FIRST: Verify Wrangler Installation ```bash wrangler --version # Requires v4.x+ ``` If not installed: ```bash npm install -D wrangler@latest ``` ## 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`. - **Validate config before deploy**: Run `wrangler check` to catch errors early. - **Use environments for staging/prod**: Define `env.staging` and `env.production` in config. ## Quick Start: New Worker ```bash # 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` | | Validate configuration | `wrangler check` | | View live logs | `wrangler tail` | | Delete Worker | `wrangler delete` | | Auth status | `wrangler whoami` | --- ## Configuration (wrangler.jsonc) ### Minimal Config ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-03-18" } ``` ### Full Config with Bindings ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-03-18", "compatibility_flags": ["nodejs_compat_v2"], // Environment variables "vars": { "ENVIRONMENT": "production" }, // KV Namespace "kv_namespaces": [ { "binding": "KV", "id": "<KV_NAMESPACE_ID>" } ], // R2 Bucket "r2_buckets": [ { "binding": "BUCKET", "bucket_name": "my-bucket" } ], // D1 Database "d1_databases": [ { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" } ], // Workers AI (always remote) "ai": { "binding": "AI" }, // Vectorize "vectorize": [ { "binding": "VECTOR_INDEX", "index_name": "my-index" } ], // Hyperdrive "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" } ], // Durable Objects "durable_objects": { "bindings": [ { "name": "COUNTER", "class_name": "Counter" } ] }, // Cron triggers "triggers": { "crons": ["0 * * * *"] }, // Environments "env": { "staging": { "name": "my-worker-staging", "vars": { "ENVIRONMENT": "staging" } } } } ``` ### Generate Types from Config ```bash # Generate worker-configuration.d.ts wrangler types # Custom output path wrangler types ./src/env.d.ts # Check types are up to date (CI) wrangler types --check ``` --- ## Local Development ### Start Dev Server ```bash # Local mode (default) - uses local storage simulation wrangler dev # With specific environment wrangler dev --env staging # Force local-only (disable remote bindings) wrangler dev --local # Remote mode - runs on Cloudflare edge (legacy) wrangler dev --remote # Custom port wrangler dev --port 8787 # Live reload for HTML changes wrangler dev --live-reload # Test scheduled/cron handlers wrangler dev --test-scheduled # Then visit: http://localhost:8787/__scheduled ``` ### Remote Bindings for Local Dev Use `remote: true` in binding config to connect to real resources while running locally: ```jsonc { "r2_buckets": [ { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true } ], "ai": { "binding": "AI", "remote": true }, "vectorize": [ { "binding": "INDEX", "index_name": "my-index", "remote": true } ] } ``` **Recommended remote bindings**: AI (required), Vectorize, Browser Rendering, mTLS, Images. ### Local Secrets Create `.dev.vars` for local development secrets: ``` API_KEY=local-dev-key DATABASE_URL=postgres://localhost:5432/dev ``` --- ## Deployment ### Deploy Worker ```bash # Deploy to production wrangler deploy # Deploy specific environment wrangler deploy --env staging # Dry run (validate without deploying) wrangler deploy --dry-run # Keep dashboard-set variables wrangler deploy --keep-vars # Minify code wrangler deploy --minify ``` ### Manage Secrets ```bash # Set secret interactively wrangler secret put API_KEY # Set from stdin echo "secret-value" | wrangler secret put API_KEY # List secrets wrangler secret list # Delete secret wrangler secret delete API_KEY # Bulk secrets from JSON file wrangler secret bulk secrets.json ``` ### Versions and Rollback ```bash # List recent versions wrangler versions list # View specific version wrangler versions view <VERSION_ID> # Rollback to previous version wrangler rollback # Rollback to specific version wrangler rollback <VERSION_ID> ``` --- ## KV (Key-Value Store) ### Manage Namespaces ```bash # Create namespace wrangler kv namespace create MY_KV # List namespaces wrangler kv namespace list # Delete namespace wrangler kv namespace delete --namespace-id <ID> ``` ### Manage Keys ```bash # Put value wrangler kv key put --namespace-id <ID> "key" "value" # Put with expiration (seconds) wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600 # Get value wrangler kv key get --namespace-id <ID> "key" # List keys wrangler kv key list --namespace-id <ID> # Delete key wrangler kv key delete --namespace-id <ID> "key" # Bulk put from JSON wrangler kv bulk put --namespace-id <ID> data.json ``` ### Config Binding ```jsonc { "kv_namespaces": [ { "binding": "CACHE", "id": "<NAMESPACE_ID>" } ] } ``` --- ## R2 (Object Storage) ### Manage Buckets ```bash # Create bucket wrangler r2 bucket create my-bucket # Create with location hint wrangler r2 bucket create my-bucket --location wnam # List buckets wrangler r2 bucket list # Get bucket info wrangler r2 bucket info my-bucket # Delete bucket wrangler r2 bucket delete my-bucket ``` ### Manage Objects ```bash # Upload object wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt # Download object wrangler r2 object get my-bucket/path/file.txt # Delete object wrangler r2 object delete my-bucket/path/file.txt ``` ### Config Binding ```jsonc { "r2_buckets": [ { "binding": "ASSETS", "bucket_name": "my-bucket" } ] } ``` --- ## D1 (SQL Database) ### Manage Databases ```bash # Create database wrangler d1 create my-database # Create with location wrangler d1 create my-database --location wnam # List databases wrangler d1 list # Get database info wrangler d1 info my-database # Delete database wrangler d1 delete my-database ``` ### Execute SQL ```bash # Execute SQL command (remote) wrangler d1 execute my-database --remote --command "SELECT * FROM users" # Execute SQL file (remote) wrangler d1 execute my-database --remote --file ./schema.sql # Execute locally wrangler d1 execute my-database --local --command "SELECT * FROM users" ``` ### Migrations ```bash # Create migration wrangler d1 migrations create my-database create_users_table # List pending migrations wrangler d1 migrations list my-database --local # Apply migrations locally wrangler d1 migrations apply my-database --local # Apply migrations to remote wrangler d1 migrations apply my-database --remote ``` ### Export/Backup ```bash # Export schema and data wrangler d1 export my-database --remote --output backup.sql # Export schema only wrangler d1 export my-database --remote --output schema.sql --no-data ``` ### Config Binding ```jsonc { "d1_databases": [ { "binding": "DB", "database_name": "my-database", "database_id": "<DATABASE_ID>", "migrations_dir": "./migrations" } ] } ``` --- ## Vectorize (Vector Database) ### Manage Indexes ```bash # Create index with dimensions wrangler vectorize create my-index --dimensions 768 --metric cosine # Create with preset (auto-configures dimensions/metric) wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5 # List indexes wrangler vectorize list # Get index info wrangler vectorize get my-index # Delete index wrangler vectorize delete my-index ``` ### Manage Vectors ```bash # Insert vectors from NDJSON file wrangler vectorize insert my-index --file vectors.ndjson # Query vectors wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10 ``` ### Config Binding ```jsonc { "vectorize": [ { "binding": "SEARCH_INDEX", "index_name": "my-index" } ] } ``` --- ## Hyperdrive (Database Accelerator) ### Manage Configs ```bash # Create config wrangler hyperdrive create my-hyperdrive \ --connection-string "postgres://user:pass@host:5432/database" # List configs wrangler hyperdrive list # Get config details wrangler hyperdrive get <HYPERDRIVE_ID> # Update config wrangler hyperdrive update <HYPERDRIVE_ID> --origin-password "new-password" # Delete config wrangler hyperdrive delete <HYPERDRIVE_ID> ``` ### Config Binding ```jsonc { "compatibility_flags": ["nodejs_compat_v2"], "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" } ] }