Workers

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]

• 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
  • Develop against remote resources and data stored on Cloudflare's network.
• --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.

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]

• 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

    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.

• --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.

• --triggers, --schedule, --schedules string[] optional

  • Cron schedules to attach to the deployed Worker. Refer to Cron Trigger Examples.

• --routes, --route string[] optional

  • Routes where this Worker will be deployed.
  • For example: --route example.com/*.

• --domain string[] optional

  • Custom domains where this Worker will be deployed.
  • For example: --domain example.com.

• --tsconfig string optional

  • Path to a custom tsconfig.json file.

• --minify boolean optional

  • Minify the bundled Worker before deploying.

• --dry-run boolean (default: false) optional

  • Compile a project without actually deploying to live servers. Combined with --outdir, this is also useful for testing the output of npx wrangler deploy. It also gives developers a chance to upload our generated sourcemap to a service like Sentry, so that errors from the Worker can be mapped against source code, but before the service goes live.

• --keep-vars boolean (default: false) optional

  • It is recommended best practice to treat your Wrangler developer environment as a source of truth for your Worker configuration, and avoid making changes via the Cloudflare dashboard.
  • If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behaviour set keep-vars to true.
  • Secrets are never deleted by a deployment whether this flag is true or false.

• --secrets-file string optional

  • Path to a file containing secrets to upload alongside the deployment. Accepts JSON or .env format — the same formats used by wrangler secret bulk. Existing secrets not included in the file are preserved from the previous version. Refer to Secrets — Upload secrets alongside code for more details.

• --dispatch-namespace string optional

  • Specify the Workers for Platforms dispatch namespace to upload this Worker to.

• --metafile string optional

  • Specify a file to write the build metadata from esbuild to. If flag is used without a path string, this defaults to bundle-meta.json inside the directory specified by --outdir. This can be useful for understanding the bundle size.

• --containers-rollout immediate | gradual | none optional

  • Rollout mode for Containers on this deploy. gradual (default) uses rollout_step_percentage. immediate uses one 100% step (not a simultaneous restart of every container instance). none skips container image and instance updates.

• --strict boolean (default: false) optional

  • Turns on strict mode for the deployment command, meaning that the command will be more defensive and prevent deployments which could introduce potential issues. In particular, this mode prevents deployments if the deployment would potentially override remote settings in non-interactive environments.

• --tag string optional

  • A tag for this Worker version. Matches the behavior of wrangler versions upload --tag.

• --message string optional

  • A descriptive message for this Worker version and deployment. Matches the behavior of wrangler versions upload --message. The message is also applied to the deployment.

• --yes boolean (default: false) optional

  • Skip confirmation prompts and run automatic project configuration non-interactively using detected settings. Only applicable when no Wrangler configuration file exists in your project.

• --temporary boolean optional

  • Deploy with a temporary preview account when no Cloudflare credentials are available. Requires Wrangler 4.102.0 or later. Wrangler prints a claim URL that lets you claim the deployment within 60 minutes. This is intended for AI agents and other first-time deployment flows. If Wrangler can already use OAuth, CLOUDFLARE_API_TOKEN, or a global API key, this flag returns an error. For more information, refer to Claim deployments.

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.

preview

Create a Preview deployment of the current Worker for branch and pull request work. Use wrangler deploy for production.

wrangler preview [<SCRIPT>] [OPTIONS]

• 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 Preview. Defaults to the current git branch.
• --tag string optional
  • A tag for this Preview deployment.
• --message string optional
  • A descriptive message for this Preview deployment.
• --json boolean (default: false) optional
  • Return machine-readable output.
• --ignore-base-config boolean (default: false) optional
  • Only use settings from your Wrangler file, ignoring the Preview base config configured in the Cloudflare dashboard.
• --worker-name string optional
  • Name of the Worker to target. Defaults to the name in your local Wrangler file.

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.

For example:

npx wrangler preview --name feature-branch

Other Preview branches are not affected.

preview delete

Delete a Preview and all its deployments

npx wrangler preview delete

yarn wrangler preview delete

pnpm wrangler preview delete

• --name string

  Name of the Preview to delete (defaults to current git branch)

• --skip-confirmation boolean alias: --y default: false

  Skip the confirmation prompt

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview secret put

Create or update a secret variable on a Worker Preview and create a new deployment

npx wrangler preview secret put <KEY>

yarn wrangler preview secret put <KEY>

pnpm wrangler preview secret put <KEY>

• <KEY> string required

  The secret name to be accessible in the Worker

• --name string

  Name of the Preview (defaults to current git branch)

• --message string

  A descriptive message for this Preview deployment

• --tag string

  A tag for this Preview deployment

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview secret delete

Delete a secret variable from a Worker Preview and create a new deployment

npx wrangler preview secret delete <KEY>

yarn wrangler preview secret delete <KEY>

pnpm wrangler preview secret delete <KEY>

• <KEY> string required

  The secret name to delete

• --name string

  Name of the Preview (defaults to current git branch)

• --message string

  A descriptive message for this Preview deployment

• --tag string

  A tag for this Preview deployment

• --skip-confirmation boolean alias: --y default: false

  Skip the confirmation prompt

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview secret list

List all secrets on a Worker Preview's latest deployment

npx wrangler preview secret list

yarn wrangler preview secret list

pnpm wrangler preview secret list

• --name string

  Name of the Preview (defaults to current git branch)

• --json boolean default: false

  Return output as JSON

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview secret bulk

Upload multiple secrets to a Worker Preview and create a new deployment

npx wrangler preview secret bulk [FILE]

yarn wrangler preview secret bulk [FILE]

pnpm wrangler preview secret bulk [FILE]

• [FILE] string

  The file of key-value pairs to upload, as JSON or .env format

• --name string

  Name of the Preview (defaults to current git branch)

• --message string

  A descriptive message for this Preview deployment

• --tag string

  A tag for this Preview deployment

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview base-config secret put

Create or update a secret variable on the Preview base config

npx wrangler preview base-config secret put <KEY>

yarn wrangler preview base-config secret put <KEY>

pnpm wrangler preview base-config secret put <KEY>

• <KEY> string required

  The secret name to be accessible in the Worker

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview base-config secret delete

Delete a secret variable from the Preview base config

npx wrangler preview base-config secret delete <KEY>

yarn wrangler preview base-config secret delete <KEY>

pnpm wrangler preview base-config secret delete <KEY>

• <KEY> string required

  The secret name to delete

• --skip-confirmation boolean alias: --y default: false

  Skip the confirmation prompt

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

preview base-config secret list

List all secrets on the Preview base config

npx wrangler preview base-config secret list

yarn wrangler preview base-config secret list

pnpm wrangler preview base-config secret list

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

• --json boolean default: false

  Return output as JSON

preview base-config secret bulk

Upload multiple secrets to the Preview base config

npx wrangler preview base-config secret bulk [FILE]

yarn wrangler preview base-config secret bulk [FILE]

pnpm wrangler preview base-config secret bulk [FILE]

• [FILE] string

  The file of key-value pairs to upload, as JSON or .env format

• --worker-name string

  Name of the Worker to target (defaults to the name in your local config file)

delete

Delete your Worker and all associated Cloudflare developer platform resources.

wrangler delete [<SCRIPT>] [OPTIONS]

• 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.
• --env string optional
  • Perform on a specific environment.
• --dry-run boolean (default: false) optional
  • Do not actually delete the Worker. This is useful for testing the output of wrangler delete.

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.

setup

🪄 Setup a project to work on Cloudflare

npx wrangler setup

yarn wrangler setup

pnpm wrangler setup

• --yes boolean alias: --y default: false

  Answer "yes" to any prompts for configuring your project

• --build boolean default: false

  Run your project's build command once it has been configured

• --dry-run boolean

  Runs the command without applying any filesystem modifications

This command configures your project for Cloudflare Workers without deploying. It performs the same automatic project configuration as wrangler deploy, but does not deploy. This is useful when you want to review the generated configuration before deploying.

secret

Manage the secret variables for a Worker.

This action creates a new version of the Worker and deploys it immediately. To only create a new version of the Worker, use the wrangler versions secret commands.

secret put

Create or update a secret for a Worker

npx wrangler secret put <KEY>

yarn wrangler secret put <KEY>

pnpm wrangler secret put <KEY>

• <KEY> string required

  The variable name to be accessible in the Worker

• --name string

  Name of the Worker. If this is not specified, it will default to the name specified in your Wrangler config file.

When running this command, you will be prompted to input the secret's value:

npx wrangler secret put FOO

? Enter a secret value: > ***
🌀 Creating the secret for script worker-app
✨ Success! Uploaded secret FOO

The put command can also receive piped input. For example:

echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY

secret delete

Delete a secret from a Worker

npx wrangler secret delete <KEY>

yarn wrangler secret delete <KEY>

pnpm wrangler secret delete <KEY>

• <KEY> string required

  The variable name to be accessible in the Worker

• --name string

  Name of the Worker. If this is not specified, it will default to the name specified in your Wrangler config file.

secret list

List all secrets for a Worker

npx wrangler secret list

yarn wrangler secret list

pnpm wrangler secret list

• --name string

  Name of the Worker. If this is not specified, it will default to the name specified in your Wrangler config file.

• --format "json" | "pretty" default: json

  The format to print the secrets in

The following is an example of listing the secrets for the current Worker.

npx wrangler secret list

[
  {
    "name": "FOO",
    "type": "secret_text"
  }
]

secret bulk

Create, update, or delete multiple secrets for a Worker in a single request, with up to 100 secrets per command.

npx wrangler secret bulk [FILE]

yarn wrangler secret bulk [FILE]

pnpm wrangler secret bulk [FILE]

• [FILE] string

  The file of key-value pairs to create, update, or delete, as JSON in form {"key": "value", ...} or .env file in the form KEY=VALUE. Set a key to null in the JSON file to delete it. Deletion is not supported with .env files. If omitted, Wrangler expects to receive input from stdin rather than a file.

• --name string

  Name of the Worker. If this is not specified, it will default to the name specified in your Wrangler config file.

The following is an example of creating, updating, and deleting secrets from a JSON file redirected to stdin. Set a key to null to delete it.

{
	"secret-name-1": "secret-value-1",
	"secret-name-2": "secret-value-2",
	"secret-name-3": null
}

npx wrangler secret bulk < secrets.json

🌀 Processing the secrets for the Worker "script-name"
✨ Successfully created secret for key: secret-name-1
✨ Successfully created secret for key: secret-name-2
💥 Successfully deleted secret for key: secret-name-3

Finished processing secrets file:
✨ 2 secrets successfully created
💥 1 secrets successfully deleted

tail

🦚 Start a log tailing session for a Worker

npx wrangler tail [WORKER]

yarn wrangler tail [WORKER]

pnpm wrangler tail [WORKER]

• [WORKER] string

  Name or route of the worker to tail

• --format "json" | "pretty"

  The format of log entries

• --status "ok" | "error" | "canceled"

  Filter by invocation status

• --header string

  Filter by HTTP header

• --method string

  Filter by HTTP method

• --sampling-rate number

  Adds a percentage of requests to log sampling rate

• --search string

  Filter by a text match in console.log messages

• --ip string

  Filter by the IP address the request originates from. Use "self" to filter for your own IP

• --version-id string

  Filter by Worker version

After starting wrangler tail, you will receive a live feed of console and exception logs for each request your Worker receives.

If your Worker has a high volume of traffic, the tail might enter sampling mode. This will cause some of your messages to be dropped and a warning to appear in your tail logs. To prevent messages from being dropped, add the options listed above to filter the volume of tail messages.

If sampling persists after using options to filter messages, consider using instant logs.

versions

versions upload

Upload a new version of your Worker that is not deployed immediately.

npx wrangler versions upload [PATH]

yarn wrangler versions upload [PATH]

pnpm wrangler versions upload [PATH]

• [PATH] string

  The path to an entry point for your Worker or a directory of static assets

• --name string

  Name of the Worker

• --tag string

  A tag for this Worker Version

• --message string

  A descriptive message for this Worker Version

• --no-bundle boolean default: false

  Skip internal build steps and directly upload Worker

• --outdir string

  Output directory for the bundled Worker

• --outfile string

  Output file for the bundled worker

• --compatibility-date string

  Date to use for compatibility checks

• --compatibility-flags string alias: --compatibility-flag

  Flags to use for compatibility checks

• --latest boolean default: false

  Use the latest compatibility date supported by this version of Wrangler

• --assets string

  Static assets to be served. Replaces Workers Sites.

• --var string

  A key-value pair to be injected into the script as a variable

• --define string

  A key-value pair to be substituted in the script

• --alias string

  A module pair to be substituted in the script

• --jsx-factory string

  The function that is called for each JSX element

• --jsx-fragment string

  The function that is called for each JSX fragment

• --tsconfig string

  Path to a custom tsconfig.json file

• --minify boolean

  Minify the Worker

• --upload-source-maps boolean

  Include source maps when uploading this Worker

• --dry-run boolean

  Compile a project and run checks without actually uploading the Worker

• --secrets-file string

  Path to a file containing secrets to upload with the version (JSON or .env format). Applies additively with secrets from previous deployments - omitted secrets will not be deleted.

• --keep-vars boolean default: false

  When not used (or set to false), Wrangler will delete all vars before setting those found in the Wrangler configuration. When used (and set to true), the environment variables are not deleted before the deployment. If you set variables via the dashboard you probably want to use this flag. Note that secrets are never deleted by deployments.

• --strict boolean default: false

  Enables strict mode, which prevents uploads when there are conflicting remote changes.

• --preview-alias string

  Name of an alias for this Worker version

versions deploy

Deploy a previously created version of your Worker all at once or create a gradual deployment to incrementally shift traffic to a new version by following an interactive prompt.

npx wrangler versions deploy [VERSION-SPECS]

yarn wrangler versions deploy [VERSION-SPECS]

pnpm wrangler versions deploy [VERSION-SPECS]

• --durable-objects-code-update-mode string

  How to update Durable Object code: immediate, or deferred followed by a maximum delay (for example, deferred 30s)

• --name string

  Name of the worker

• --version-id string

  Worker Version ID(s) to deploy

• --percentage number

  Percentage of traffic to split between Worker Version(s) (0-100)

• [VERSION-SPECS] string

  Shorthand notation to deploy Worker Version(s) [<version-id>@<percentage>..]. Omitted percentages share the remaining traffic.

• --version-tag string

  Worker Version tag(s) to deploy, resolved to a Version ID against the deployable versions. Supports the shorthand notation [<version-tag>@<percentage>..].

• --message string

  Description of this deployment (optional)

• --yes boolean alias: --y default: false

  Automatically accept defaults to prompts

• --dry-run boolean default: false

  Don't actually deploy

versions list

Retrieve details for the 10 most recent versions. Details include Version ID, Created on, Author, Source, and optionally, Tag or Message.

npx wrangler versions list

yarn wrangler versions list

pnpm wrangler versions list

• --name string

  Name of the Worker

• --json boolean default: false

  Display output as JSON

versions view

View the details of a specific version of your Worker

npx wrangler versions view <VERSION-ID>

yarn wrangler versions view <VERSION-ID>

pnpm wrangler versions view <VERSION-ID>

• <VERSION-ID> string required

  The Worker Version ID to view

• --name string

  Name of the worker

• --json boolean default: false

  Display output as JSON

versions secret put

Create or update a secret variable for a Worker

npx wrangler versions secret put [KEY]

yarn wrangler versions secret put [KEY]

pnpm wrangler versions secret put [KEY]

• [KEY] string

  The variable name to be accessible in the Worker

• --name string

  Name of the Worker

• --message string

  Description of this deployment

• --tag string

  A tag for this version

versions secret delete

Delete a secret variable from a Worker

npx wrangler versions secret delete [KEY]

yarn wrangler versions secret delete [KEY]

pnpm wrangler versions secret delete [KEY]

• [KEY] string

  The variable name to be accessible in the Worker

• --name string

  Name of the Worker

• --message string

  Description of this deployment

• --tag string

  A tag for this version

versions secret bulk

Create or update a secret variable for a Worker

npx wrangler versions secret bulk [FILE]

yarn wrangler versions secret bulk [FILE]

pnpm wrangler versions secret bulk [FILE]

• [FILE] string

  The file of key-value pairs to upload, as JSON in form {"key": value, ...} or .dev.vars file in the form KEY=VALUE

• --name string

  Name of the Worker

• --message string

  Description of this deployment

• --tag string

  A tag for this version

triggers

triggers deploy

Experimental

Apply changes to triggers (Routes or domains and Cron Triggers) when using wrangler versions upload

npx wrangler triggers deploy

yarn wrangler triggers deploy

pnpm wrangler triggers deploy

• --name string

  Name of the worker

• --triggers string aliases: --schedule, --schedules

  cron schedules to attach

• --routes string alias: --route

  Routes to upload

• --experimental-route-zones boolean aliases: --x-route-zones default: false

  Experimental: Enable the --zone and --zone-id flags to attach a zone to the routes passed via --route

• --zone string alias: --zones

  Experimental (requires --x-route-zones): Zone name for the routes passed via --route. Pass one value to apply it to all routes, or one value per --route in the same order

• --zone-id string alias: --zone-ids

  Experimental (requires --x-route-zones): Zone ID for the routes passed via --route. Pass one value to apply it to all routes, or one value per --route in the same order

• --dry-run boolean default: false

  Don't actually deploy

deployments

Deployments track the version(s) of your Worker that are actively serving traffic.

deployments list

Displays the 10 most recent deployments of your Worker

npx wrangler deployments list

yarn wrangler deployments list

pnpm wrangler deployments list

• --name string

  Name of the Worker

• --json boolean default: false

  Display output as JSON

deployments status

View the current state of your production

npx wrangler deployments status

yarn wrangler deployments status

pnpm wrangler deployments status

• --name string

  Name of the Worker

• --json boolean default: false

  Display output as JSON

rollback

wrangler rollback [<VERSION_ID>] [OPTIONS]

• VERSION_ID string optional
  • The ID of the version you wish to roll back to. If not supplied, the rollback command defaults to the version uploaded before the latest version.
• --name string optional
  • Perform on a specific Worker rather than inheriting from the Wrangler configuration file.
• --message string optional
  • Add message for rollback. Accepts empty string. When specified, interactive prompts for rollback confirmation and message are skipped.

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.

types

Generate types based on your Worker configuration, including Env types based on your bindings, module rules, and runtime types based on thecompatibility_date and compatibility_flags in your config file.

wrangler types [<PATH>] [OPTIONS]

Multi-environment support

By default, wrangler types generates types for bindings from all environments defined in your configuration file. This ensures your generated Env type includes all bindings that might be used across different deployment environments (such as staging and production), preventing TypeScript errors when accessing environment-specific bindings.

For example, if you have a KV namespace binding only in production and an R2 bucket binding only in staging, both will be included in the generated types as optional properties.

To generate types for only a specific environment, use the --env flag.

Options

• PATH string (default: `./worker-configuration.d.ts`)
  • The path to where types for your Worker will be written.
  • The path must have a d.ts extension.
• --env string optional
  • Generate types for bindings in a specific environment only, rather than aggregating bindings from all environments.
• --env-interface string (default: `Env`)
  • The name of the interface to generate for the environment object.
  • Not valid if the Worker uses the Service Worker syntax.
• --include-runtime boolean (default: true)
  • Whether to generate runtime types based on thecompatibility_date and compatibility_flags in your config file.
• --include-env boolean (default: true)
  • Whether to generate Env types based on your Worker bindings.
• --strict-vars boolean optional (default: true)
  • Control the types that Wrangler generates for vars bindings.
  • If true, (the default) Wrangler generates literal and union types for bindings (e.g. myVar: 'my dev variable' | 'my prod variable').
  • If false, Wrangler generates generic types (e.g. myVar: string). This is useful when variables change frequently, especially when working across multiple environments.
• --check boolean optional
  • Compare the generated file's recorded environment/configuration hash and runtime header with the current Wrangler configuration and runtime inputs.
  • This does not compare or validate the generated file body or regenerate the file.
  • Exits with code 0 if types are up-to-date, or code 1 if types are out-of-date.
  • Useful for CI/CD pipelines and pre-commit hooks to detect input changes that require regeneration.
• --config, -c string[] optional
  • Path(s) to Wrangler configuration file. If the Worker you are generating types for has service bindings or bindings to Durable Objects, you can also provide the paths to those configuration files so that the generated Env type will include RPC types. For example, given a Worker with a service binding, wrangler types -c wrangler.toml -c ../bound-worker/wrangler.toml will generate an Env type like this:
  interface Env {
  	SERVICE_BINDING: Service<import("../bound-worker/src/index").Entrypoint>;
  }

check

startup

Analyze your Worker's startup phase. Wrangler reports bundle size and a summary of local CPU activity. It also saves a detailed CPU profile.

wrangler check startup

Bundle: 42.31 KiB / gzip: 11.24 KiB

Local startup profile:
  Profile window: 25.2 ms
  Sampled time: 24.8 ms
  Active: 18.4 ms (including 1.2 ms garbage collection)
  Idle: 6.4 ms
  Samples: 25

The local startup profile includes the following metrics:

Import the generated .cpuprofile file into Chrome DevTools or open it directly in VS Code to view a flamegraph. When a Worker deployment fails with a startup time error, Wrangler also generates this profile automatically.

• --args string optional
  • To customise the way wrangler check startup builds your Worker for analysis, provide the exact arguments you use when deploying your Worker with wrangler deploy, or your Pages project with wrangler pages functions build. For instance, if you deploy your Worker with wrangler deploy --no-bundle, you should use wrangler check startup --args="--no-bundle" to profile the startup phase.
• --worker string optional
  • If you don't use Wrangler to deploy your Worker, you can use this argument to provide a Worker bundle to analyse. This should be a file path to a serialized multipart upload, with the exact same format as the API expects.
• --pages boolean optional
  • If you don't use a Wrangler config file with your Pages project (i.e. a Wrangler config file containing pages_build_output_dir), use this flag to force wrangler check startup to treat your project as a Pages project.

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.