GitHub iconEdit on GitHub

Commands

generate

Scaffold a Cloudflare Workers project from a public GitHub repository.

wrangler generate [$NAME] [$TEMPLATE] [--type=$TYPE] [--site]
OptionalDefault value
$NAMEName of WorkerOptional"worker"
$TEMPLATEGitHub URL of the template to base new project off ofOptionalworker-template
--typeType of project. Acceptable values:"webpack", "javascript", or "rust"Optional"webpack"
--siteSame of template but based off of default site templateOptionalN/A

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]
OptionalDefault value
$NAMEName of WorkerOptionalThe name of working directory
--typeType of project. Acceptable values:"webpack", "javascript", or "rust"Optional"webpack"
--siteInitiates the project to a Workers site.OptionalN/A

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]
Required
--envPerform on a specific environment specified as $ENVIRONMENT_NAMEOptional

config

Configure your global Cloudflare user. This is an interactive command that will prompt you for your API token.

wrangler config [--api-key]
Optional
--api-keyTo provide your email and global API key (this is not recommended for security reasons) instead of a token.Optional

You can also use 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]
Required
--envPerform on a specific environment specified as $ENVIRONMENT_NAMEOptional

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

KeyValueExample
namethe name of your workername = "your-worker"
typebuild type (webpack, rust, or javascript)type = "webpack"
account_idyour Cloudflare account ID, this can be found in the Cloudflare dashboard`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.

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

KeyValueExample
zone_idYour Cloudflare zone ID*zone_id = "b6558acaf2b4cad1f2b51c5236a6b972"
route OR routesThe route(s) you would like to publish toroute = "example.com/my-worker/*" or
routes = ["example.com/foo/*", example.com/bar/*]

*Note: Your Cloudflare Zone ID can be found in the Cloudflare dashboard.

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 (alpha)

Disclaimer

This feature is still in alpha! The way this tool works in the future will change, proceed with caution.

Usage

wrangler dev will start a server on localhost that connects to Cloudflare's servers and executes your Worker on incoming HTTP requests. After starting wrangler dev in a directory with a project, you can send it HTTP requests to test your Worker with clients such as cURL, Postman, or your browser.

You should run wrangler dev from your Worker directory, and if your Worker makes any requests to a backend, you should specify the host with --host example.com.

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.

If you have feedback about wrangler dev or general questions, we will respond here.

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]
KeyValue
--port $PORTthe port for your local log server
--metrics-port $PORTthe 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]
OptionalDefault value
--envPerform on a specific environment specified as $ENVIRONMENT_NAMEOptionalThe top level environment
--watchEnable live preview, so on changes Wrangler will continually update the preview service with the newest version of your projectRecommendedBy default, wrangler preview will only bundle your project a single time.
$METHODType of request to preview your worker with (get, post)OptionalGET
$BODYBody string to post to your preview worker request. For example wrangler preview post hello=helloOptionalNull

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]
Optional
--envPerform on a specific environment specified as $ENVIRONMENT_NAMEOptional

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]
Optional
--envPerform on a specific environment specified as $ENVIRONMENT_NAMEOptional
\$IDThe hash of the route ID to deleteRequired

kv

Interact with your Cloudflare Workers KV store. Check out the docs.

secret

Interact with your secrets. Check out the docs.

subdomain

Create or change your workers.dev subdomain.

wrangler subdomain <name>
Definition
$NAMEName of the workers.dev subdomain you wish to deploy to (e.g. name.workers.dev)

If you've already selected a workers.dev subdomain, running wrangler subdomain <name> will update all your currently running Workers to run on the new subdomain (e.g. hello.world.workers.dev will now run on hello.new-world.workers.dev).