Skip to content
Workers
Visit Workers on GitHub
Set theme to dark (⇧+D)

Commands

Complete list of all commands available for wrangler, the Workers CLI.


generate

Scaffold a Cloudflare Workers project from a public GitHub repository.

$ wrangler generate [$NAME] [$TEMPLATE] [--type=$TYPE] [--site]

Default values indicated by =value.


init

Creates a skeleton wrangler.toml in an existing directory. This can be used as an alternative to generate if you prefer to clone a template repository yourself, or you already have a JavaScript project and you’d like to use Wrangler.

$ wrangler init [$NAME] [--type=$TYPE] [--site]

Default values indicated by =value.

  • $NAME =(Name of working directory) optional

    • Name of the Workers project, used in the name property in the generated wrangler.toml configuration file.
  • --type=$TYPE =webpack optional

    • Type of project. One of webpack, javascript, or rust.
  • --site optional


build

Build your project. This command looks at your wrangler.toml file and runs the build steps associated with the"type" declared in your wrangler.toml.

$ wrangler build [--env $ENVIRONMENT_NAME]
  • --env optional
    • Perform on a specific environment specified as $ENVIRONMENT_NAME.

login

$ wrangler login

Authenticate Wrangler with your Cloudflare login. This will prompt you with a Cloudflare account login page and is the alternative to wrangler config.


config

An interactive command that will authenticate Wrangler by prompting you for a Cloudflare API Token or Global API key.

$ wrangler config [--api-key]
  • --api-key optional
    • To provide your email and global API key instead of a token. (This is not recommended for security reasons.)

You can also use wrangler login or environment variables to authenticate.


publish

Publish your Worker to Cloudflare. Several keys in your wrangler.toml determine whether you are publishing to a workers.dev subdomain or your own registered domain, proxied through Cloudflare.

$ wrangler publish [--env $ENVIRONMENT_NAME]
  • --env optional
    • Perform on a specific environment specified as $ENVIRONMENT_NAME

To use this command, the following fields are required in your wrangler.toml:

  • name string

    • Name of your Worker, e.g. name = "your-worker".
  • type string

    • Type of project. One of "webpack", "javascript", or "rust", e.g. type = "webpack".
  • account_id string

    • Your Cloudflare account ID. This can be found in the Cloudflare dashboard, e.g. account_id = "a655bacaf2b4cad0e2b51c5236a6b974".

From here, you have two options, you can choose to publish to your own domain or you can choose to publish to <your-worker>.<your-subdomain>.workers.dev.

Publishing to workers.dev

If you want to publish to workers.dev, you will first need to have a subdomain registered. You can register a subdomain by executing the subdomain command.

After you have registered a subdomain, add workers_dev to your wrangler.toml.

  • workers_dev bool
    • Indicates if deploying to a workers.dev domain, e.g. workers_dev = true.

Publishing to your own domain

If you would like to publish to your own domain, you will need to specify these three fields in your wrangler.toml.

  • zone_id string

  • route string

    • The route you would like to publish to, e.g. route = "example.com/my-worker/*".
  • routes Array

    • The routes you would like to publish to, e.g. routes = ["example.com/foo/*", example.com/bar/*].

Publishing the same code to multiple places

If you would like to be able to publish your code to multiple places, please see the documentation for environments.


dev

wrangler dev starts a server on localhost that executes your Worker on incoming HTTP requests. It can forward the requests to Cloudflare's servers, one of your zones, or any host you specify. This is a great way to easily test your Worker while developing.

$ wrangler dev [--env $ENVIRONMENT_NAME] [--ip <ip>] [--port <port>] [--host <host>] [--local-protocol <http|https>] [--upstream-protocol <http|https>]
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME
  • --ip optional

    • Ip to listen on, defaults to 127.0.0.1
  • --port optional

    • Port to listen on, defaults to 8787
  • --host optional

    • Host to forward requests to, defaults to the zone of project or to tutorial.cloudflareworkers.com if unauthenticated.
  • --local-protocol optional

    • Protocol to listen to requests on, defaults to http.
  • --upstream-protocol optional

    • Protocol to forward requests to host on, defaults to https.

These arguments can also be set in your wrangler.toml; see wrangler dev configuration.

Usage

You should run wrangler dev from your Worker directory, and wrangler will run a local server accepting requests, executing your worker, and forwarding them to a host. If you want to use another host other than your zone or tutorials.cloudflare.com you can specify with --host example.com.

$ wrangler dev💁  JavaScript project found. Skipping unnecessary build!💁  watching "./"👂  Listening on http://127.0.0.1:8787

From here 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. If either of these things don’t happen, or you think the output is incorrect, please file an issue.

kv_namespaces

If you are using kv_namespaces with wrangler dev, you will need to specify a preview_id in your wrangler.toml before you can start the session. This is so that you do not accidentally write changes to your production namespace while you are developing. You may make preview_id equal to id if you would like to preview with your production namespace, but you should make sure that you are not writing things to KV that would break your production Worker.


tail

Starts a log tailing session for a deployed Worker.

$ wrangler tail [--port $PORT] [--metrics-port $PORT]

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

Like all Wrangler commands, run wrangler tail from your Worker’s root directory (i.e. the directory with your wrangler.toml).

Dependencies

Wrangler tail uses cloudflared under the hood. If you are already using cloudflared, be sure you have installed the latest version. Otherwise, follow the getting started guide for Argo Tunnel. wrangler tail will register a tailing session for your Worker, and start a server on localhost with a tunnel that listens for incoming log requests from your Worker.


preview

Preview your project using the Cloudflare Workers preview service.

$ wrangler preview [--watch] [--env $ENVIRONMENT_NAME] [ --url $URL] [$METHOD] [$BODY]

Default values indicated by =value.

  • --env $ENVIRONMENT_NAME =(Top level environment) optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --watch recommended

    • Enable live preview, so on changes Wrangler will continually update the preview service with the newest version of your project. By default, wrangler preview will only bundle your project a single time.
  • $METHOD ="GET" optional

    • Type of request to preview your worker with (get, post)
  • $BODY ="Null" optional

    • Body string to post to your preview worker request. For example wrangler preview post hello=hello

kv_namespaces

If you are using kv_namespaces with wrangler preview, you will need to specify a preview_id in your wrangler.toml before you can start the session. This is so that you do not accidentally write changes to your production namespace while you are developing. You may make preview_id equal to id if you would like to preview with your production namespace, but you should make sure that you are not writing things to KV that would break your production Worker.

Previewing on Windows Subsystem for Linux (WSL 1/2)

Setting $BROWSER to your browser binary

WSL is a Linux environment, so wrangler attempts to invoke xdg-open in order to open your browser. To make wrangler preview work with WSL, you should set your $BROWSER to the path of your browser binary.

eg. $ export BROWSER="/mnt/c/tools/firefox.exe" Spaces in filepaths are not common in Linux, and some programs like xdg-open break on paths with spaces. You can work around this by linking the binary to your /usr/local/bin eg:

$ ln -s "/mnt/c/Program Files/Mozilla Firefox/firefox.exe" firefox$ export BROWSER=firefox

Setting $BROWSER to wsl-open

Another option is to install wsl-open and set the $BROWSER env variable to wsl-open, via wsl-open -w. This ensures that xdg-open uses wsl-open when it attempts to open your browser.

If you’re using WSL 2, you will need to install wsl-open via their standalone method rather than through npm. This is because their npm package has not yet been updated with WSL 2 support.


route

List or delete a route associated with a zone:

$ wrangler route list [--env $ENVIRONMENT_NAME]

Default values indicated by =value.

  • --env $ENVIRONMENT_NAME =(Top level environment) optional
    • Perform on a specific environment specified as $ENVIRONMENT_NAME.

Will return a json response from the List Routes API. Each entry includes the route id, pattern, and associated Worker name for a route. Piping this through a tool such as jq will pretty up the output.

$ wrangler route delete $ID [--env $ENVIRONMENT_NAME]

Default values indicated by =value.

  • $ID required

    • The hash of the route ID to delete.
  • --env $ENVIRONMENT_NAME =(Top level environment) optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.

subdomain

Create or change your workers.dev subdomain.

$ wrangler subdomain <name>

secret

Interact with your secrets.

put

Interactive command to create or replace a secret

$ wrangler secret put <name> --env ENVIRONMENT_NAMEEnter the secret text you’d like assigned to the variable name on the script named my-worker-ENVIRONMENT_NAME:
  • name

    • The variable name to be accessible in the script.
  • --env optional

    • Binds the secret to the script of the specific environment.

delete

Interactive command to delete a secret from a specific script

$ wrangler secret delete <name> --env ENVIRONMENT_NAME
  • name

    • The variable name to be accessible in the script.
  • --env optional

    • Binds the secret to the script of the specific environment.

list

List all the secret names bound to a specific script

$ wrangler secret list --env ENVIRONMENT_NAME
  • --env optional
    • Binds the secret to the script of the specific environment.

kv

The kv subcommand allows you to store application data in the Cloudflare network to be accessed from Workers, using Workers KV. KV operations are scoped to your account, so in order to use any of these commands, you need to:

  • have a Wrangler project set up with your account_id configured in the wrangler.toml
  • call commands from within a Wrangler project directory.

Getting started

To use Workers KV with your Worker, the first thing you must do is create a KV namespace. This is done with the kv:namespace subcommand.

The kv:namespace subcommand takes as a new binding name as an argument. It will create a Worker KV namespace whose title is a concatenation of your Worker’s name (from wrangler.toml) and the binding name you provide:

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

Make sure to add the kv_namespaces output above to your wrangler.toml. You can now access it from a Worker with code like:

let value = await MY_KV.get("my-key")

To put a value to your KV namespace via Wrangler, use the kv:key put subcommand.

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

You can also specify which namespace to put your key-value pair into using --namespace-id instead of --binding:

$ wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "key" "value"✨  Success

Additionally, KV namespaces can be used with environments! This is useful for when you have code that refers to a KV binding like MY_KV, and you want to be able to have these bindings point to different namespaces (like one for staging and one for production). So, if you have a wrangler.toml with two environments:

[env.staging]kv_namespaces = [  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }]
[env.production]kv_namespaces = [  { binding = "MY_KV", id = "a825455ce00f4f7282403da85269f8ea" }]

To insert a value into a specific KV namespace, you can use

$ wrangler kv:key put --env=staging --binding=MY_MV "key" "value"✨  Success

Since --namespace-id is always unique (unlike binding names), you don’t need to pass environment variables for them (they will be unused).

There are way more helpful Wrangler subcommands for interacting with Workers KV, like ones for bulk uploads and deletes--check them out below!

Concepts

Most kv commands require you to specify a namespace. A namespace can be specified in two ways:

  1. With a --binding:

    $ wrangler kv:key get --binding=MY_KV "my key"
    • This can be combined with --preview flag to interact with a preview namespace instead of a production namespace
  2. With a --namespace_id:

    $ wrangler kv:key get --namespace-id=06779da6940b431db6e566b4846d64db "my key"

Most kv subcommands also allow you to specify an environment with the optional --env flag. This allows you to publish workers running the same code but with different namespaces. For example, you could use separate staging and production namespaces for KV data in your wrangler.toml:

type = "webpack"name = "my-worker"account_id = "<account id here>"route = "staging.example.com/*"workers_dev = false
kv_namespaces = [  { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" }]
[env.production]route = "example.com/*"kv_namespaces = [  { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" }]

With the wrangler.toml above, you can specify --env production when you want to perform a KV action on the namespace MY_KV under env.production. For example, with the wrangler.toml above, you can get a value out of a production KV instance with:

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

To learn more about environments, check out the environments documentation.

kv:namespace

create

Creates a new namespace.

$ wrangler kv:namespace create $NAME [--env=$ENVIRONMENT_NAME] [--preview]
  • $NAME

    • The name of the new namespace
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production.
Usage
$ 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" }]
$ 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

Outputs a list of all KV namespaces associated with your account id.

$ wrangler kv:namespace list
Usage

The example below uses the jq command line tool to pretty-print output.

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

delete

Deletes a given namespace.

$ wrangler kv:namespace delete --binding= [--namespace-id=]
  • --binding required (if no --namespace-id)

    • The name of the namespace to delete.
  • --namespace-id required (if no --binding)

    • The id of the namespace to delete.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production.
Usage
$ wrangler kv:namespace delete --binding=MY_KVAre you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]yes🌀  Deleting namespace f7b02e7fc70443149ac906dd81ec1791✨  Success
$ 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

put

Writes a single key/value pair to the given namespace.

$ wrangler kv:key put --binding= [--namespace-id=] $KEY $VALUE✨  Success
  • $KEY required

    • The key to write to.
  • $VALUE required

    • The value to write.
  • --binding required (if no --namespace-id)

    • The name of the namespace to write to.
  • --namespace-id required (if no --binding)

    • The id of the namespace to write to.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production. Pass this to use your wrangler.toml’s kv_namespaces.preview_id instead of kv_namespaces.id
  • --ttl optional

    • Number of seconds for which the entries should be visible before they expire. At least 60. Takes precedence over expiration option.
  • --expiration optional

    • Number of seconds since the UNIX epoch, indicating when the key-value pair should expire.
  • --path optional

    • Read value from the file at a given path. This is good for security-sensitive operations, like uploading keys to KV; uploading from a file prevents a key value from being saved in areas like your terminal history.
Usage
$ wrangler kv:key put --binding=MY_KV "key" "value"✨  Success
$ wrangler kv:key put --binding=MY_KV --preview "key" "value"✨  Success
$ wrangler kv:key put --binding=MY_KV "key" "value" --ttl=10000✨  Success
$ wrangler kv:key put --binding=MY_KV "key" value.txt --path✨  Success

list

Outputs a list of all keys in a given namespace.

$ wrangler kv:key list --binding= [--namespace-id=] [--prefix] [--env]
  • --binding required (if no --namespace-id)

    • The name of the namespace to list.
  • --namespace-id required (if no --binding)

    • The id of the namespace to list.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --prefix optional

    • A prefix to filter listed keys.
Usage

The example below uses the jq command line tool to pretty-print output.

$ 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

Reads a single value by key from the given namespace.

$ wrangler kv:key get --binding= [--env=] [--preview] [--namespace-id=] "$KEY"
  • $KEY required

    • The key value to get.
  • --binding required (if no --namespace-id)

    • The name of the namespace to get from.
  • --namespace-id required (if no --binding)

    • The id of the namespace to get from.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production. Pass this to use your wrangler.toml’s kv_namespaces.preview_id instead of kv_namespaces.id
Usage
$ wrangler kv:key get --binding=MY_KV "key"value

delete

Removes a single key value pair from the given namespace.

$ wrangler kv:key delete --binding= [--env=] [--preview] [--namespace-id=] "$KEY"
  • $KEY required

    • The key value to delete.
  • --binding required (if no --namespace-id)

    • The name of the namespace to delete from.
  • --namespace-id required (if no --binding)

    • The id of the namespace to delete from.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production. Pass this to use your wrangler.toml’s kv_namespaces.preview_id instead of kv_namespaces.id
Usage
$ wrangler kv:key delete --binding=MY_KV "key"Are you sure you want to delete key "key"? [y/n]yes🌀  Deleting key "key"✨  Success

kv:bulk

put

Writes a file full of key/value pairs to the given namespace.

$ wrangler kv:bulk put --binding= [--env=] [--preview] [--namespace-id=] $FILENAME
  • $FILENAME required

    • The file to write to the namespace
  • --binding required (if no --namespace-id)

    • The name of the namespace to put to.
  • --namespace-id required (if no --binding)

    • The id of the namespace to put to.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production. Pass this to use your wrangler.toml’s kv_namespaces.preview_id instead of kv_namespaces.id

Takes as an argument a JSON file with a list of key-value pairs to upload (see JSON spec above). An example of JSON input:

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

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

  • key string required

    • A key’s name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
  • value string required

    • A UTF-8 encoded string to be stored, up to 10 MB in length.
  • expiration int optional

    • The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
  • expiration_ttl int optional

    • The number of seconds for which the key should be visible before it expires. At least 60.
  • base64 bool optional

    • Whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn’t otherwise be valid 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.

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

delete

Deletes all specified keys within a given namespace.

$ wrangler kv:key delete --binding= [--env=] [--preview] [--namespace-id=] $FILENAME
  • $FILENAME required

    • The file to write to the namespace
  • --binding required (if no --namespace-id)

    • The name of the namespace to put to.
  • --namespace-id required (if no --binding)

    • The id of the namespace to put to.
  • --env optional

    • Perform on a specific environment specified as $ENVIRONMENT_NAME.
  • --preview optional

    • Interact with a preview namespace instead of production. Pass this to use your wrangler.toml’s kv_namespaces.preview_id instead of kv_namespaces.id

Takes as an argument a JSON file with a list of key-value pairs to delete (see JSON spec above). An example of JSON input:

[  {    "key": "test_key",    "value": ""  }]
  • key string required

    • A key’s name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
  • value string required

    • A UTF-8 encoded string to be stored, up to 10 MB in length.
Usage
$ 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

--help

$ wrangler --help👷 ✨  wrangler 1.10.3The Wrangler Team <wrangler@cloudflare.com>
USAGE:    wrangler [SUBCOMMAND]
FLAGS:    -h, --help       Prints help information    -V, --version    Prints version information
SUBCOMMANDS:    kv:namespace    🗂️  Interact with your Workers KV Namespaces    kv:key          🔑  Individually manage Workers KV key-value pairs    kv:bulk         💪  Interact with multiple Workers KV key-value pairs at once    route           ➡️  List or delete worker routes.    secret          🤫  Generate a secret that can be referenced in the worker script    generate        👯  Generate a new worker project    init            📥  Create a wrangler.toml for an existing project    build           🦀  Build your worker    preview         🔬  Preview your code temporarily on cloudflareworkers.com    dev             👂  Start a local server for developing your worker    publish         🆙  Publish your worker to the orange cloud    config          🕵️  Set up wrangler with your Cloudflare account    subdomain       👷  Configure your workers.dev subdomain    whoami          🕵️  Retrieve your user info and test your auth config    tail            🦚  Aggregate logs from production worker    help            Prints this message or the help of the given subcommand(s)