Commands · Cloudflare Workers docs

Wrangler commands

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

init - Create a skeleton Wrangler project, including the wrangler.toml file.
generate - Create a Wrangler project using an existing Workers template.
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.
secret:bulk - Manage multiple 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.
whoami - Retrieve your user information and test your authentication configuration.

init

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

$ wrangler init [NAME] [-y / --yes] [--from-dash]

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.
--from-dash string optional
- Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name. wrangler init --from-dash <WORKER_NAME>
- The --from-dash command will not automatically sync changes made to the dashboard after the command is used. Therefore, it is recommended that you continue using the CLI.

generate

Create a Wrangler project using an existing Workers template.

$ wrangler generate [name] [template]

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.
template string optional
- The URL of a GitHub template, with a default worker-template. Browse a list of available templates on cloudflare/templates repository.

dev

Start a local server for developing your Worker.

$ wrangler dev [SCRIPT] [OPTIONS]

None of the options for this command are required. Many of these options can be set in your wrangler.toml file. Refer to the wrangler.toml configuration documentation for more information.

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.
  This runs an ephemeral local version of your Worker, and will not be able to access data stored on Cloudflare’s Edge (for instance, this includes your data stored on KV). If you’d like to persist data locally, the experimental option --experimental-enable-local-persistence will store data in the wrangler-local-state subdirectory.
--minify boolean
- Minify the script.
--test-scheduled boolean (default: false)
- Exposes a /__scheduled fetch route which will trigger a scheduled event (cron trigger) for testing during development. To simulate different cron patterns, a cron query parameter can be passed in: /__scheduled?cron=*+*+*+*+*.

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]

None of the options for this command are required. Also, many can be set in your wrangler.toml file. Refer to the wrangler.toml configuration documentation for more information.

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).

Below is an example of using the create command to create a KV namespace called MY_KV.

$ wrangler kv:namespace create "MY_KV"🌀  Creating namespace with title "worker-MY_KV"✨  Add the following to your wrangler.toml:kv_namespaces = [  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }]

Below is an example of using the create command to create a preview KV namespace called MY_KV.

$ wrangler kv:namespace create "MY_KV" --preview🌀  Creating namespace with title "my-site-MY_KV_preview"✨  Success!Add the following to your wrangler.toml:kv_namespaces = [  { binding = "MY_KV", preview_id = "15137f8edf6c09742227e99b08aaf273" }]

list

List all KV namespaces associated with the current account ID.

$ wrangler kv:namespace list

Below is an example that passes the Wrangler command through the jq command:

$ wrangler kv:namespace list | jq "."[  {    "id": "06779da6940b431db6e566b4846d64db",    "title": "TEST_NAMESPACE"  },  {    "id": "32ac1b3c2ed34ed3b397268817dea9ea",    "title": "STATIC_CONTENT"  }]

delete

Delete a given namespace.

$ wrangler kv:namespace delete [OPTIONS]

Exactly one of --binding or --namespace-id is required.

--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.

Below is an example of deleting a KV namespace called MY_KV.

$ wrangler kv:namespace delete --binding=MY_KVAre you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]yes🌀  Deleting namespace f7b02e7fc70443149ac906dd81ec1791✨  Success

Below is an example of deleting a preview KV namespace called MY_KV.

$ wrangler kv:namespace delete --binding=MY_KV --previewAre you sure you want to delete namespace 15137f8edf6c09742227e99b08aaf273? [y/n]yes🌀  Deleting namespace 15137f8edf6c09742227e99b08aaf273✨  Success

`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.

Below is an example that puts a key-value into the namespace with binding name of MY_KV.

$ wrangler kv:key put --binding=MY_KV "my-key" "some-value"✨  Success

Below is an example that puts a key-value into the preview namespace with binding name of MY_KV.

$ wrangler kv:key put --binding=MY_KV --preview "my-key" "some-value"✨  Success

Below is an example that puts a key-value into a namespace, with a time-to-live value of 10000 seconds.

$ wrangler kv:key put --binding=MY_KV "my-key" "some-value" --ttl=10000✨  Success

Below is an example that puts a key-value into a namespace, where the value is read from the value.txt file.

$ wrangler kv:key put --binding=MY_KV "my-key" --path=value.txt✨  Success

list

Output a list of all keys in a given namespace.

$ wrangler kv:key list [OPTIONS]

Exactly one of --binding or --namespace-id is required.

--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.

Below is an example that passes the Wrangler command through the jq command:

$ wrangler kv:key list --binding=MY_KV --prefix="public" | jq "."[  {    "name": "public_key"  },  {    "name": "public_key_with_expiration",    "expiration": "2019-09-10T23:18:58Z"  }]

`get`

Read a single value by key from the given namespace.

$ wrangler kv:key get <KEY> [OPTIONS]

Exactly one of --binding or --namespace-id is required.

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.

Here is an example that gets the value of the "my-key" key from the KV namespace with binding name MY_KV.

$ wrangler kv:key get --binding=MY_KV "my-key"value

`delete`

Remove a single key value pair from the given namespace.

$ wrangler kv:key delete <KEY> [OPTIONS]

Exactly one of --binding or --namespace-id is required.

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.

Below is an example that deletes the key-value pair with key "my-key" from the KV namespace with binding name MY_KV.

$ wrangler kv:key delete --binding=MY_KV "my-key"Are you sure you want to delete key "my-key"? [y/n]yes🌀  Deleting key "my-key"✨  Success

`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]

Exactly one of --binding or --namespace-id is required.

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.

If both expiration and expiration_ttl are specified for a given key, the API will prefer expiration_ttl.

Here is an example of writing all the key-value pairs found in the allthethingsupload.json file.

$ wrangler kv:bulk put --binding=MY_KV allthethingsupload.json🌀  uploading 1 key value pairs✨  Success

`delete`

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

$ wrangler kv:bulk delete <FILENAME> [OPTIONS]

Exactly one of --binding or --namespace-id is required.

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"]

Below is an example of deleting all the keys found in the allthethingsdelete.json file.

$ wrangler kv:bulk delete --binding=MY_KV allthethingsdelete.jsonAre you sure you want to delete all keys in allthethingsdelete.json? [y/n]y🌀  deleting 1 key value pairs✨  Success

r2 bucket

Interact with buckets in an R2 store.

The r2 bucket commands allow you to manage application data in the Cloudflare network to be accessed from Workers using the R2 API.

`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 <KEY> [OPTIONS]

KEY string required
- The variable name for this secret to be accessed in the Worker.
--name string optional
- Perform on a specific Worker script rather than inheriting from wrangler.toml.
--env string optional
- Perform on a specific environment.

You will be prompted to input the secret’s value. For example:

$ wrangler secret put FOOEnter a secret value: ***🌀 Creating the secret for script worker-app✨ Success! Uploaded secret FOO

The put command can also receive piped input. For example:

$ echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY

delete

Delete a secret for a Worker.

$ wrangler secret delete <KEY> [OPTIONS]

KEY string required
- The variable name for this secret to be accessed in the Worker.
--name string optional
- Perform on a specific Worker script rather than inheriting from wrangler.toml.
--env string optional
- Perform on a specific environment.

list

List the names of all the secrets for a Worker.

$ wrangler secret list [OPTIONS]

--name string optional
- Perform on a specific Worker script rather than inheriting from wrangler.toml.
--env string optional
- Perform on a specific environment

Below is an example of listing the secrets for the current Worker.

$ wrangler secret list[  {    "name": "FOO",    "type": "secret_text"  }]

`secret:bulk`

Manage multiple secrets for a Worker.

`json`

The path to a JSON file containing secrets in key-value pairs to upload.

$ wrangler secret:bulk json <FILE> [OPTIONS]

JSON string required
- The JSON file of key-value pairs to upload, in form {“key”: value, …}
--name string optional
- Perform on a specific Worker script rather than inheriting from wrangler.toml.
--env string optional
- Perform on a specific environment

Below is an example of uploading secrets from a JSON file.

{  "secret-name-1": "secret-value-1",  "secret-name-2": "secret-value-2"
}

When complete the output summary will show the number of secrets uploaded and number failed.

🌀 Creating the secrets for the Worker "script-name"✨ Successfully created secret for key: secret-name-1...🚨 Error uploading secret for key: secret-name-1✨ Successfully created secret for key: secret-name-2
Finished processing secrets JSON file:✨ 1 secrets successfully uploaded🚨 1 secrets failed to upload

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.

Filtering with --ip self will allow tailing a Worker beyond the normal request per second limits.

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.

Your site is deployed to <PROJECT_NAME>.pages.dev. If you do not provide the --project-name argument, you will be prompted to enter <PROJECT_NAME> in your terminal after you run the command.

This command has an alias of wrangler pages deploy create.

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.

wrangler login uses all the available scopes by default if no flags are provided.

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:

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

whoami

Retrieve your user information and test your authentication configuration.

$ wrangler whoami

​​ Wrangler commands

​​ init

​​ generate

​​ dev

​​ publish

​​ kv:namespace

​​ create

​​ list

​​ delete

​​ kv:key

​​ put

​​ list

​​ get

​​ delete

​​ kv:bulk

​​ put

​​ delete

​​ r2 bucket

​​ create

​​ delete

​​ list

​​ secret

​​ put

​​ delete

​​ list

​​ secret:bulk

​​ json

​​ tail

​​ pages

​​ dev

​​ project list

​​ project create

​​ deployment list

​​ publish

​​ login

​​ logout

​​ whoami

Wrangler commands

init

generate

dev

publish

`kv:namespace`

`create`

list

delete

`kv:key`

`put`

list

`get`

`delete`

`kv:bulk`

`put`

`delete`

r2 bucket

`create`

`delete`

`list`

secret

put

delete

list

`secret:bulk`

`json`

tail

pages

`dev`

`project list`

`project create`

`deployment list`

`publish`

login

logout

whoami