​​ Wrangler commands

These are the global flags that work on every single command

Flags:
  -c, --config      Path to .toml configuration file  [string]
  -h, --help        Show help  [boolean]
  -v, --version     Show version number  [boolean]
      --legacy-env  Use legacy environments  [boolean] (defaults to true)

​​ init

Create a skeleton wrangler.toml in an existing directory. This command 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 would like to use Wrangler.

$ wrangler init [$NAME] [--yes]

Default values indicated by =value.

​​ login

Authorize Wrangler with your Cloudflare account. This will open a login page in your browser and request your account access permissions. This command is the alternative to wrangler config and it uses OAuth tokens.

$ wrangler login [--scopes-list] [--scopes $SCOPES]

All of the arguments and flags to this command are optional:

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 and delete the configuration file, if present.

$ wrangler logout

This command only invalidates OAuth tokens acquired through the wrangler login command. However, it will try to delete the configuration file regardless of your authorization method.

If you wish to delete your API token, log into the Cloudflare dashboard and go to Overview > Get your API token in the right side menu > select the three-dot menu on your Wrangler token and select Delete if you wish to delete your API token.

​​ publish

Publish your Worker to Cloudflare. Several keys in your wrangler.toml file determine whether you are publishing to a *.workers.dev subdomain or a custom domain. However, custom domains must be proxied (orange-clouded) through Cloudflare. Refer to the Get started guide for more information.

$ wrangler publish [--env $ENVIRONMENT_NAME]

Options:
  -e, --env                                        Perform on a specific environment  [string]
      --name                                       Name of the worker  [string]
      --format                                     Choose an entry type  [choices: "modules", "service-worker"]
      --compatibility-date                         Date to use for compatibility checks  [string]
      --compatibility-flags, --compatibility-flag  Flags to use for compatibility checks  [array]
      --latest                                     Use the latest version of the worker runtime  [boolean] [default: false]
      --experimental-public                        Static assets to be served  [string]
      --site                                       Root folder of static assets for Workers Sites  [string]
      --site-include                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.  [array]
      --site-exclude                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.  [array]
      --triggers, --schedule, --schedules          cron schedules to attach  [array]
      --routes, --route                            Routes to upload  [array]
      --jsx-factory                                The function that is called for each JSX element  [string]
      --jsx-fragment                               The function that is called for each JSX fragment  [string]

​​ dev

wrangler dev is a command that establishes a connection between localhost and an edge server that operates your Worker in development. A cloudflared tunnel forwards all requests to the edge server, which continuously updates as your Worker code changes. This allows full access to Workers KV, Durable Objects, etc. 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>]

These arguments can also be set in your wrangler.toml file. Refer to the wrangler dev configuration documentation for more information.

​​ Usage

You should run wrangler dev from your Worker directory. 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

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. If either of these things do not happen, or you think the output is incorrect, file an issue Open external link .

​​ tail

Start a session to livestream logs from a deployed Worker.

$ wrangler tail [--format $FORMAT] [--status $STATUS] [OPTIONS]

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 (the directory with your wrangler.toml file).

​​ secret

Interact with your secrets.

​​ put

Create or replace a secret.

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

You will be prompted to input the secret’s value. This command can receive piped input, so the following example is also possible:

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

​​ delete

Delete a secret from a specific script.

$ wrangler secret delete <name> --env ENVIRONMENT_NAME

​​ list

List all the secret names bound to a specific script.

$ wrangler secret list --env ENVIRONMENT_NAME

​​ kv

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

• must configure and account_id in your project’s wrangler.toml file.
• run all wrangler kv:<command> operations in your terminal from the project’s root 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 its argument. A Workers KV namespace will be created using a concatenation of your Worker’s name (from your wrangler.toml file) 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 configuration file:
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

Successful operations will print a new configuration block that should be copied into your wrangler.toml file. Add the output to the existing kv_namespaces configuration if already present. You can now access the binding from within a Worker:

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

To write a value to your KV namespace using Wrangler, run the wrangler kv:key put subcommand.

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

Instead of --binding, you may use --namespace-id to specify which KV namespace should receive the operation:

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

A wrangler.toml file 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 do not need to specify an --env argument.

​​ 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 file:

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 file 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 file 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, refer to Environments .

​​ kv:namespace

​​ create

Create a new namespace.

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

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

List all KV namespaces associated with an account ID.

$ wrangler kv:namespace list

​​ Usage

This example 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 --binding= [--namespace-id=]

​​ Usage

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

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

​​ kv:key

​​ put

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

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

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

Output a list of all keys in a given namespace.

$ wrangler kv:key list --binding= [--namespace-id=] [--prefix] [--env]

​​ Usage

This example 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 --binding= [--env=] [--preview] [--namespace-id=] "$KEY"

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

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

Write a file full of key-value pairs to the given namespace.

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

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

In order to save JSON data, cast value to a string:

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

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

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

Delete all specified keys within a given namespace.

$ wrangler kv:bulk delete --binding= [--env=] [--preview] [--namespace-id=] $FILENAME

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

[
  {
    "key": "test_key",
    "value": ""
  }
]

​​ Usage

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