Workers (3)

Last updated Oct 26, 2026 Wrangler commands for creating, developing, deploying, and managing Workers.

init

Create a new project via the create-cloudflare-cli (C3) tool. A variety of web frameworks are available to choose from as well as templates. Dependencies are installed by default, with the option to deploy your project immediately.

wrangler init [<NAME>] [OPTIONS]
  • NAME string optional (default: name of working directory)
  • The name of the Workers project. This is both the directory name and name property in the generated Wrangler configuration.
  • --yes boolean optional
  • Answer yes to any prompts for new projects.
  • --from-dash string optional
  • Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name. wrangler init --from-dash <WORKER_NAME>.
  • The --from-dash command will not automatically sync changes made to the dashboard after the command is used. Therefore, it is recommended that you continue using the CLI.

The following global flags work on every command:

  • --help boolean
  • Show help.
  • --config string (not supported by Pages)
  • Path to your Wrangler configuration file.
  • --cwd string
  • Run as if Wrangler was started in the specified directory instead of the current working directory.

dev

Start a local server for developing your Worker.

wrangler dev [<SCRIPT>] [OPTIONS]

By default, wrangler dev executes your Worker in a local workerd process, which is not a hardened sandbox. Only run code you trust. For more information, refer to Local development security considerations.

Note

None of the options for this command are required. Many of these options can be set in your Wrangler file. Refer to the Wrangler configuration documentation for more information.

  • SCRIPT string
  • The path to an entry point for your Worker. Only required if your Wrangler configuration file does not include a main key (for example, main = "index.js").
  • --name string optional
  • Name of the Worker.
  • --config, -c string[] optional
  • Path(s) to Wrangler configuration file. If not provided, Wrangler will use the nearest config file based on your current working directory.
  • You can provide multiple configuration files to run multiple Workers in one dev session like this: wrangler dev -c ./wrangler.toml -c ../other-worker/wrangler.toml. The first config will be treated as the primary Worker, which will be exposed over HTTP. The remaining config files will only be accessible via a service binding from the primary Worker.
  • --no-bundle boolean (default: false) optional
  • Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to Bundling for more information.
  • --env string optional
  • Perform on a specific environment.
  • --compatibility-date string optional
  • A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.
  • --compatibility-flags, --compatibility-flag string[] optional
  • Flags to use for compatibility checks.
  • --latest boolean (default: true) optional
  • Use the latest version of the Workers runtime.
  • --ip string optional
  • IP address to listen on, defaults to localhost.
  • --port number optional
  • Port to listen on.
  • --inspector-port number optional
  • Port for devtools to connect to.
  • --routes, --route string[] optional
  • Routes to upload.
  • For example: --route example.com/*.
  • --host string optional
  • Host to forward requests to, defaults to the zone of project.
  • --local-protocol 'http'|'https' (default: http) optional
  • Protocol to listen to requests on.
  • --https-key-path string optional
  • Path to a custom certificate key.
  • --https-cert-path string optional
  • Path to a custom certificate.
  • --local-upstream string optional
  • Host to act as origin in local mode, defaults to dev.host or route.
  • --infer-origin-from-routes boolean (default: true) optional
  • Use the first configured route to infer the origin ( request.url and the Host header) seen by the Worker in local mode. Set to false to preserve the real local origin, for example localhost:8787, so that Host- or Origin-sensitive logic behaves the same as the actual local request. An explicit --host, --local-upstream, or dev.host takes precedence either way.
  • --assets string optional beta
  • Folder of static assets to be served. Replaces Workers Sites. Visit assets for more information.
  • --site string optional deprecated, use `--assets`
  • Folder of static assets for Workers Sites. Caution

Workers Sites is deprecated. Please use Workers Assets or Pages. - --site-include string[] optional deprecated - Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded. - --site-exclude string[] optional deprecated - Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded. - --upstream-protocol 'http'|'https' (default: https) optional - Protocol to forward requests to host on. - --var key:value\[] optional - Array of key:value pairs to inject as variables into your code. The value will always be passed as a string to your Worker. - For example, --var "git_hash:'$(git rev-parse HEAD)'" "test:123" makes the git_hash and test variables available in your Worker's env. - This flag is an alternative to defining vars in your Wrangler configuration file. If defined in both places, this flag's values will be used. - --define key:value\[] optional - Array of key:value pairs to replace global identifiers in your code. - For example, --define "GIT_HASH:'$(git rev-parse HEAD)'" will replace all uses of GIT_HASH with the actual value at build time. - This flag is an alternative to defining define in your Wrangler configuration file. If defined in both places, this flag's values will be used. - --tsconfig string optional - Path to a custom tsconfig.json file. - --minify boolean optional - Minify the Worker. - --persist-to string optional - Specify directory to use for local persistence. - --remote boolean (default: false) optional - Execute your Worker in a preview environment on Cloudflare. All bindings connect to remote resources. - --tunnel boolean (default: false) optional - Expose your local dev server over a Cloudflare Tunnel. For more information, refer to Share a local dev server. - --tunnel-name string optional - Use an existing named Cloudflare Tunnel. Combine with --tunnel to open it automatically at startup. - --test-scheduled boolean (default: false) optional - Exposes a /cdn-cgi/local/scheduled fetch route which will trigger a scheduled event (Cron Trigger) for testing during development. To simulate different cron patterns, a cron query parameter can be passed in: /cdn-cgi/local/scheduled?cron=*+*+*+*+*. - --log-level 'debug'|'info'|'log'|'warn'|'error|'none' (default: log) optional - Specify Wrangler's logging level. - --show-interactive-dev-session boolean (default: true if the terminal supports interactivity) optional - Show the interactive dev session. - --alias Array<string> - Specify modules to alias using module aliasing. - --types boolean (default: false) optional - Generate types from your Worker configuration. - --local boolean (default: false) optional - Run in local mode. In this mode: - the Worker code is running locally on your machine - all remote bindings are disabled, which behaves exactly as if they were configured with remote: false.

The following global flags work on every command:

  • --help boolean
  • Show help.
  • --config string (not supported by Pages)
  • Path to your Wrangler configuration file.
  • --cwd string
  • Run as if Wrangler was started in the specified directory instead of the current working directory.

wrangler dev is a way to locally test your Worker while developing. With wrangler dev running, 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.

Note

wrangler dev runs the local workerd runtime with TZ=UTC to match the production Cloudflare runtime. Date and Intl APIs inside your Worker observe UTC during local development, regardless of your machine's timezone.

deploy

Deploy your Worker to Cloudflare.

When you run wrangler deploy in a project directory without a Wrangler configuration file, Wrangler will automatically detect your framework and configure your project for Cloudflare Workers. This command will prompt you to confirm the detected settings before applying changes. Confirm that you would like to proceed, and your project will be configured and deployed.

To deploy from an AI agent or another environment before Cloudflare authentication is available, use wrangler deploy --temporary. This flow requires Wrangler 4.102.0 or later. Wrangler creates or reuses a temporary preview account, deploys to that account, and prints a claim URL. For more information, refer to Claim deployments.

To configure your project without deploying, use wrangler setup instead.

wrangler deploy [<PATH>] [OPTIONS]

Note

None of the options for this command are required. Also, many can be set in your Wrangler file. Refer to the Wrangler configuration documentation for more information.

  • PATH string
  • A path specific what needs to be deployed, this can either be:
    • The path to an entry point for your Worker.
    • Only required if your Wrangler configuration file does not include a main key (for example, main = "index.js").
    • Or the path to an assets directory for the deployment of a static site.
    • Visit assets for more information.
    • This overrides the eventual assets configuration in your Wrangler configuration file.
    • This is equivalent to the --assets option listed below.
    • Note: this option currently only works only in interactive mode (so not in CI systems).
  • --name string optional
  • Name of the Worker.
  • --no-bundle boolean (default: false) optional
  • Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to Bundling for more information.
  • --env string optional
  • Perform on a specific environment. Note

If you're using the Cloudflare Vite plugin, you select the environment at dev or build time via the CLOUDFLARE_ENV environment variable rather than the --env flag. Otherwise, environments are defined in your Worker config file as usual. For more detail on using environments with the Cloudflare Vite plugin, refer to the plugin documentation. - --outdir string optional - Path to directory where Wrangler will write the bundled Worker files. - --compatibility-date string optional - A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. - --compatibility-flags, --compatibility-flag string[] optional - Flags to use for compatibility checks. - --latest boolean (default: true) optional - Use the latest version of the Workers runtime. - --assets string optional beta - Folder of static assets to be served. Replaces Workers Sites. Visit assets for more information. - --site string optional deprecated, use `--assets` - Folder of static assets for Workers Sites. Caution