Cloudflare Wrangler

Cloudflare Wrangler cheatsheet — build and deploy Workers to the edge. wrangler dev, wrangler deploy, wrangler kv:key put, wrangler tail. Serverless at Cloudflare's edge.

7 min read

What it is

Cloudflare Wrangler is a command-line interface (CLI) tool for developing, deploying, and managing applications on Cloudflare’s Workers platform. You reach for it when you want to build serverless applications that run on Cloudflare’s edge network.

Installation

Linux/macOS

npm install -g wrangler

yarn global add wrangler

Windows

npm install -g wrangler

yarn global add wrangler

Core Concepts

Workers: Serverless JavaScript, TypeScript, or WebAssembly functions that run on Cloudflare’s global network.
wrangler.toml: The configuration file for your Worker project, defining name, account ID, routes, and other settings.
wrangler.dev: A local development server that simulates the Cloudflare Workers environment, allowing for rapid iteration.
wrangler publish: Deploys your Worker to Cloudflare’s production environment.
Routes: URLs that are configured to trigger your Worker.

Commands / Usage

Project Initialization

Create a new Worker project:
```
wrangler generate my-worker
```
Creates a new Worker project directory named my-worker with a basic template.
Create a new Worker project from a template:
```
wrangler generate my-worker https://github.com/cloudflare/workers-templates/tree/main/typescript
```
Creates a new Worker project from a specified Git repository template.

Development

Start a local development server:
```
cd my-worker
wrangler dev
```
Runs your Worker locally and watches for file changes. Access your Worker at http://localhost:8787.
Start a local development server with a specific IP/port:
```
wrangler dev --host 127.0.0.1 --port 9000
```
Runs your Worker locally on http://127.0.0.1:9000.
Start a local development server with a specific upstream Worker:
```
wrangler dev --upstream my-other-worker
```
When developing a Worker that might interact with another Worker, this command allows you to specify an upstream Worker to proxy requests to.
Start a local development server with a specific upstream Worker and route:
```
wrangler dev --upstream my-other-worker --route "https://api.example.com/*"
```
Proxies requests matching the route to the specified upstream Worker.

Deployment

Publish your Worker to production:
```
cd my-worker
wrangler publish
```
Deploys the current state of your Worker to Cloudflare.
Publish with a specific version message:
```
wrangler publish --message "Added new feature X"
```
Deploys your Worker and associates a descriptive message with the deployment.
Publish to a specific environment:
```
wrangler publish --env staging
```
Deploys your Worker to a configured staging environment. Requires environments to be set up in wrangler.toml.

Configuration and Account Management

Configure your Cloudflare account:
```
wrangler config
```
Prompts you to log in to your Cloudflare account and sets up authentication.
Configure your Worker project:
```
wrangler init
```
Initializes a wrangler.toml file in the current directory if one doesn’t exist.
View your wrangler.toml configuration:
```
wrangler config --show
```
Displays your current Wrangler configuration, including your account ID and API token.
Login to Cloudflare:
```
wrangler login
```
Authenticates your Wrangler CLI with your Cloudflare account.

Environment Management

List configured environments:
```
wrangler env list
```
Shows the environments defined in your wrangler.toml file.
Create a new environment:
```
wrangler env create production
```
Adds a new environment named production to your wrangler.toml.
Delete an environment:
```
wrangler env delete staging
```
Removes the staging environment from your wrangler.toml.
Set environment variables for an environment:
```
wrangler env vars set MY_API_KEY --env production
```
Sets an environment variable named MY_API_KEY for the production environment. You will be prompted for the value.
List environment variables for an environment:
```
wrangler env vars list --env production
```
Displays environment variables set for the production environment.
Delete environment variables for an environment:
```
wrangler env vars delete MY_API_KEY --env production
```
Removes the MY_API_KEY environment variable from the production environment.

KV (Key-Value) Store Management

Create a new KV namespace:
```
wrangler kv:namespace create my-kv-store
```
Creates a new KV namespace named my-kv-store and adds it to your wrangler.toml.
List KV namespaces:
```
wrangler kv:namespace list
```
Lists all KV namespaces associated with your account.
Put a value into a KV namespace:
```
wrangler kv:key put "user:123" "John Doe" --binding MY_KV_STORE
```
Stores the value "John Doe" with the key "user:123" in the KV namespace bound to MY_KV_STORE.
Get a value from a KV namespace:
```
wrangler kv:key get "user:123" --binding MY_KV_STORE
```
Retrieves the value associated with the key "user:123" from the KV namespace bound to MY_KV_STORE.
List keys in a KV namespace:
```
wrangler kv:key list --binding MY_KV_STORE
```
Lists all keys within the KV namespace bound to MY_KV_STORE.
Delete a key from a KV namespace:
```
wrangler kv:key delete "user:123" --binding MY_KV_STORE
```
Removes the key "user:123" and its associated value from the KV namespace bound to MY_KV_STORE.

Durable Objects Management

Create a new Durable Object:
```
wrangler do:new <name>
```
Creates a new Durable Object named <name>.
List Durable Objects:
```
wrangler do:list
```
Lists all Durable Objects in your account.

Cron Triggers

Create a cron trigger:

wrangler cron:create "0 * * * *" --cron-description "Every hour"

Creates a cron trigger that runs every hour.

List cron triggers:
```
wrangler cron:list
```
Lists all configured cron triggers for your Worker.
Delete a cron trigger:
```
wrangler cron:delete "0 * * * *"
```
Deletes the specified cron trigger.

Tail (Logging)

Tail logs from your Worker:
```
wrangler tail
```
Connects to your Worker in production and streams logs in real-time.
Tail logs with a specific number of recent events:
```
wrangler tail --count 100
```
Streams logs and includes the last 100 events that occurred before connecting.
Tail logs from a specific environment:
```
wrangler tail --env staging
```
Streams logs from the Worker deployed to the staging environment.

Other Commands

Validate your Worker configuration:
```
wrangler validate
```
Checks your wrangler.toml for common configuration errors.
Get information about your Worker:
```
wrangler whoami
```
Displays information about your authenticated Cloudflare account.
Generate a type definition file:
```
wrangler generate types worker-types.ts
```
Generates a TypeScript file (worker-types.ts) that includes types for your Worker’s environment variables, KV namespaces, Durable Objects, and more.

Common Patterns

Develop a Worker with a KV store and Durable Object:

# In wrangler.toml
[vars]
MY_KV_NAMESPACE = "MY_KV_STORE"

[[durable_objects]]
name = "MY_DO"
script = "my-do-worker" # if your DO is in a separate file

# In your main worker file (e.g., index.ts)
export default {
  async fetch(request, env, ctx) {
    const kvValue = await env.MY_KV_STORE.get("some_key");
    const doStub = env.MY_DO.get(env.MY_DO.idFromName("some_id"));
    await doStub.fetch("http://example.com");
    return new Response(kvValue);
  },
};

# Deploy and run
wrangler kv:namespace create MY_KV_STORE
wrangler do:new MY_DO
wrangler publish

Deploy a Worker to a staging environment and test it:

# Ensure staging environment is configured in wrangler.toml
# wrangler env create staging
# wrangler env vars set API_URL --env staging http://localhost:3000

wrangler publish --env staging
curl https://staging.your-worker-name.your-account.workers.dev

Watch for local changes and automatically rebuild/redeploy (requires nodemon or similar):
```
# Using nodemon for automatic restarts
npm install -g nodemon
nodemon --watch src --ext ts --exec "wrangler dev"
```
This setup automatically restarts wrangler dev whenever TypeScript files in the src directory change.
Get a list of all deployed Worker versions:
```
wrangler deployments list
```
Useful for auditing or rolling back to previous versions.
Rollback to a previous deployment:
```
wrangler deployments rollback <deployment-id>
```
Reverts your Worker to a specific deployment ID.

Gotchas

wrangler.toml is essential: Many commands require a wrangler.toml file to be present and correctly configured (especially account_id). If it’s missing, Wrangler will often prompt you to create it.
account_id is mandatory: You must set your Cloudflare account_id in wrangler.toml for most commands to work. You can find this on your Cloudflare dashboard.
Environment variables are bound, not global: Environment variables, KV namespaces, and Durable Objects are accessed via the env object passed to your Worker’s fetch handler. They are not global variables.
Local wrangler dev vs. Production: While wrangler dev is a great simulator, there can be subtle differences in behavior compared to the live production environment. Always test thoroughly in production.
KV namespace binding names: When using KV or Durable Objects, ensure the binding name in wrangler.toml (e.g., MY_KV_STORE) matches how you reference it in your Worker code (e.g., env.MY_KV_STORE).
wrangler.dev port conflicts: If port 8787 is already in use, wrangler dev will try to find another available port. Check the output for the correct URL.
API Token Permissions: When setting up wrangler config or wrangler login, ensure the API token you use has the necessary permissions for Workers management, KV, Durable Objects, etc. Insufficient permissions are a common source of deployment errors.
Module Workers vs. Script Workers: Wrangler supports both. wrangler.toml has a type field ("module" or "javascript"). Default is "javascript". Module Workers are generally preferred for modern development.