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
.
$NAME
=worker
- Name of the Workers project, setting both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- Name of the Workers project, setting both the directory name and
$TEMPLATE
=github.com/cloudflare/worker-template
- GitHub URL of the repo to use as the template for generating the project.
--type=$TYPE
=webpack
- Type of project. One of
webpack
,javascript
, orrust
.
- Type of project. One of
--site
- Generates a Workers Sites project from the default Workers Sites template instead.
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)
- Name of the Workers project, used in the
name
property in the generatedwrangler.toml
configuration file.
- Name of the Workers project, used in the
--type=$TYPE
=webpack
- Type of project. One of
webpack
,javascript
, orrust
.
- Type of project. One of
--site
- Initializes as a Workers Sites project.
build
Build your project (if applicable). 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
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
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
- 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
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
- Perform on a specific environment specified as
To use this command, the following fields are required in your wrangler.toml
:
name
string
- Name of your Worker, e.g.
name = "your-worker"
.
- Name of your Worker, e.g.
type
string
- Type of project. One of
"webpack"
,"javascript"
, or"rust"
, e.g.type = "webpack"
.
- Type of project. One of
account_id
string
- Your Cloudflare account ID. This can be found in the Cloudflare dashboard, e.g.
account_id = "a655bacaf2b4cad0e2b51c5236a6b974"
.
- Your Cloudflare account ID. This can be found in the Cloudflare dashboard, e.g.
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
.
- Indicates if deploying to a workers.dev domain, e.g.
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
- Your Cloudflare zone ID, e.g.
zone_id = "b6558acaf2b4cad1f2b51c5236a6b972"
, which can be found in the Cloudflare dashboard.
- Your Cloudflare zone ID, e.g.
route
string
- The route you would like to publish to, e.g.
route = "example.com/my-worker/*"
.
- The route you would like to publish to, e.g.
routes
Array
- The routes you would like to publish to, e.g.
routes = ["example.com/foo/*", example.com/bar/*]
.
- The routes you would like to publish to, e.g.
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
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
- Perform on a specific environment specified as
--ip
- Ip to listen on, defaults to 127.0.0.1
--port
- Port to listen on, defaults to 8787
--host
- Host to forward requests to, defaults to the zone of project or to tutorial.cloudflareworkers.com if unauthenticated.
--local-protocol
- Protocol to listen to requests on, defaults to http.
--upstream-protocol
- 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]
--port $PORT
int
- The port for your local log server
--metrics-port $PORT
int
- The port for serving metrics information about the tunnel
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)
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--watch
- 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.
- Enable live preview, so on changes Wrangler will continually update the preview service with the newest version of your project. By default,
$METHOD
="GET"
- Type of request to preview your worker with (get, post)
$BODY
="Null"
- Body string to post to your preview worker request. For example
wrangler preview post hello=hello
- Body string to post to your preview worker request. For example
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)
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
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
- The hash of the route ID to delete.
--env $ENVIRONMENT_NAME
=(Top level environment)
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
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
- 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
- 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
- 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 thewrangler.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:
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
- This can be combined with
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
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- 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
- The name of the namespace to delete.
--namespace-id
- The id of the namespace to delete.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- 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
- The key to write to.
$VALUE
- The value to write.
--binding
- The name of the namespace to write to.
--namespace-id
- The id of the namespace to write to.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
โskv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
--ttl
- Number of seconds for which the entries should be visible before they expire. At least 60. Takes precedence over
expiration
option.
- Number of seconds for which the entries should be visible before they expire. At least 60. Takes precedence over
--expiration
- Number of seconds since the UNIX epoch, indicating when the key-value pair should expire.
--path
- 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
- The name of the namespace to list.
--namespace-id
- The id of the namespace to list.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--prefix
- 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
- The key value to get.
--binding
- The name of the namespace to get from.
--namespace-id
- The id of the namespace to get from.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
โskv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
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
- The key value to delete.
--binding
- The name of the namespace to delete from.
--namespace-id
- The id of the namespace to delete from.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
โskv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
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
- The file to write to the namespace
--binding
- The name of the namespace to put to.
--namespace-id
- The id of the namespace to put to.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
โskv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
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
- A keyโs name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
value
string
- A UTF-8 encoded string to be stored, up to 10 MB in length.
expiration
int
- The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
expiration_ttl
int
- The number of seconds for which the key should be visible before it expires. At least 60.
base64
bool
- 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
.
- 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
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:bulk delete --binding= [--env=] [--preview] [--namespace-id=] $FILENAME
$FILENAME
- The file with key-value pairs to delete
--binding
- The name of the namespace to delete from.
--namespace-id
- The id of the namespace to delete from.
--env
- Perform on a specific environment specified as
$ENVIRONMENT_NAME
.
- Perform on a specific environment specified as
--preview
- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
โskv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
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
- A keyโs name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
value
string
- 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.12.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 ๐ต๏ธ Authenticate Wrangler with a Cloudflare API Token or Global API Key subdomain ๐ท Configure your workers.dev subdomain whoami ๐ต๏ธ Retrieve your user info and test your auth config tail ๐ฆ Aggregate logs from production worker login ๐ Authenticate Wrangler with your Cloudflare username and password help Prints this message or the help of the given subcommand(s)