Cloudflare Docs
Workers
Visit Workers on GitHub
Set theme to dark (⇧+D)

Wrangler commands

Wrangler offers a number of commands to manage your Cloudflare Workers.

  • init - Create a skeleton Wrangler project, including the wrangler.toml file.
  • dev - Start a local server for developing your Worker.
  • publish - Publish your Worker to Cloudflare.
  • kv:namespace - Manage Workers KV namespaces.
  • kv:key - Manage key-value pairs within a Workers KV namespace.
  • kv:bulk - Manage multiple key-value pairs within a Workers KV namespace in batches.
  • r2 bucket - Manage Workers R2 buckets.
  • secret - Manage the secret variables for a Worker.
  • tail - Start a session to livestream logs from a deployed Worker.
  • pages - Configure Cloudflare Pages.
  • login - Authorize Wrangler with your Cloudflare account using OAuth.
  • logout - Remove Wrangler’s authorization for accessing your account.

init

Create a skeleton Wrangler project, including the wrangler.toml file.

$ wrangler init [NAME] [-y / --yes]
  • NAME string optional (default: name of working directory)
    • The name of the Workers project. This is both the directory name and name property in the generated wrangler.toml configuration file.
  • --yes boolean optional
    • Answer yes to any prompts for new projects.

dev

Start a local server for developing your Worker.

$ wrangler dev [SCRIPT] [OPTIONS]
  • SCRIPT string
    • The path to an entry point for your Worker.
  • --name string
    • Name of the Worker.
  • --env string
    • Perform on a specific environment.
  • --compatibility-date string
    • Date to use for compatibility checks.
  • --compatibility-flags, --compatibility-flag boolean[]
    • Flags to use for compatibility checks.
  • --latest boolean (default: true)
    • Use the latest version of the Workers runtime.
  • --ip string
    • IP address to listen on, defaults to localhost.
  • --port number
    • Port to listen on.
  • --inspector-port number
    • Port for devtools to connect to.
  • --routes, --route string[]
    • Routes to upload.
  • --host string
    • Host to forward requests to, defaults to the zone of project.
  • --local-protocol “http”|“https” (default: http)
    • Protocol to listen to requests on.
  • --site string
    • Root folder of static assets for Workers Sites.
  • --site-include string[]
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.
  • --site-exclude string[]
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.
  • --upstream-protocol “http”|“https” (default: https)
    • Protocol to forward requests to host on.
  • --tsconfig string
    • Path to a custom tsconfig.json file.
  • --local boolean (default: false)
    • Run the preview of the Worker directly on your local machine.
  • --minify boolean
    • Minify the script.

The wrangler dev command that establishes a connection between localhost and a Cloudflare server that hosts your Worker in development. This allows full access to Workers KV and Durable Objects. wrangler dev is a way to easily test your Worker while developing.

~/my-worker $ wrangler dev
⬣ Listening at http://localhost:8787
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn on local mode, [c] clear console, [x] to exit │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

With wrangler dev running, you can send HTTP requests to localhost:8787 and your Worker should execute as expected. You will also see console.log messages and exceptions appearing in your terminal.


publish

Publish your Worker to Cloudflare.

$ wrangler publish [SCRIPT] [OPTIONS]
  • SCRIPT string
    • The path to an entry point for your Worker.
  • --name string
    • Name of the Worker.
  • --env string
    • Perform on a specific environment.
  • --outdir string
    • Path to directory where Wrangler will write the bundled Worker files.
  • --compatibility-date string
    • Date to use for compatibility checks.
  • --compatibility-flags, --compatibility-flag boolean[]
    • Flags to use for compatibility checks.
  • --latest boolean (default: true)
    • Use the latest version of the Workers runtime.
  • --site string
    • Root folder of static assets for Workers Sites.
  • --site-include string[]
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.
  • --site-exclude string[]
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.
  • --triggers, --schedule, --schedules string[]
    • Cron schedules to attach to the published Worker.
  • --routes, --route string[]
    • Routes where this Worker will be published.
  • --tsconfig string
    • Path to a custom tsconfig.json file.
  • --minify boolean
    • Minify the bundled script before publishing.
  • --dry-run boolean (default: false)

kv:namespace

Manage Workers KV namespaces.

create

Create a new namespace.

$ wrangler kv:namespace create <NAMESPACE> [OPTIONS]
  • NAMESPACE string required
    • The name of the new namespace.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace (the preview_id value).

list

List all KV namespaces associated with the current account ID.

$ wrangler kv:namespace list

delete

Delete a given namespace.

$ wrangler kv:namespace delete [OPTIONS]
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

kv:key

Manage key-value pairs within a Workers KV namespace.

put

Write a single key-value pair to a particular namespace.

$ wrangler kv:key put <KEY> [VALUE] [OPTIONS]
  • KEY string required
    • The key to write to.
  • VALUE string optional
    • The value to write.
  • --path optional
    • When defined, the value is loaded from the file at --path rather than reading it from the VALUE argument. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.
  • --ttl number optional
    • The lifetime (in number of seconds) that the key-value pair should exist before expiring. Must be at least 60 seconds. This option takes precedence over the expiration option.
  • --expiration number optional
    • The timestamp, in UNIX seconds, indicating when the key-value pair should expire.

list

Output a list of all keys in a given namespace.

$ wrangler kv:key list [OPTIONS]
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.
  • --prefix string optional
    • Only list keys that begin with the given prefix.

get

Read a single value by key from the given namespace.

$ wrangler kv:key get <KEY> [OPTIONS]
  • KEY string required
    • The key value to get.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

delete

Remove a single key value pair from the given namespace.

$ wrangler kv:key delete <KEY> [OPTIONS]
  • KEY string required
    • The key value to get.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

kv:bulk

Manage multiple key-value pairs within a Workers KV namespace in batches.

put

Write a JSON file containing an array of key-value pairs to the given namespace.

$ wrangler kv:bulk put <FILENAME> [OPTIONS]
  • FILENAME string required
    • The JSON file containing an array of key-value pairs to write to the namespace.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

This command takes a JSON file as an argument with a list of key-value pairs to upload. An example of JSON input:

[
{
"key": "test_key",
"value": "test_value",
"expiration_ttl": 3600
}
]

KV namespace values can only store strings. In order to save complex a value, stringify it to JSON:

[
{
"key": "test_key",
"value": "{\"name\": \"test_value\"}",
"expiration_ttl": 3600
}
]

Here is the full schema for key-value entries uploaded via the bulk API:

  • key string required
    • The key’s name. The name may be 512 bytes maximum. All printable, non-whitespace characters are valid.
  • value string required
    • The UTF-8 encoded string to be stored, up to 10 MB in length.
  • expiration number optional
    • The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
  • expiration_ttl number optional
    • The number of seconds the document should exist before expiring. Must be at least 60 seconds.
  • base64 boolean optional
    • When true, the server will decode the value as base64 before storing it. This is useful for writing values that would otherwise be invalid JSON strings, such as images. Defaults to false.

delete

Delete all keys read from a JSON file within a given namespace.

$ wrangler kv:bulk delete <FILENAME> [OPTIONS]
  • FILENAME string required
    • The JSON file containing an array of keys to delete from the namespace.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, to delete.
  • --namespace-id string
    • The ID of the namespace to delete.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

This command takes a JSON file as an argument containing an array of keys to delete. Here is an example of the JSON input:

["test_key_1", "test_key_2"]

r2 bucket

Interact with buckets in an R2 store.

create

Create a new R2 bucket.

$ wrangler r2 bucket create <NAME>
  • NAME string required
    • The name of the new R2 bucket.

delete

Delete an R2 bucket.

$ wrangler r2 bucket delete <NAME>
  • NAME string required
    • The name of the R2 bucket to delete.

list

List R2 bucket in the current account.

$ wrangler r2 bucket list

secret

Manage the secret variables for a Worker.

put

Create or replace a secret for a Worker.

$ wrangler secret put <NAME> [OPTIONS]
  • NAME string required
    • The variable name for this secret to be accessed in the Worker.
  • --env string optional
    • Perform on a specific environment.

delete

Delete a secret for a Worker.

$ wrangler secret delete <NAME> [OPTIONS]
  • NAME string required
    • The variable name for this secret to be accessed in the Worker.
  • --env string optional
    • Perform on a specific environment.

list

List the names of all the secrets for a Worker.

$ wrangler secret list [OPTIONS]
  • --env string optional
    • Perform on a specific environment

tail

Start a session to livestream logs from a deployed Worker.

$ wrangler tail <NAME> [OPTIONS]
  • NAME string required
  • --format “json”|“pretty” optional
    • The format of the log entries.
  • --status “ok”|“error”|“canceled” optional
    • Filter by invocation status.
  • --header string optional
    • Filter by HTTP header.
  • --method string optional
    • Filter by HTTP method.
  • --sampling-rate number optional
    • Add a fraction of requests to log sampling rate (between 0 and 1).
  • --search string optional
    • Filter by a text match in console.log messages.
  • --ip (string|“self”)[] optional
    • Filter by the IP address the request originates from. Use "self" to show only messages from your own IP.

After starting wrangler tail, you will receive a live feed of console and exception logs for each request your Worker receives.


pages

Configure Cloudflare Pages.

dev

Develop your full stack Pages application locally.

$ wrangler pages dev [<DIRECTORY>] [OPTIONS] [-- <COMMAND..>]
  • DIRECTORY string
    • The directory of static assets to serve.
  • COMMAND.. string
    • The proxy command(s) to run.
  • --local boolean (default: true)
    • Run on my machine.
  • --port number (default: 8788)
    • The port to listen on (serve from).
  • --proxy number
    • The port to proxy (where the static assets are served).
  • --script-path string (default: “_worker.js”)
    • The location of the single Worker script if not using functions.
  • --binding string[]
    • Bind variable/secret (KEY=VALUE).
  • --kv string[]
    • KV namespace to bind.
  • --do string[]
    • Durable Object to bind (NAME=CLASS).
  • --live-reload boolean (default: false)
    • Auto reload HTML pages when change is detected.

project list

List your Pages projects.

$ wrangler pages project list

project create

Create a new Cloudflare Pages project.

$ wrangler pages project create [PROJECT-NAME] [OPTIONS]
  • PROJECT-NAME string
    • The name of your Pages project.
  • --production-branch string
    • The name of the production branch of your project.

deployment list

List deployments in your Cloudflare Pages project.

$ wrangler pages deployment list [OPTIONS]
  • --project-name string
    • The name of the project you would like to list deployments for.

publish

Deploy a directory of static assets as a Pages deployment.

$ wrangler pages publish [DIRECTORY] [OPTIONS]
  • DIRECTORY string
    • The directory of static files to upload.
  • --project-name string
    • The name of the project you want to deploy to.
  • --branch string
    • The name of the branch you want to deploy to.
  • --commit-hash string
    • The SHA to attach to this deployment.
  • --commit-message string
    • The commit message to attach to this deployment.
  • --commit-dirty boolean
    • Whether or not the workspace should be considered dirty for this deployment.

login

Authorize Wrangler with your Cloudflare account using OAuth. This will open a login page in your browser and request your account access permissions.

$ wrangler login [OPTIONS]
  • --scopes-list string optional
    • List all the available OAuth scopes with descriptions.
  • --scopes $SCOPES string optional
    • Allows to choose your set of OAuth scopes. The set of scopes must be entered in a whitespace-separated list, for example, $ wrangler login --scopes account:read user:read.

logout

Remove Wrangler’s authorization for accessing your account. This command will invalidate your current OAuth token.

$ wrangler logout

If you are using CLOUDFLARE_API_TOKEN instead of OAuth, and you can logout by deleting your API token in the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard.
  2. Go to Overview > Get your API token in the right-side menu.
  3. Select the three-dot menu on your Wrangler token.
  4. Select Delete.