Commands
Complete list of all commands available for wrangler
↗, the Workers CLI.
generate
Scaffold a Cloudflare Workers project from a public GitHub repository.
Default values indicated by =value.
-
$NAME
=worker optional- The name of the Workers project. This is both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- The name of the Workers project. This is both the directory name and
-
$TEMPLATE
=https://github.com/cloudflare/worker-template ↗ optional- The GitHub URL of the repository to use as the template ↗ for generating the project.
-
--type=$TYPE
=webpack optional- The type of project; one of
webpack
,javascript
, orrust
.
- The type of project; one of
-
--site
optional- When defined, the default
$TEMPLATE
value is changed tocloudflare/workers-sdk/templates/worker-sites
↗. This scaffolds a Workers Site project.
- When defined, the default
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.
Default values indicated by =value.
-
$NAME
=(Name of working directory) optional- The name of the Workers project. This is both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- The name of the Workers project. This is both the directory name and
-
--type=$TYPE
=webpack optional- The type of project; one of
webpack
,javascript
, orrust
.
- The type of project; one of
-
--site
optional- When defined, the default
$TEMPLATE
value is changed tocloudflare/workers-sdk/templates/worker-sites
↗. This scaffolds a Workers Site project.
- When defined, the default
build
Build your project (if applicable). This command looks at your wrangler.toml
file and reacts to the "type"
value specified.
When using type = "webpack"
, Wrangler will build the Worker using its internal webpack installation. When using type = "javascript"
, the build.command
, if defined, will run.
--env
optional- If defined, Wrangler will load the matching environment’s configuration before building. Refer to Environments for more information.
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.
All of the arguments and flags to this command are optional:
--scopes-list
optional- List all the available OAuth scopes with descriptions.
--scopes $SCOPES
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
.
- Allows to choose your set of OAuth scopes. The set of scopes must be entered in a whitespace-separated list,
for example,
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.
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 in to 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.
config
Configure Wrangler so that it may acquire a Cloudflare API Token or Global API key, instead of OAuth tokens, in order to access and manage account resources.
--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 environment variables to authenticate, or wrangler login
to authorize with OAuth tokens.
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.
--env
optional- If defined, Wrangler will load the matching environment’s configuration before building and deploying. Refer to Environments for more information.
To use this command, the following fields are required in your wrangler.toml
file:
-
name
string- The name of the Workers project. This is both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- The name of the Workers project. This is both the directory name and
-
type
string- The type of project; one of
webpack
,javascript
, orrust
.
- The type of project; one of
-
account_id
string- The Cloudflare account ID. This can be found in the Cloudflare dashboard, for example,
account_id = "a655bacaf2b4cad0e2b51c5236a6b974"
.
- The Cloudflare account ID. This can be found in the Cloudflare dashboard, for example,
You can publish to <your-worker>.<your-subdomain>.workers.dev ↗ or to a custom domain.
When you publish changes to an existing Worker script, all new requests will automatically route to the updated version of the Worker without downtime. Any inflight requests will continue running on the previous version until completion. Once all inflight requests have finished complete, the previous Worker version will be purged and will no longer handle requests.
Publishing to workers.dev
To publish to *.workers.dev
↗, you will first need to have a subdomain registered. You can register a subdomain by executing the wrangler subdomain
command.
After you have registered a subdomain, add workers_dev
to your wrangler.toml
file.
workers_dev
bool- When
true
, indicates that the Worker should be deployed to a*.workers.dev
domain.
- When
Publishing to your own domain
To publish to your own domain, specify these three fields in your wrangler.toml
file.
-
zone_id
string- The Cloudflare zone ID, for example,
zone_id = "b6558acaf2b4cad1f2b51c5236a6b972"
, which can be found in the Cloudflare dashboard ↗.
- The Cloudflare zone ID, for example,
-
route
string- The route you would like to publish to, for example,
route = "example.com/my-worker/*"
.
- The route you would like to publish to, for example,
-
routes
Array- The routes you would like to publish to, for example,
routes = ["example.com/foo/*", example.com/bar/*]
.
- The routes you would like to publish to, for example,
Publishing the same code to multiple domains
To publish your code to multiple domains, refer to the documentation for environments.
dev
wrangler dev
is a command that establishes a connection between localhost
and a global network server that operates your Worker in development. A cloudflared
tunnel forwards all requests to the global network server, which continuously updates as your Worker code changes. This allows full access to Workers KV, Durable Objects and other Cloudflare developer platform products. The dev
command is a way to test your Worker while developing.
-
--env
optional- If defined, Wrangler will load the matching environment’s configuration. Refer to Environments for more information.
-
--ip
optional- The IP to listen on, defaults to
127.0.0.1
.
- The IP to listen on, defaults to
-
--port
optional- The port to listen on, defaults to
8787
.
- The port to listen on, defaults to
-
--host
optional- The host to forward requests to, defaults to the zone of the project or to
tutorial.cloudflareworkers.com
if unauthenticated.
- The host to forward requests to, defaults to the zone of the project or to
-
--local-protocol
optional- The protocol to listen to requests on, defaults to
http
.
- The protocol to listen to requests on, defaults to
-
--upstream-protocol
optional- The protocol to forward requests to host on, defaults to
https
.
- The protocol to forward requests to host on, defaults to
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
.
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 ↗.
tail
Start a session to livestream logs from a deployed Worker.
--format $FORMAT
json|pretty- The format of the log entries.
--status $STATUS
- Filter by invocation status [possible values:
ok
,error
,canceled
].
- Filter by invocation status [possible values:
--header $HEADER
- Filter by HTTP header.
--method $METHOD
- Filter by HTTP method.
--sampling-rate $RATE
- Add a percentage of requests to log sampling rate.
--search $SEARCH
- Filter by a text match in
console.log
messages.
- Filter by a text match in
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).
preview
Preview your project using the Cloudflare Workers preview service ↗.
Default values indicated by =value.
-
--env $ENVIRONMENT_NAME
optional- If defined, Wrangler will load the matching environment’s configuration. Refer to Environments for more information.
-
--watch
recommended- When enabled, any changes to the Worker project 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.
- When enabled, any changes to the Worker project will continually update the preview service with the newest version of your project. By default,
-
$METHOD
=“GET” optional- The type of request to preview your Worker with (
GET
,POST
).
- The type of request to preview your Worker with (
-
$BODY
=“Null” optional- The body string to post to your preview Worker request. For example,
wrangler preview post hello=hello
.
- The 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
file 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 ensure that you are not writing values to KV that would break your production Worker.
To create a preview_id
run:
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
to open your browser. To make wrangler preview
work with WSL, you should set your $BROWSER
to the path of your browser binary:
Spaces in filepaths are not common in Linux, and some programs like xdg-open
will break on paths with spaces ↗. You can work around this by linking the binary to your /usr/local/bin
:
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 are using WSL 2, you will need to install wsl-open
following 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 domain:
Default values indicated by =value.
--env $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
This command will forward the JSON response from the List Routes API. Each object within the JSON list will include the route id, route pattern, and the assigned Worker name for the route. Piping this through a tool such as jq
will render the output nicely.
Default values indicated by =value.
-
$ID
required- The hash of the route ID to delete.
-
--env $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
subdomain
Create or change your *.workers.dev
↗ subdomain.
secret
Interact with your secrets.
put
Create or replace a secret.
You will be prompted to input the secret’s value. This command can receive piped input, so the following example is also possible:
-
name
- The variable name to be accessible in the script.
-
--env $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
delete
Delete a secret from a specific script.
-
name
- The variable name to be accessible in the script.
-
--env $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
list
List all the secret names bound to a specific script.
--env $ENVIRONMENT_NAME
optional- If defined, only the specified environment’s secrets will be listed. Refer to Environments for more information.
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:
- must configure an
account_id
in your project’swrangler.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 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:
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:
To write a value to your KV namespace using Wrangler, run the wrangler kv:key put
subcommand.
Instead of --binding
, you may use --namespace-id
to specify which KV namespace should receive the operation:
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:
To insert a value into a specific KV namespace, you can use:
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:
-
With a
--binding
:- 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
:
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:
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:
To learn more about environments, refer to Environments.
kv:namespace
create
Create a new namespace.
-
$NAME
- The name of the new namespace.
-
--env $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace (the
preview_id
value) instead of production.
- Interact with a preview namespace (the
Usage
list
List all KV namespaces associated with an account ID.
Usage
This example passes the Wrangler command through the jq
command:
delete
Delete a given namespace.
-
--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 $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace instead of production.
Usage
kv:key
put
Write a single key-value pair to a particular namespace.
-
$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 $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace instead of production. Pass this to the
wrangler.toml
file’skv_namespaces.preview_id
instead ofkv_namespaces.id
.
- Interact with a preview namespace instead of production. Pass this to the
-
--ttl
optional- The lifetime (in number of seconds) the document should exist before expiring. Must be at least
60
seconds. This option takes precedence over theexpiration
option.
- The lifetime (in number of seconds) the document should exist before expiring. Must be at least
-
--expiration
optional- The timestamp, in UNIX seconds, indicating when the key-value pair should expire.
-
--path
optional- When defined, Wrangler reads the
--path
file location to upload its contents as KV documents. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.
- When defined, Wrangler reads the
Usage
list
Output a list of all keys in a given namespace.
-
--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 $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--prefix
optional- A prefix to filter listed keys.
Usage
This example passes the Wrangler command through the jq
command:
get
Read a single value by key from the given namespace.
-
$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 $ENVIRONMENT_NAME
optional- If defined, the operation will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
file’skv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
Usage
delete
Removes a single key value pair from the given namespace.
-
$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
.
- Perform on a specific environment specified as
-
--preview
optional- 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
kv:bulk
put
Write a file full of key-value pairs to the given namespace.
-
$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 $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
file’skv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
This command takes a JSON file as an argument with a list of key-value pairs to upload. An example of JSON input:
In order to save JSON data, cast value
to a string:
The schema below 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 25 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 the document should exist before expiring. Must be at least
60
seconds.
- The number of seconds the document should exist before expiring. Must be at least
-
base64
bool 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
.
- 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
If both expiration
and expiration_ttl
are specified for a given key, the API will prefer expiration_ttl
.
Usage
delete
Delete all specified keys within a given namespace.
-
$FILENAME
required- The file with key-value pairs 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 $ENVIRONMENT_NAME
optional- If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
-
--preview
optional- Interact with a preview namespace instead of production. Pass this to use your
wrangler.toml
file’skv_namespaces.preview_id
instead ofkv_namespaces.id
- Interact with a preview namespace instead of production. Pass this to use your
This command takes a JSON file as an argument with a list of key-value pairs to delete. An example of JSON input:
-
key
string required- The key’s name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
-
value
string required- This field must be specified for deserialization purposes, but is unused because the provided keys are being deleted, not written.
Usage
Environment variables
Wrangler supports any wrangler.toml
keys passed in as environment variables. This works by passing in CF_
+ any uppercased TOML key. For example:
CF_NAME=my-worker CF_ACCOUNT_ID=1234 wrangler dev