Github iconEdit on Github

Commands

generate

Scaffold a project, including boilerplate for a Rust library and a Cloudflare Worker. You can pass a name and template to this command optionally.

wrangler generate <name> <template> --type=["webpack", "javascript", "rust"] --site

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

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 repository yourself.

wrangler init <name> --type=["webpack", "javascript", "rust"] --site

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

  • name: defaults to the name of your working directory
  • type: defaults to "webpack".
  • --site: generates a Workers Site from an existing static site

build

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

Additionally, you can build different environments. This is useful if you have different builds for different environments, but typically isn't needed. For more information see the environments documentation.

config

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

wrangler config
Enter API token:
superlongapitoken

You can also provide your email and global API key (this is not recommended for security reasons):

wrangler config --api-key
Enter email:
testuser@example.com
Enter global API key:
superlongapikey

You can also use environment variables to configure these values.

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

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 dashboardaccount_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 workers.dev subdomain registered. You can register a subdomain by executing:

  wrangler subdomain <name>

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
workers_devfalseworkers_dev = false
routeThe route you would like to publish toroute = "example.com/my-worker/*"
zone_idYour Cloudflare zone ID, this can be found in the Cloudflare dashboardzone_id = "b6558acaf2b4cad1f2b51c5236a6b972"

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.

preview

Preview your project using the Cloudflare Workers preview service.

By default, wrangler preview will only bundle your project a single time. To enable live preview, where Wrangler will continually update the preview service with the newest version of your project, pass the --watch flag:

wrangler preview --watch

You can optionally pass get or post and a body to this command. This will send a request to your worker on the preview service and return the response in your terminal. For example:

GET requests can be sent with

wrangler preview

or

wrangler preview get

POST requests can be sent with

wrangler preview post hello=hello

Additionally, you can preview different environments. This is useful if you have different builds for different environments (like staging vs. production), but typically isn't needed. For more information see the environments documentation.

Previewing on Windows Subsytem 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.

kv

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

secret

Interact with your secrets. Check out the docs.