---
schema_version: 1
route: /t/wrangler.md
tool: "wrangler"
---

# sincecutoff.com /t/wrangler — Wrangler

- name: Wrangler
- kind: cli
- children: none
- homepage: <https://github.com/cloudflare/workers-sdk>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=wrangler`](https://sincecutoff.com/v1/changes.md?tool=wrangler) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### wrangler deploy, versions upload, and preview upload source maps by default (2026-10-13)
- slug: wrangler-deploy-versions-upload-and-preview-upload-source-maps-by-default-2b5ff9de329b
- score: 0.95

How to use it:

When deploying, uploading a version, or creating a preview and you want stack traces mapped to original source, leave `upload_source_maps` unset for Wrangler’s default map generation and upload. Set it to `true` for strict behavior or `false` to opt out; deploy and version upload also accept `--no-upload-source-maps`.

Examples:

```
npx wrangler deploy
```

```
npx wrangler versions upload [PATH]
```

```
wrangler preview [<SCRIPT>] [OPTIONS]
```

- why_it_matters: Deploy, upload a version, or preview a Worker and make logged stack traces point to the original source.
- before: Previously, source map uploads required `upload_source_maps` to be set in config or via `--upload-source-maps`; setting it to `true` kept strict behavior.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.150.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://developers.cloudflare.com/workers/observability/source-maps/>
- gotchas: "Version: 4.150.0"; "upload_source_maps: Boolean Wrangler config key. Omit it for default generation and upload on deploy, version upload, and preview; set `true` for strict behavior or `false` to opt out."; "--upload-source-maps: Boolean flag to include source maps when uploading a Worker; setting it to `true` retains strict behavior."; "--no-upload-source-maps: Opts out of source map uploads for deploy and version upload."; "[PATH]: Path to a Worker entry point or a directory of static assets for `versions upload`."; "[<SCRIPT>]: Optional script argument for `wrangler preview`."; "Prerequisite: For frameworks or custom builds, the build tool must generate source maps; Wrangler uploads maps from an existing build."; "Prerequisite: The documented minimum Wrangler version for `versions upload` is 3.40.0."; "In the default mode, unresolvable source maps are skipped rather than failing the upload."; "`wrangler build --experimental-cf-build-output` includes source maps only when `upload_source_maps = true`."; "`--no-upload-source-maps` is available for deploy and versions upload."

### Workers Assets supports `assets.base_path` (2026-10-06)
- slug: workers-assets-supports-assets-base-path-2f18bb904592
- score: 0.98

How to use it:

To serve the configured assets directory under a public prefix, set `assets.base_path` to that root-relative path in Wrangler configuration. For authored `200` asset rewrites, include the prefix in both the source and destination paths.

Examples:

```
{"assets":{"directory":"./public","base_path":"/docs"}}
```

- why_it_matters: Serve a Workers Assets directory under a public URL prefix while keeping its on-disk layout unchanged.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0>, <https://github.com/cloudflare/workers-sdk/releases>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.148.0"; "assets.directory: Folder of static assets to serve."; "assets.base_path: Public path prefix; the 4.148.0 release example uses `/docs`."; "URL-shaped values are rejected."; "Omitting the option preserves existing root-path behavior."; "Authored `_headers` and `_redirects` rules continue to match full public paths."; "Requests passed to a user Worker, request-facing headers, and redirects retain the public path."; "Docs conflict: The current Wrangler configuration docs describe `assets.directory` but do not list `assets.base_path`; they may reflect a newer or different documentation state than Wrangler 4.148.0. No conflicting behavior was used."

### wrangler dev supports email-protected Quick Tunnels (2026-10-06)
- slug: wrangler-dev-supports-email-protected-quick-tunnels-b1ab84800c30
- score: 0.96

How to use it:

When exposing a local development server through a Quick Tunnel, pass one or more `--tunnel-allowed-mail` flags to `wrangler dev` to require email authentication.

Examples:

```
npx wrangler dev --tunnel --tunnel-allowed-mail <email-or-domain-pattern>
```

- why_it_matters: Expose a local development server through a Quick Tunnel restricted to approved email addresses or domains.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0>, <https://developers.cloudflare.com/workers/local-development/local-dev-tunnels/>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.148.0"; "--tunnel: Opens the tunnel automatically when Wrangler starts."; "--tunnel-allowed-mail <value>: Requires email authentication for the Quick Tunnel; pass one or more flags. Each value is an exact email address or a domain pattern."; "Prerequisite: Wrangler must be available to run `npx wrangler dev`. Quick Tunnels are temporary and do not require a Cloudflare account."; "Each flag value must be an exact email address or a domain pattern."

### wrangler versions secret bulk supports deleting secrets (2026-10-06)
- slug: wrangler-versions-secret-bulk-supports-deleting-secrets-cec5ac20109c
- score: 0.98

How to use it:

When removing secrets from a new Worker version, set each secret’s value to `null` in JSON input, inspect bulk output for created and deleted secrets, then deploy the version to production traffic.

Examples:

```
npx wrangler versions secret bulk <secrets.json>
```

```
npx wrangler versions deploy <version-id>@100%
```

- why_it_matters: Remove secrets from a new Worker version and apply the requested deletions to production traffic.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.148.0"; "[FILE]: File of key-value pairs in JSON or `.dev.vars` format; when omitted, the docs do not specify stdin behavior for this command."; "--name: Worker name."; "--message: Description of the version deployment."; "--tag: Tag for the version."; "[VERSION-SPECS]: Version shorthand `<version-id>@<percentage>`; use `100%` to assign all traffic to that version."; "Prerequisite: Secret bulk input must be JSON to request deletions with `null`; `.env` format does not support deletion."; "Deletion applies to the new Worker version; deploy that version with `wrangler versions deploy` to apply the changes to production traffic."; "Docs conflict: The current Wrangler command docs describe `versions secret bulk` as creating or updating a secret and do not document null-based deletion, while the v4.148.0 release note says it supports deletion. Follow the release note for that changed behavior."

### Local Workflows bindings support object-form createBatch() (2026-10-01)
- slug: local-workflows-bindings-support-object-form-createbatch-9338eb8fa030
- score: 0.94

How to use it:

When running a local Workflows binding, call object-form `createBatch()` with a count or per-instance options. Read the returned `created` handles and indexed `errors`; the array form remains supported.

Examples:

```
const result = await env.<BINDING>.createBatch({ count: 2, params: <payload> });
const handles = result.created;
const errors = result.errors;
```

```
const result = await env.<BINDING>.createBatch({ instances: [{ id: "<id>", params: <payload> }] });
const handles = result.created;
const errors = result.errors;
```

- why_it_matters: In local development, create Workflow instances in a batch using a count or per-instance options.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.146.0>, <https://github.com/cloudflare/workers-sdk/commit/464a582442ad6872edf1d52107b1a7b68b5e606f>, <https://developers.cloudflare.com/workflows/build/local-development/>
- gotchas: "Version: 4.146.0"; "count: Number of instances to create in count form; the documented source example uses `count: 2`."; "params: Payload passed to instances in the count-form example."; "instances: List of per-instance options; each may include `id` and `params`."; "created: Returned instance handles."; "errors: Returned per-instance errors include the input `index`; examples also show `id`, `code`, and `message`."; "Prerequisite: Local Workflows development requires Wrangler v3.89.0 or later and Node.js 18.0.0 or later; Wrangler 4.146.0 satisfies the documented Wrangler minimum."; "This support applies to local Workflows bindings."; "Docs conflict: The Workers API docs list the array-form `createBatch(batch: WorkflowInstanceCreateOptions[])` signature and array result; the Wrangler 4.146.0 release note and source commit document the new local object form. The docs do not specify object-form field requiredness."

### wrangler.json supports native Analytics SQL bindings in local development (2026-09-30)
- slug: wrangler-json-supports-native-analytics-sql-bindings-in-local-development-2f829d47c083
- score: 0.92

How to use it:

When a Worker uses Analytics SQL during local development, declare `analytics.binding` in `wrangler.json` and run `wrangler dev`; call it through `env.<BINDING>.query()` without `unsafe.bindings`.

Examples:

```
{
  "analytics": {
    "binding": "ANALYTICS"
  }
}
```

```
export default {
  async fetch(_request, env) {
    const result = await env.ANALYTICS.query({
      query: "SELECT COUNT(*) AS requests FROM events.httpRequests",
    });
    return Response.json(result);
  },
};
```

```
wrangler dev
```

- why_it_matters: During local development of a Worker that uses an Analytics SQL binding, configure the binding and call it with `wrangler dev`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0>, <https://developers.cloudflare.com/workers/runtime-apis/bindings/analytics-sql/>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.145.0"; "analytics.binding (required): Name used to access the Analytics SQL binding on the Worker `env` object."; "query (required): One SQL `SELECT` statement; use `$1` or `$name` for parameter placeholders."; "Prerequisite: Wrangler 4.145.0 or later."; "Prerequisite: Analytics SQL has no local implementation; the binding always connects to the remote service during local development."

### wrangler K2 producer bindings write to existing streams (2026-09-30)
- slug: wrangler-k2-producer-bindings-write-to-existing-streams-fe443330e667
- score: 0.92

How to use it:

When producing events from a Worker to an existing K2 stream, add its ID and a binding name under `k2` in Wrangler config, then call `env.<BINDING>.send(records)` and check `result.success`.

Examples:

```
{
  "k2": [
    {
      "binding": "<BINDING>",
      "stream": "<32-character-lowercase-hex-stream-id>"
    }
  ]
}
```

```
const result = await env.<BINDING>.send([
  {
    content: new TextEncoder().encode("<EVENT_PAYLOAD>"),
    headers: { event: "<EVENT_NAME>" }
  }
]);
if (!result.success) {
  console.error(`Produce failed: ${result.error.message}`);
}
```

```
npx wrangler types
```

- why_it_matters: Configure a Worker to produce events to an existing K2 stream during development or deployment.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0>, <https://developers.cloudflare.com/k2/features/produce/>, <https://developers.cloudflare.com/k2/>, <https://developers.cloudflare.com/k2/configuration/>
- gotchas: "Version: 4.145.0"; "Availability: Beta"; "k2[].binding (required): Worker variable name for the binding, such as `env.ORDERS`."; "k2[].stream (required): 32 lowercase hexadecimal stream ID; stream must be in the same account as the Worker."; "send(records)[].content (required): Record payload as `ArrayBuffer` or `Uint8Array`; all records in a batch must use the same type."; "send(records)[].headers: Metadata map with string keys and string values."; "Prerequisite: K2 is available on the Workers Paid plan; it is in public beta."; "Prerequisite: The K2 Workers binding input must be enabled on the stream; it is enabled by default when omitted at stream creation."; "Prerequisite: Run `npx wrangler types` after adding the binding to generate the Env type."; "K2 requires an enabled account."; "Deployment credentials need Worker deployment and K2 configuration-read access."; "Existing OAuth users should run `wrangler login` again to grant the new permissions."; "Development always uses a real K2 stream and may incur usage charges; no local simulator is provided."; "Batches use either all `ArrayBuffer` or all `Uint8Array` content."; "Check the returned `success` value, handle rejected RPC promises, and retry only when the returned error explicitly allows it."; "`remote: false` is rejected."; "Consumption is not part of this Worker binding."

### wrangler containers ssh supports forced pseudo-terminal allocation (2026-09-29)
- slug: wrangler-containers-ssh-supports-forced-pseudo-terminal-allocation-fd8c162e686f
- score: 0.97

How to use it:

When running an interactive shell as a remote command, pass `--tty` before the command to force pseudo-terminal allocation.

Examples:

```
wrangler containers ssh <INSTANCE_ID> --tty -- bash
```

- why_it_matters: When opening an interactive shell in a Container with a remote command, allocate a pseudo-terminal so the shell has a prompt and line editing.
- before: For a remote command such as `bash`, SSH did not allocate a pseudo-terminal by default; the release note says to pass `--tty` to force one.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.144.0>, <https://developers.cloudflare.com/workers/wrangler/commands/containers/>, <https://developers.cloudflare.com/containers/ssh/>
- gotchas: "Version: 4.144.0"; "INSTANCE_ID (required): ID of the running Container instance to SSH into."; "--tty (-t): Force pseudo-terminal allocation."; "-- <remote command>: Run the specified command instead of the default shell."; "Prerequisite: The Container must be running, SSH must be configured, and a matching public key must be in `authorized_keys`."; "Docs conflict: The current Wrangler command reference documents `containers ssh` and remote commands but does not list `--tty` or `-t`; the release note for v4.144.0 documents the flag. No differing behavior is documented."

### wrangler local development supports Workflows in ctx.exports (2026-09-27)
- slug: wrangler-local-development-supports-workflows-in-ctx-exports-f77762c0df2d
- score: 0.97

How to use it:

When a Worker declares a Workflow in `exports`, create it locally with `ctx.exports.<ClassName>.create({ params })`; use `wrangler workflows` with `--local` to trigger or inspect its instances. In Vitest, introspect through a test-only Workflow binding, which also captures instances created via `ctx.exports`.

Examples:

```
const instance = await ctx.exports.MyWorkflow.create({ params: { name: "World" } });
```

```
npx wrangler workflows trigger <WORKFLOW_NAME> '{"name":"World"}' --local
npx wrangler workflows instances describe <WORKFLOW_NAME> <INSTANCE_ID> --local
```

```
cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" }, miniflare: { workflows: { MY_WORKFLOW: { name: "my-workflow", className: "MyWorkflow" } } } })

await using introspector = await introspectWorkflow(env.MY_WORKFLOW);
await exports.default.fetch("https://example.com/");
const instances = await introspector.get();
```

- why_it_matters: Create and introspect a Workflow declared in a Worker’s `exports` while developing or testing the Worker locally.
- before: Before this change, a Worker could define a Workflow through a `workflows` binding; calling an exported Workflow through `ctx.exports` was not available.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.142.0>, <https://developers.cloudflare.com/changelog/post/2026-09-27-workflow-ctx-exports/>, <https://developers.cloudflare.com/workflows/build/local-development/>, <https://developers.cloudflare.com/workers/testing/vitest-integration/test-apis/>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>, <https://developers.cloudflare.com/changelog/product/workflows/>
- gotchas: "Version: 4.142.0"; "ctx.exports.MyWorkflow (required): Use the Workflow class name as the key to reach the exported Workflow API."; "params: Object passed as the Workflow instance input; example uses `{ name: \"World\" }`."; "<WORKFLOW_NAME> (required): Workflow name used by Wrangler commands."; "[PARAMS]: JSON string passed as the Workflow instance parameters."; "--local: Target the Workflow in a local `wrangler dev` session."; "--port: Select the local dev session port; defaults to `8787`."; "MY_WORKFLOW test binding (required): Vitest introspection requires a Workflow binding; configure `name` and `className` under `miniflare.workflows`."; "Prerequisite: For local exported Workflows, use Wrangler 4.142.0 or later, `@cloudflare/vite-plugin` 1.61.0 or later, or `@cloudflare/vitest-plugin` 1.3.0 or later, as appropriate."; "Prerequisite: Run a `wrangler dev` session before using `wrangler workflows ... --local`."; "Prerequisite: Vitest helpers from `cloudflare:test` and `cloudflare:workers` must be imported from test files running in the Workers runtime."; "`ctx.exports` and `workflows` bindings with the same Workflow `name` share their instances, including instances created before the Workflow was declared in `exports`."; "Two Workers can't export the same Workflow name."; "A binding to an exported Workflow must refer to the Worker and class that export it."; "`getPlatformProxy()` ignores Workflows declared in `exports`, since it doesn't run the Worker's code."; "In the Vitest plugin, `introspectWorkflow()` and `introspectWorkflowInstance()` still need a Workflow binding."; "A `workflows` binding whose `script_name` is the Worker's own name resolves to the Worker itself again."

### wrangler deploy, versions deploy, and rollback support Durable Objects code update strategies (2026-09-25)
- slug: wrangler-deploy-versions-deploy-and-rollback-support-durable-objects-code-update-015fcabdb0be
- score: 0.97

How to use it:

When deploying or rolling back a Worker with Durable Objects, set the code update mode to control when their code updates. Use `--durable-objects-code-update-mode immediate` for immediate updates, or `deferred <delay>` to set the maximum delay; the Wrangler config field could not be verified in the official docs found.

Examples:

```
npx wrangler versions deploy <VERSION-SPECS> --durable-objects-code-update-mode immediate
```

```
wrangler rollback [<VERSION_ID>] --durable-objects-code-update-mode deferred 30s
```

```
wrangler deploy --durable-objects-code-update-mode deferred 30s
```

- why_it_matters: When deploying or rolling back a Worker with Durable Objects, configure when its code updates.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.141.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.141.0"; "--durable-objects-code-update-mode: Selects Durable Object code update behavior; docs say `immediate` or `deferred` followed by a maximum delay, such as `deferred 30s`."; "Prerequisite: Wrangler versions commands require Wrangler 3.40.0 or later; Wrangler 4.141.0 exceeds that minimum."; "When unset, the strategy defaults to deferred with a 5-minute maximum delay."; "Delays cannot exceed 24 hours and must use millisecond precision."

### wrangler declares Workflow exports in `exports` (2026-09-24)
- slug: wrangler-declares-workflow-exports-in-exports-ac32289c2a00
- score: 0.94

How to use it:

If a Worker defines a `WorkflowEntrypoint` class, declare it in `exports` under the class name with `type: "workflow"` and a Workflow `name`; add supported settings as needed. Deploy the Worker with Wrangler to upload and provision the Workflow.

Examples:

```
{
  "exports": {
    "MyWorkflow": {
      "type": "workflow",
      "name": "my-workflow",
      "limits": { "steps": 100 },
      "schedules": "0 * * * *"
    }
  }
}
```

```
npx wrangler deploy
```

- why_it_matters: Declare and deploy a Workflow defined by a Worker using the exports configuration map.
- before: Previously, a Worker could only define a Workflow through a `workflows` binding, even when it never called the Workflow itself.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.139.0>, <https://developers.cloudflare.com/workflows/build/workers-api/>, <https://developers.cloudflare.com/workers/wrangler/commands/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/cf/projects/cloudflare-config/>, <https://developers.cloudflare.com/changelog/post/2026-09-24-workflow-exports/>
- gotchas: "Version: 4.139.0"; "exports.MyWorkflow (required): Map key is the exported class name; it must name a class extending `WorkflowEntrypoint`."; "type (required): Set to `\"workflow\"`."; "name (required): Workflow name; unique within the account."; "limits.steps: Maximum steps a Workflow instance may run."; "concurrency.limit: Maximum Workflow instances that can run concurrently; documented by the `@cloudflare/config` helper."; "schedules: Cron schedule or schedules that start Workflow instances automatically."; "default_retention.success_retention: Retention duration for successful or terminated instances; accepts a duration string or milliseconds."; "default_retention.error_retention: Retention duration for errored instances; accepts a duration string or milliseconds."; "Prerequisite: Workflow exports require Wrangler 4.139.0 or above."; "Prerequisite: For `cloudflare.config.ts`, the documented helper is `exports.workflow({ name, limits, concurrency, schedules, defaultRetention })`; the class name is the map key."; "A Workflow may be declared both as a binding and as an export if both declarations use the same class and do not set the same setting to different values."; "A binding to another Worker's Workflow cannot share a name with an export."; "Local development does not yet act on these entries."; "Docs conflict: The Wrangler configuration and changelog pages list `limits`, `schedules`, and `default_retention` for Workflow exports, but do not list `concurrency`; the current `@cloudflare/config` helper docs do include `concurrency.limit`. The release note says exports accept the same settings as bindings, including concurrency. Verify the installed Wrangler/config schema before using concurrency in Wrangler JSON/TOML."

### Wrangler configures real-time Issues observability (2026-09-17)
- slug: wrangler-configures-real-time-issues-observability-d9a9ecd3383b
- score: 0.94

How to use it:

When enabling or updating real-time Issues observability for a Worker, set `observability.issues.enabled` to `true` in Wrangler configuration and deploy the Worker.

Examples:

```
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "observability": {
    "issues": {
      "enabled": true
    }
  }
}
```

```
npx wrangler deploy
```

- why_it_matters: Enable or update real-time Issues observability for a Worker in its Wrangler configuration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.134.0>, <https://developers.cloudflare.com/workers/observability/issues/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.134.0"; "Availability: experimental configuration format supports the equivalent option"; "observability.issues.enabled: Boolean; set to `true` to detect and group production failures, or `false` and deploy to stop detecting new failures."; "Prerequisite: Requires Wrangler 4.134.0 or later."; "Prerequisite: A Worker configuration must include `name`, `main`, and `compatibility_date` to deploy; `main` is optional for assets-only Workers."

### wrangler previews block accepts placement configuration (2026-09-16)
- slug: wrangler-previews-block-accepts-placement-configuration-c556450408ca
- score: 0.92

How to use it:

When a Worker needs a Preview placement different from production, set `placement` inside the Wrangler `previews` block; this overrides top-level placement for Previews.

Examples:

```
{"placement":{"region":"<provider>:<region>"},"previews":{"placement":{"mode":"smart"}}}
```

- why_it_matters: Configure a Worker’s Preview placement independently from its production placement.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.133.0>, <https://developers.cloudflare.com/workers/previews/configuration/>, <https://developers.cloudflare.com/workers/configuration/placement/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.133.0"; "previews.placement: Preview placement configuration; overrides top-level placement for Previews."; "placement.mode: Set to `\"smart\"` for automatic placement near back-end services."; "placement.region: Cloud region in `{provider}:{region}` format, such as `aws:us-east-1`."; "placement.host: Hostname and port for a single-homed layer 4 service."; "placement.hostname: Hostname for a single-homed layer 7 service."; "placement choice: `mode`, `region`, `host`, and `hostname` are mutually exclusive placement options."; "Prerequisite: Use a Wrangler configuration file. Deployable Workers require `name`, `main`, and `compatibility_date` (with `main` optional for assets-only Workers)."

### wrangler preview supports AI Search bindings (2026-09-15)
- slug: wrangler-preview-supports-ai-search-bindings-39736d03b852
- score: 0.92

How to use it:

When a Worker needs AI Search bindings in a Preview deployment, declare `ai_search` and/or `ai_search_namespaces` explicitly under `previews`, then run `npx wrangler preview`.

Examples:

```
{
  "previews": {
    "ai_search": [{ "binding": "<BINDING_NAME>", "instance_name": "<INSTANCE_NAME>" }],
    "ai_search_namespaces": [{ "binding": "<BINDING_NAME>", "namespace": "<NAMESPACE_NAME>" }]
  }
}
```

```
npx wrangler preview
```

- why_it_matters: Add AI Search bindings needed by a Worker to its Preview deployment configuration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.132.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/workers/previews/get-started/>, <https://developers.cloudflare.com/workers/previews/configuration/>
- gotchas: "Version: 4.132.0"; "ai_search[].binding (required): Binding name used to refer to the AI Search instance."; "ai_search[].instance_name (required): AI Search instance name; must exist in the default namespace at deploy time."; "ai_search_namespaces[].binding (required): Binding name used to refer to the AI Search namespace."; "ai_search_namespaces[].namespace (required): AI Search namespace name; a missing namespace is created on deploy according to the current configuration docs."; "previews (required): Preview-specific configuration block; Preview settings do not inherit production settings."; "Prerequisite: Worker Previews requires Wrangler 4.135.0 or later in the current Get started guide."; "These bindings are non-inheritable and must be declared explicitly under `previews`."; "Bindings attach to existing AI Search resources; Preview does not provision new isolated instances or namespaces."; "Docs conflict: The current Wrangler configuration docs say a missing AI Search namespace is created on deploy, while the v4.132.0 release note says Preview bindings attach to existing resources and Preview does not provision isolated namespaces. Apply the release note's existing-resource limitation to Preview behavior."

### wrangler top-level containers supports Durable Object-managed applications (2026-09-10)
- slug: wrangler-top-level-containers-supports-durable-object-managed-applications-1003782ed581
- score: 0.92

How to use it:

When a Worker uses Durable Object-managed Containers, configure `scheduling_policy: "durable_object"`, its class, and named image sources; deploy with Wrangler and select prepared images through `ctx.container.images`. Retry the same deploy command if Cloudflare reports partial completion after application creation fails.

Examples:

```
{"containers":[{"class_name":"<Class>","scheduling_policy":"durable_object","images":{"<image-name>":{"dockerfile":"<path/to/Dockerfile>"}}}]}
```

```
npx wrangler deploy --containers-rollout=none
```

```
npx wrangler versions deploy <VERSION-ID>@100%
```

- why_it_matters: Configure a Worker to use managed Containers backed by a Durable Object class and deploy its images.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.131.0>, <https://developers.cloudflare.com/containers/configuration/scheduling-policy/>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/containers/guides/image-management/>, <https://developers.cloudflare.com/workers/authorization/workers/>
- gotchas: "Version: 4.131.0"; "containers[].scheduling_policy (required): Set to `\"durable_object\"` for Durable Object-managed scheduling."; "containers[].class_name (required): Names the corresponding Durable Object class for this release-note configuration."; "containers[].name: Optional Container application name in the release note."; "containers[].images: Map of named images accessible through `ctx.container.images`; each image must specify exactly one of `dockerfile` or `image`."; "containers[].images.<name>.dockerfile: Local Dockerfile path; Wrangler builds and pushes the image. Mutually exclusive with `image` for each named image."; "containers[].images.<name>.image: Digest-pinned image reference in the Cloudflare Registry. Mutually exclusive with `dockerfile` for each named image."; "containers[].images.<name>.build_context: Build context relative to the Wrangler config; only valid with `dockerfile`."; "containers[].images.<name>.build_vars: Build-time variables; only valid with `dockerfile`."; "--containers-rollout: For `wrangler deploy`, `none` skips Container image and instance updates."; "EXPERIMENTAL_CLOUDFLARE_CONTAINER_IMAGES: Temporary reserved Wrangler binding for Container image references; user configuration cannot declare it."; "ctx.container.images: Runtime object exposing configured named image references to Durable Object code."; "Prerequisite: The Durable Object linked to the Container must use SQLite storage."; "Prerequisite: A local Dockerfile build requires Docker or a Docker-compatible CLI to be running."; "Prerequisite: Wrangler deploy of an existing Worker requires Editor access; creating a new Worker requires product-level Admin."; "Prerequisite: The `durable_object` scheduling policy is in public beta."; "Durable Object-managed entries also accept an optional `name` and optional named `images` map; scheduler-only fields are rejected."; "Wrangler builds or resolves each image and waits while Cloudflare prepares it for the Containers runtime."; "Local development support for these entries is deferred to a follow-up."; "With `--containers-rollout=none`, existing Workers retain deployed Container metadata and image binding even when local `containers` is omitted or empty; local scheduler edits are ignored, and upload stops if deployed versions cannot be recovered."; "Existing Workers for Platforms dispatch scripts reject `--containers-rollout=none` before upload because their API does not expose enough metadata to preserve Container associations safely."; "Without `--containers-rollout=none`, removing managed Containers, including by omitting `containers`, clears the experimental image binding even with `keep_vars`."; "`versions deploy` validates selected versions before changing traffic and creates Durable Object-managed applications only after deployment succeeds."; "Both `deploy` and `versions deploy` report partial completion if application creation fails afterward, with instructions to retry the same command."; "`EXPERIMENTAL_CLOUDFLARE_CONTAINER_IMAGES` is a temporary, reserved Wrangler binding; user configuration cannot declare it, and existing versions that already use it are treated as Container configuration."; "The binding's class keys identify managed applications during `versions deploy`, including classes with empty image maps."; "Existing scheduler-backed entries and Durable Object migrations continue to work unchanged."; "Docs conflict: The current Wrangler configuration docs additionally allow omitting `class_name` when linking a Container by `name` from `exports.<Class>.container`; the Wrangler 4.131.0 release note describes `class_name` entries and does not document that alternative. Current docs may describe later behavior."

### wrangler Pipelines sink creation supports gzip compression for JSON (2026-09-03)
- slug: wrangler-pipelines-sink-creation-supports-gzip-compression-for-json-96b62c03faac
- score: 0.94

How to use it:

For a Wrangler 4.129.0 Pipelines sink with JSON output, select `gzip` or `uncompressed` in the CLI or interactive setup flow. The current CLI reference does not document a JSON compression flag; the API documents JSON compression in the sink `format` object.

Examples:

```
curl https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/pipelines/v1/sinks -H 'Content-Type: application/json' -H "Authorization: Bearer <CLOUDFLARE_API_TOKEN>" -d '{"name":"<SINK_NAME>","type":"r2","format":{"type":"json","compression":"gzip"}}'
```

- why_it_matters: Create a JSON sink for a Pipelines workflow with gzip compression.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.129.0>, <https://developers.cloudflare.com/api/resources/pipelines/subresources/sinks/methods/create/>, <https://fec4cfc0.previews.developers.cloudflare.com/pipelines/reference/wrangler-commands/>
- gotchas: "Version: 4.129.0"; "Availability: Pipelines is in open beta."; "format.type (required): Use `json` for JSON output; the documented format is a JSON or Parquet object."; "format.compression: JSON accepts `uncompressed` or `gzip`."; "[SINK] (required): Name of the sink to create."; "--type (required): Type of sink to create."; "--bucket (required): R2 bucket name."; "Prerequisite: The Create Sink API requires a token with Pipelines Write permission."; "JSON sinks accept `uncompressed` or `gzip`."; "Parquet retains its existing compression options and `zstd` default."; "Docs conflict: Current Wrangler command docs describe --compression as Parquet-only and default it to zstd; this differs from release-note behavior for JSON in Wrangler 4.129.0, so that flag behavior is not used here."

### wrangler workflows commands accept --json (2026-09-03)
- slug: wrangler-workflows-commands-accept-json-75934421d1e7
- score: 0.97

How to use it:

When a script consuming `wrangler workflows` output needs raw API data, append `--json` to the command; formatted output is the default. For example, list a workflow’s instances with `--json` to emit the raw API response.

Examples:

```
npx wrangler workflows instances list <workflow-name> --json
```

- why_it_matters: When scripting a workflow command and consuming its output, request the raw API payload with `--json`.
- before: Use the command without `--json` to receive the human-readable rendering by default.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.129.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>
- gotchas: "Version: 4.129.0"; "<workflow-name> (required): Name of the workflow."; "--json: Boolean flag (default false); outputs the raw API response as JSON."; "Prerequisite: Wrangler 3.83.0 or greater is required for `wrangler workflows`."; "JSON output carries raw values, including ISO timestamps and plain status strings, and omits presentation-only derived fields."

### Wrangler observability can redact query strings (2026-09-01)
- slug: wrangler-observability-can-redact-query-strings-7c5c42933899
- score: 0.96

How to use it:

If the Worker should omit request URL query strings from observability logs and traces, set `observability.redact_query_string` to `true` in `wrangler.json`, or `observability.redactQueryString` to `true` in the experimental `cloudflare.config.ts` format.

Examples:

```
{"observability":{"redact_query_string":true}}
```

```
export default defineConfig({
  observability: { redactQueryString: true },
});
```

- why_it_matters: Configure a Worker project to omit request URL query strings from observability logs and traces.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.128.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/cf/projects/cloudflare-config/>
- gotchas: "Version: 4.128.0"; "Availability: The `cloudflare.config.ts` format is experimental."; "observability.redact_query_string: Boolean; whether query strings are removed from request URLs in logs and traces. Default: false."; "observability.redactQueryString: Boolean; whether query strings are removed from request URLs in logs and traces. Default: false."; "Prerequisite: The `cloudflare.config.ts` format is experimental."

### wrangler workflows instances list adds date filters (2026-09-01)
- slug: wrangler-workflows-instances-list-adds-date-filters-17565dcfd5de
- score: 0.96

How to use it:

To list workflow instances created in a date or timestamp window, run `npx wrangler workflows instances list <NAME>` with either or both date filters. The bounds include their endpoints and may be combined with `--status`.

Examples:

```
npx wrangler workflows instances list <NAME> --date-start 2026-01-01 --date-end 2026-01-31
```

- why_it_matters: Narrow a workflow instance listing to instances created within a specified date or timestamp window.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.128.0>, <https://developers.cloudflare.com/workflows/reference/wrangler-commands/>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>
- gotchas: "Version: 4.128.0"; "<NAME> (required): Workflow name."; "--date-start: Include instances created at or after this ISO 8601 date or timestamp."; "--date-end: Include instances created at or before this ISO 8601 date. A date-only value covers the whole UTC day."; "--status: Filter by status: queued, running, paused, errored, terminated, or complete. Can be combined with date filters."; "Prerequisite: Workflows Wrangler commands require Wrangler 3.83.0 or later."; "Either date flag can be used independently."; "Date or timestamp values must be ISO 8601."; "Bounds are inclusive and compose with the existing `--status` filter."

### wrangler configures a per-workflow concurrency limit (2026-08-27)
- slug: wrangler-configures-a-per-workflow-concurrency-limit-5a4224334e5c
- score: 0.96

How to use it:

When deploying a Workflow with Wrangler, set `concurrency.limit` to a positive integer in its `workflows[]` entry. The limit is persisted on deploy and enforced server-side; it is ignored in local development.

Examples:

```
{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow",
      "concurrency": { "limit": 10 }
    }
  ]
}
```

- why_it_matters: Set a maximum number of Workflow instances that can run concurrently for a workflow deployed with Wrangler.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.127.0>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.127.0>
- gotchas: "Version: 4.127.0"; "workflows[].concurrency.limit: Positive integer maximum number of Workflow instances that can run concurrently. The `concurrency` object is optional; when set, specify `limit`."; "The limit is validated as a positive integer."; "Concurrency is ignored in local development."; "Docs conflict: The current Wrangler configuration page documents Workflow binding fields but does not list `concurrency`; it does not state different behavior. https://developers.cloudflare.com/workers/wrangler/configuration/"

### Wrangler Hyperdrive PlanetScale signature provisions billed databases (2026-08-25)
- slug: wrangler-hyperdrive-planetscale-signature-provisions-billed-databases-efa8d5017e24
- score: 0.96

How to use it:

When creating a PlanetScale Postgres database billed to Cloudflare, pipe Wrangler’s experimental signed authorization into `pscale database create` with the documented flags. Use `pscale` v0.313.0 or newer, as stated in the release note.

Examples:

```
npx wrangler hyperdrive planetscale signature | \
  pscale database create <name> \
    --org <org> \
    --engine postgresql \
    --cloudflare-billing @- \
    --format json
```

- why_it_matters: Create a PlanetScale Postgres database billed to a Cloudflare account from a coding workflow.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.126.0>, <https://planetscale.com/docs/cli/database>, <https://github.com/planetscale/cli/blob/main/AGENTS.md>, <https://developers.cloudflare.com/workers/wrangler/commands/hyperdrive/>
- gotchas: "Version: 4.126.0"; "Availability: Experimental; interface may change."; "<name> (required): Name of the database to create."; "--org <org> (required): Organization for the database. The PlanetScale database docs say create requires `--org` or `PLANETSCALE_ORG`."; "--engine postgresql (required): Selects Postgres; the CLI defaults to `mysql` (Vitess)."; "--cloudflare-billing @- (required): Passes Cloudflare billing proof to `database create`; `@-` reads it from stdin."; "--format json: Formats CLI output as JSON; the release note recommends it when output is consumed by an agent."; "Prerequisite: Use `pscale` v0.313.0 or newer."; "Prerequisite: Wrangler’s signature command is experimental."; "Requires `pscale` v0.313.0 or newer."; "`pscale database create` defaults to Vitess; pass `--engine postgresql` for a Postgres database."; "Wrangler authorizes the Cloudflare billing side only; PlanetScale credentials stay between the user and `pscale`."; "The signed token authorizes creating a database billed to the Cloudflare account; treat it as a credential and do not share it."; "Piping the token is recommended over passing it as a command line argument."

### Wrangler Workflow bindings configure default instance retention (2026-08-25)
- slug: wrangler-workflow-bindings-configure-default-instance-retention-e83cc7f59a9e
- score: 0.94

How to use it:

When a Workflow’s instances need a per-Workflow retention default, add optional `default_retention` to its Wrangler `workflows` binding. Set `success_retention` and/or `error_retention` to a duration string or whole number of milliseconds; instances with their own retention keep that setting.

Examples:

```
{
  "workflows": [
    {
      "binding": "<BINDING_NAME>",
      "name": "<WORKFLOW_NAME>",
      "class_name": "<CLASS_NAME>",
      "default_retention": {
        "success_retention": "3 days",
        "error_retention": "7 days"
      }
    }
  ]
}
```

- why_it_matters: Set default retention periods for instances of a Workflow in Wrangler configuration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.126.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.126.0"; "workflows[].binding (required): Binding name used to refer to the Workflow; must be a valid JavaScript variable name."; "workflows[].name (required): Name of the Workflow."; "workflows[].class_name (required): Exported Workflow class name; must match the class exported from the Worker."; "workflows[].default_retention: Default retention for instances that do not set their own retention; capped at the account retention limit."; "workflows[].default_retention.success_retention: Retention for successfully completed or terminated instances; accepts a duration string or whole number of milliseconds."; "workflows[].default_retention.error_retention: Retention for instances that end in an errored state; accepts a duration string or whole number of milliseconds."; "Each retention side is optional."; "Durations are interpreted by the Workflows API, which caps them at the account's retention limit."; "The per-Workflow default applies to instances that do not specify their own retention."

### wrangler dev supports raw socket connect triggers (2026-08-20)
- slug: wrangler-dev-supports-raw-socket-connect-triggers-def490770749
- score: 0.98

How to use it:

When configuring raw TCP connections for local development, enable the `experimental` compatibility flag and add a `connect` trigger; `wrangler dev` forwards connections to the Worker’s `connect(socket, env, ctx)` handler. [Release note](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.125.0)

Examples:

```
{
  "compatibility_flags": ["experimental"],
  "connect": [{ "protocol": "tcp", "port": 5432 }]
}
```

```
import { defineWorker, triggers } from "@cloudflare/config";

export default defineWorker({
  triggers: [
    triggers.connect({ protocol: "tcp", port: 5432, address: "127.0.0.1" }),
  ],
});
```

```
npx wrangler dev
```

- why_it_matters: Configure a Worker to handle raw TCP connections during local development.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.125.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.125.0"; "compatibility_flags: \"experimental\" (required): Required compatibility flag for the connect trigger."; "connect[].protocol (required): Protocol to listen for; only `\"tcp\"` is supported."; "connect[].port (required): Port for the listening socket. The example uses `5432`."; "connect[].address: Listening address; defaults to `127.0.0.1`."; "triggers.connect(...): `@cloudflare/config` declaration that lowers to the `connect` field."; "Requires the `experimental` compatibility flag."; "Only `\"tcp\"` is supported at the moment."; "Each entry listens on `127.0.0.1` unless an `address` is given."; "Connections bypass the local dev HTTP entry point."

### wrangler preview configures containers for preview deployments (2026-08-20)
- slug: wrangler-preview-configures-containers-for-preview-deployments-f4463ec69ade
- score: 0.98

How to use it:

When a Worker preview needs a Durable Object backed by a container, declare it under `previews.containers` with its `class_name`, then run `npx wrangler preview` to build and deploy the image. Use `npx wrangler preview --json` from a non-interactive shell for machine-readable output; the release note recommends a prebuilt image over a Dockerfile.

Examples:

```
"previews": { "containers": [{ "class_name": "<DurableObjectClass>", "image": "<image-or-Dockerfile-path>", "max_instances": 10, "instance_type": "basic" }] }
```

```
npx wrangler preview
```

```
npx wrangler preview --json
```

- why_it_matters: Configure a Worker preview deployment to run a Durable Object backed by a container.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.125.0>, <https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/docs/workers/previews/resources/index.mdx>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.125.0"; "previews.containers[].class_name (required): Durable Object class backed by the preview container. A class with no matching Durable Object is rejected; a class can back at most one container app, per release note."; "previews.containers[].image: Container image or Dockerfile path; docs example uses `./Dockerfile`. Release note recommends prebuilt `image` for JSON output."; "previews.containers[].max_instances: Maximum container instances; docs example uses `10`."; "previews.containers[].instance_type: Container instance type; docs example uses `basic`."; "--json: Return machine-readable output; defaults to false."; "Prerequisite: Container preview configuration is not inherited from top-level `containers`; declare it under `previews.containers`."; "Prerequisite: A Durable Object class and its SQLite migration are shown in the docs configuration example. A preview Durable Object binding is needed only when Worker code reads the namespace from `env`; it is unnecessary for access through `ctx.exports`."; "Prerequisite: The preview command's `SCRIPT` argument is needed only if the Wrangler config has no `main` key."; "Container configuration does not inherit; declare containers explicitly in the `previews` block."; "Each entry must set `class_name`."; "An entry cannot set its own `name`."; "A Durable Object class can be backed by at most one container application; validation rejects entries sharing a `class_name`."; "Entries whose `class_name` matches no Durable Object class are rejected before preview deployment."; "Wrangler skips container applications for Durable Object classes another Worker implements through `script_name`."; "A binding is not required when a Durable Object declared through `migrations` or `exports` is reached only over `ctx.exports`."; "Preview deletion tears down container applications server-side; `wrangler preview delete` does not remove them."; "Docker build output and the progress spinner write directly to stdout and bypass `--json` suppression; the spinner is skipped in non-interactive shells."; "`--json` suppresses Wrangler's own stdout output; warnings and errors still go to stderr."; "Docs conflict: Current Cloudflare preview docs say deleting a preview can leave its generated container app visible; they recommend checking `wrangler containers list` and deleting leftovers. This differs from the release note statement that preview deletion tears down container applications server-side. The docs page does not state the Wrangler version for that behavior."

### wrangler workflows instances delete removes one or more instances (2026-08-20)
- slug: wrangler-workflows-instances-delete-removes-one-or-more-instances-a0564b2f375e
- score: 0.97

How to use it:

When deleting Workflow instances, call `delete()` on a `WorkflowInstance` for one instance, `env.MY_WORKFLOW.deleteBatch(instanceIds)` for 1–100 IDs, or use Wrangler’s instances-delete command with positional IDs or a JSON array file; add `--local` for a local `wrangler dev` session.

Examples:

```
const instance = await env.MY_WORKFLOW.get("<instance-id>");
await instance.delete();
```

```
const result = await env.MY_WORKFLOW.deleteBatch(["<instance-id-1>", "<instance-id-2>"]);
```

```
npx wrangler workflows instances delete <WORKFLOW_NAME> <INSTANCE_ID>... [--local]
npx wrangler workflows instances delete <WORKFLOW_NAME> --filename ./instance-ids.json [--local]
```

- why_it_matters: Delete Workflow instances from a remote or local environment.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.125.0>, <https://developers.cloudflare.com/changelog/post/2026-09-17-instance-delete/>, <https://developers.cloudflare.com/workflows/build/workers-api/>, <https://developers.cloudflare.com/workflows/build/trigger-workflows/>, <https://developers.cloudflare.com/workflows/reference/wrangler-commands/>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>
- gotchas: "Version: 4.125.0"; "WorkflowInstance.delete() (required): Deletes the instance and its stored state; self-deletion stops execution at the awaited call."; "instanceIds (required): Array of instance IDs; `deleteBatch()` accepts 1–100 IDs. Duplicates count toward the limit. Results include deleted IDs and per-instance errors."; "<NAME> (required): Workflow name."; "[ID]: One or more instance IDs; `latest` selects the most recently created instance."; "--filename: Path to a JSON file containing an array of instance IDs. Can be combined with positional IDs; together they accept up to 100 IDs."; "--local: Targets a Workflow running in a local `wrangler dev` session."; "Prerequisite: Use Wrangler 4.125.0 or later for instance deletion; the release note documents the feature as available in that version."; "Prerequisite: For `--local`, a local `wrangler dev` session is the target; Wrangler docs state the flag requires Wrangler 4.79.0 or later."; "Batch runtime deletion accepts up to 100 instances."; "CLI deletion accepts a combined limit of 100 IDs."; "Self-deletion stops the current execution."

### wrangler links containers to Durable Object exports (2026-08-18)
- slug: wrangler-links-containers-to-durable-object-exports-807c862651ab
- score: 0.98

How to use it:

For a live `durable-object` export in `created` or `expecting-transfer` state, configure `storage: "sqlite"` and set `container` to an existing container’s `name`.

Examples:

```
{"name":"my-worker","main":"worker.js","compatibility_date":"2026-07-01","containers":[{"name":"my-container","image":"./Dockerfile","max_instances":1}],"exports":{"MyContainerDO":{"type":"durable-object","storage":"sqlite","container":"my-container"}}}
```

- why_it_matters: Configure a container-backed Durable Object in a Worker.
- before: The documented earlier linkage used `containers[].class_name` to name the Durable Object class.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.124.0>, <https://developers.cloudflare.com/containers/reference/wrangler-configuration/>, <https://developers.cloudflare.com/workers/wrangler/configuration/?ref=blog.cloudflare.com>
- gotchas: "Version: 4.124.0"; "exports.<Class>.type (required): Set to `\"durable-object\"` for a Durable Object class export."; "exports.<Class>.state: Lifecycle state; `created` is the default. `container` is allowed only for `created` or `expecting-transfer`."; "exports.<Class>.storage (required): For `created` or `expecting-transfer`, set to `\"sqlite\"` to use `container`."; "exports.<Class>.container: Name of an entry in the top-level `containers` array; requires SQLite storage."; "containers[].name (required): Container identifier; required when `class_name` is omitted so the export can reference it."; "containers[].image (required): Container image, such as a local Dockerfile path."; "containers[].max_instances: Maximum concurrent running container instances; defaults to 20."; "`container` is valid only on live `durable-object` exports in `created` or `expecting-transfer` state and requires `storage: \"sqlite\"."; "The existing `containers[].class_name` direction remains supported; if both directions specify a relationship, they must agree."; "A container reference must name an existing container; two Durable Object exports cannot claim the same container; each container must link to a Durable Object; container names must be unique."; "A container's `class_name` cannot name a Durable Object whose storage is `legacy-kv`."; "Two containers cannot attach to the same Durable Object."; "Docs conflict: The current Containers configuration docs say to configure exactly one linkage direction. The release note says either direction may be used, provided both agree; follow the release note for the stated change. Current docs are dated Aug 28, 2026, after the card’s Aug 18, 2026 release."

### wrangler preview base-config secret commands manage shared Preview secrets (2026-08-11)
- slug: wrangler-preview-base-config-secret-commands-manage-shared-preview-secrets-dd8b06cee6f9
- score: 0.97

How to use it:

When setting shared defaults for all of a Worker’s Previews, use `wrangler preview base-config secret` to put, delete, list, or bulk-manage secrets in the Preview base config. Use `list` to inspect configured secrets; the release note says values are masked.

Examples:

```
npx wrangler preview base-config secret put <KEY>
```

```
npx wrangler preview base-config secret list [--worker-name <WORKER>] [--json]
```

```
npx wrangler preview base-config secret bulk <FILE>
```

- why_it_matters: Set or inspect shared secret defaults for all Previews of a Worker.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.121.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.121.0"; "<KEY> (required): Secret name accessible in the Worker; required by put and delete."; "[FILE]: File of key-value pairs to upload, in JSON or .env format; bulk can omit it and read from stdin only where the command docs say so. JSON null deletion is stated in the release note."; "--worker-name <WORKER>: Worker to target; defaults to the name in the local Wrangler config."; "--skip-confirmation: Skip the confirmation prompt for delete."; "--json: Return list output as JSON; default is false."

### wrangler queues subscription create accepts email.sending (2026-08-11)
- slug: wrangler-queues-subscription-create-accepts-email-sending-f8bb442deedc
- score: 0.91

How to use it:

When subscribing a queue to email sending events, run `wrangler queues subscription create` with the queue, `--source email.sending`, `--events`, `--zone-id`, and `--domain`. Both zone ID and domain are required; use `wrangler queues subscription get` with the subscription ID to inspect the subscription.

Examples:

```
npx wrangler queues subscription create <QUEUE> --source email.sending --events <EVENTS> --zone-id <ZONE_ID> --domain <SENDING_DOMAIN>
```

```
npx wrangler queues subscription get <QUEUE> --id <SUBSCRIPTION_ID>
```

- why_it_matters: Create a queue subscription for email sending events from a zone or verified subdomain.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.121.0>, <https://developers.cloudflare.com/workers/wrangler/commands/queues/>
- gotchas: "Version: 4.121.0"; "<QUEUE> (required): Name of the queue to create the subscription for; for get, the queue name."; "--source (required): Event source type; use `email.sending` for this task."; "--events (required): Comma-separated list of event types to subscribe to."; "--zone-id (required): Zone ID; required for the `email.sending` source."; "--domain (required): Sending domain: zone apex or verified subdomain; required for the `email.sending` source."; "--id (required): Subscription ID to retrieve with `queues subscription get`."; "The `--domain` must be the zone apex or a verified subdomain."; "Both `--zone-id` and `--domain` are required for the `email.sending` source."

### wrangler containers instances supports exact ID or name search (2026-08-07)
- slug: wrangler-containers-instances-supports-exact-id-or-name-search-b12e4b0fea86
- score: 0.93

How to use it:

When inspecting an application’s instances, run `wrangler containers instances <application_id> --search <instance_id_or_name>` to find exact ID or name matches across every page.

Examples:

```
wrangler containers instances <application_id> --search <instance_id_or_name>
```

- why_it_matters: Find a container instance by its exact ID or name while inspecting an application’s instances.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.120.0>, <https://developers.cloudflare.com/containers/reference/wrangler-commands/>
- gotchas: "Version: 4.120.0"; "<application_id> (required): UUID of the application. Use `wrangler containers list` to find application IDs."; "--search <instance_id_or_name> (required): Search for exact instance ID or name matches; duplicate exact names return every match."; "If multiple instances have the same exact name, every matching instance is returned."

### wrangler ai-search create accepts --parse-type (2026-08-05)
- slug: wrangler-ai-search-create-accepts-parse-type-4913770dbac3
- score: 0.98

How to use it:

When creating a website crawler that should discover pages by following links, set `--type web-crawler` and `--parse-type discover`.

Examples:

```
npx wrangler ai-search create <NAME> --type web-crawler --source <WEBSITE_URL> --parse-type discover
```

- why_it_matters: Create a scripted web-crawler AI Search instance that discovers URLs by following links.
- before: The release note says the parse type could only be chosen through the interactive wizard, which was skipped when `--source` was supplied; scripted creation of a `discover` instance was therefore unavailable.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.119.0>, <https://developers.cloudflare.com/ai-search/wrangler-commands/>, <https://developers.cloudflare.com/ai-search/get-started/wrangler/>
- gotchas: "Version: 4.119.0"; "<NAME> (required): AI Search instance name; must be unique within its namespace."; "--type: Source type; use `web-crawler` for a website."; "--source: Data source identifier: R2 bucket name or website URL."; "--parse-type: Website URL discovery method; `discover` follows links recursively, while `sitemap` reads XML sitemaps. Documented as for `--type web-crawler` only; defaults to `sitemap`."; "Prerequisite: Install Wrangler before using the CLI."; "`--parse-type` is valid only with `--type web-crawler`; it is rejected with `--type builtin` or `--type r2`."; "The interactive wizard offers `Discover` alongside `Sitemap`."; "When the flag is omitted in non-interactive mode, the field is left unset and the API default (`sitemap`) applies."

### wrangler login supports device authorization (2026-08-05)
- slug: wrangler-login-supports-device-authorization-7b1c099124b4
- score: 0.98

How to use it:

When the browser cannot reach Wrangler’s local `localhost:8976` callback, run `wrangler login --device` and approve the request using the printed verification URL and user code.

Examples:

```
npx wrangler login --device
```

```
npx wrangler login --device --browser=false
```

- why_it_matters: Authenticate Wrangler from a container, remote SSH session, or Codespace where the browser cannot reach `localhost:8976`.
- before: The default login flow uses a local callback server at `localhost:8976`; the browser must be able to reach it. In containers, the docs describe mapping port 8976 and setting `--callback-host=0.0.0.0` as a workaround.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.119.0>, <https://developers.cloudflare.com/workers/wrangler/commands/general/>
- gotchas: "Version: 4.119.0"; "--device: Defaults to `false`; uses OAuth 2.0 Device Authorization Grant instead of the default `localhost` callback flow."; "--browser: Boolean; defaults to `true`. Automatically opens the OAuth link. Set `--browser=false` to suppress opening it."; "--callback-host: Defaults to `localhost`; sets the callback listener host. Cannot be combined with `--device`."; "--callback-port: Defaults to `8976`; sets the callback listener port. Cannot be combined with `--device`."; "Device authorization polls the token endpoint until approval, with a 5-minute hard cap."; "The verification URL is rejected unless it is an `https` URL on the same auth domain the device code was requested from; an invalid URL is neither printed nor opened."; "`--callback-host` and `--callback-port` cannot be combined with `--device`, because this flow does not start a local callback server."

### wrangler containers info adds --json output (2026-07-31)
- slug: wrangler-containers-info-adds-json-output-20e3a003df30
- score: 0.93

How to use it:

When a script needs machine-readable container details, run `wrangler containers info <CONTAINER_ID> --json` to get JSON output, consistent with `list` and `instances`.

Examples:

```
wrangler containers info <CONTAINER_ID> --json
```

- why_it_matters: Inspect container information in a script that consumes Wrangler container command output.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.118.0>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.118.0>, <https://developers.cloudflare.com/containers/reference/wrangler-commands/>
- gotchas: "Version: 4.118.0"; "CONTAINER_ID (required): ID of the Container to get information about."; "--json: Flag added in Wrangler 4.118.0 for JSON output from `containers info`."; "Docs conflict: The current Wrangler command reference documents `containers info` and its required ID but does not list `--json`; the 4.118.0 release note states the flag was added."

### createTestHarness dispatches email handlers (2026-07-30)
- slug: createtestharness-dispatches-email-handlers-3f7801dbf851
- score: 0.98

How to use it:

When testing a Worker's `email()` handler with Wrangler 4.116.0, call `server.getWorker().email({ from, to, raw })` and inspect the returned outcome, rejection reason, forwards, and replies.

Examples:

```
const result = await server.getWorker().email({ from: "sender@example.com", to: "inbox@example.com", raw: ["From: Sender <sender@example.com>", "To: Inbox <inbox@example.com>", "Message-ID: <test@example.com>", "Subject: Test email", "", "Hello from the test harness"].join("\r\n") });
expect(result).toMatchObject({ outcome: "ok", forwards: [{ recipient: "archive@example.com" }], replies: [{ sender: "inbox@example.com", raw: expect.stringContaining("Thanks for your email") }] });
```

- why_it_matters: Test a Worker's `email()` handler and inspect its outcome, rejection reason, forwarded messages, and replies.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.116.0>
- gotchas: "Version: 4.116.0"; "from (required): Sender email address for the dispatched message."; "to (required): Recipient email address for the dispatched message."; "raw (required): Raw email content, supplied as a string."; "Prerequisite: Use Wrangler 4.116.0 or later, where the release note adds email dispatch support to createTestHarness."

### wrangler local R2 development adds experimental S3-compatible credentials (2026-07-28)
- slug: wrangler-local-r2-development-adds-experimental-s3-compatible-credentials-f75831b2bc26
- score: 0.91

How to use it:

For local development against an R2 bucket through the S3-compatible API, set `local_dev.experimental_s3_credentials` under its `r2_buckets` entry, with both credential fields. The local endpoint uses AWS SigV4; its bucket ID is `bucket_name`, or `binding` if `bucket_name` is unset.

Examples:

```
{
  "r2_buckets": [
    {
      "binding": "<BINDING_NAME>",
      "bucket_name": "<BUCKET_NAME>",
      "local_dev": {
        "experimental_s3_credentials": {
          "accessKeyId": "<ACCESS_KEY_ID>",
          "secretAccessKey": "<SECRET_ACCESS_KEY>"
        }
      }
    }
  ]
}
```

- why_it_matters: For local development against an R2 bucket through an S3-compatible API, configure the bucket's local development credentials.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.115.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.115.0"; "Availability: Experimental."; "r2_buckets[].binding (required): Binding name for the R2 bucket; used as the bucket ID if `bucket_name` is unset."; "r2_buckets[].bucket_name (required): R2 bucket name; used as the local endpoint bucket ID when set."; "r2_buckets[].local_dev.experimental_s3_credentials: Enables local S3-compatible API credentials for this bucket."; "accessKeyId (required): Configured AWS SigV4 access key ID."; "secretAccessKey (required): Configured AWS SigV4 secret access key."; "Prerequisite: The local API is available during local development at `/cdn-cgi/local/r2/s3/<bucket-id>` and authenticates with AWS SigV4 credentials."; "The bucket is served through the S3-compatible API during local development."; "The API is authenticated with the configured AWS SigV4 credentials."; "`<bucket-id>` is the bucket's `bucket_name`, or the binding name if `bucket_name` is not set."; "Docs conflict: The official PR page’s earlier configuration example uses a different field name and layout (`experimental_local_s3_credentials`); it conflicts with the Wrangler 4.115.0 release note’s `local_dev.experimental_s3_credentials`, so that PR example is not used here: https://github.com/cloudflare/workers-sdk/pull/14280"

### Reconcile Email Routing addresses during Worker trigger deployment (2026-07-21)
- slug: reconcile-email-routing-addresses-during-worker-trigger-deployment-c02c216d7b9a
- score: 0.92

How to use it:

When a Worker’s Email Routing rules should match its configuration, set top-level `addresses` and run `wrangler deploy` or `wrangler triggers deploy`. Wrangler reconciles managed rules and requires confirmation for destructive changes; non-interactive destructive plans fail after Worker deployment.

Examples:

```
npx wrangler deploy
```

```
npx wrangler triggers deploy
```

```
{
  "name": "<worker-name>",
  "main": "<entrypoint>",
  "compatibility_date": "<YYYY-MM-DD>",
  "addresses": ["<recipient@example.com>", "*@<apex-domain>"]
}
```

- why_it_matters: Deploy a Worker whose configuration defines Email Routing addresses and keep its routing rules in sync.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.113.0>, <https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.113.0"; "addresses: Top-level string array of inbound addresses; each entry is a literal recipient or `*@domain` catch-all. Catch-all supports apex domains only. Omitted means no rule changes; an empty array removes all Email Routing rules managed by this Worker. Ignored under `env`."; "Prerequisite: Wrangler 4.113.0 or later."; "Prerequisite: For Worker deployment, Wrangler requires at minimum `name`, `main`, and `compatibility_date`; `main` may be omitted for assets-only Workers."; "Reconciliation runs after the Worker uploads, or when `wrangler triggers deploy` runs after a version promotion."; "Non-interactive destructive plans fail without modifying rules."

### Redact sensitive Workflows step output in local dev (2026-07-21)
- slug: redact-sensitive-workflows-step-output-in-local-dev-3fc490e0aef0
- score: 0.94

How to use it:

When a step’s output should be hidden during local Workflow development, set `sensitive: "output"` in its step config. Run the Workflow locally with Wrangler; the output is redacted in step logs and step-output responses while downstream steps receive the real value.

Examples:

```
await step.do("<step-name>", { sensitive: "output" }, async () => {
  return <value>;
});
```

```
npx wrangler dev
curl http://localhost:8787
```

- why_it_matters: Run a Workflow locally with steps whose output is marked sensitive.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.113.0>, <https://developers.cloudflare.com/api/resources/workflows/>, <https://developers.cloudflare.com/workflows/get-started/guide/>, <https://developers.cloudflare.com/workflows/build/local-development/>
- gotchas: "Version: 4.113.0"; "sensitive: Set to `\"output\"` to redact the step output from logs and step-output responses."; "Prerequisite: Local Workflows development requires Wrangler v3.89.0 or later and Node.js 18.0.0 or later."; "The described redaction applies when running Workflows locally."; "Step errors are never redacted."

### wrangler configuration declares Email Routing addresses (2026-07-17)
- slug: wrangler-configuration-declares-email-routing-addresses-ba3bc6724a70
- score: 0.96

How to use it:

To declare inbound addresses handled by a Worker, add the optional top-level `addresses` array to `wrangler.json` with literal addresses or `*@domain` catch-alls.

Examples:

```
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-21",
  "addresses": ["support@example.com", "*@example.com"]
}
```

- why_it_matters: Configure the inbound email addresses handled by a Worker in `wrangler.json`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.112.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/>
- gotchas: "Version: 4.112.0"; "addresses: Top-level list of inbound addresses routed to the Worker. Entries can be literal recipient addresses or `*@domain` catch-alls; catch-alls support apex domains only."; "Prerequisite: The current Email Routing documentation says this feature requires Wrangler 4.113.0 or later."; "Prerequisite: Before creating an Email Routing rule, add and verify at least one destination address."; "The field declares inbound email addresses handled by the Worker."; "Docs conflict: The Wrangler 4.112.0 release note introduces `addresses`, but current Email Routing documentation says the feature requires Wrangler 4.113.0 or later. The current requirement is for a newer version than the card."

### wrangler test harness accesses Durable Object storage (2026-07-17)
- slug: wrangler-test-harness-accesses-durable-object-storage-b60bb3910b70
- score: 0.95

How to use it:

When a Worker test needs to seed or inspect SQLite-backed Durable Object state, use `worker.getDurableObjectStorage()` with the binding or exported class name and an instance name or ID, then run SQL with `storage.exec()`.

Examples:

```
const server = createTestHarness({ workers: [{ configPath: "./wrangler.json" }] });
await server.listen();
const worker = server.getWorker();
const storage = await worker.getDurableObjectStorage("COUNTER", { name: "user-123" });
await worker.fetch("/counter/user-123");
const rows = await storage.exec("SELECT value FROM counters WHERE id = ?", "user-123");
expect(rows).toEqual([{ value: 1 }]);
```

- why_it_matters: Seed or assert SQLite-backed Durable Object storage state in a Worker test using `createTestHarness()`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.112.0>, <https://developers.cloudflare.com/workers/testing/test-harness/prepare-test-state/>, <https://github.com/cloudflare/workers-sdk/blob/cb6c3f9a5c6d67804cd0cb447cc0837a9f75848c/packages/wrangler/src/api/test-harness.ts>
- gotchas: "Version: 4.112.0"; "classNameOrBindingName (required): The Durable Object exported class name or namespace binding name."; "options (required): Select the Durable Object instance by `name` or `id`."; "storage.exec(sql, ...params) (required): Executes SQL inside the target Durable Object and returns all rows; SQL parameters follow the query string."; "Prerequisite: The Durable Object must be SQLite-backed; the method returns its storage handle."; "Prerequisite: Configure the test harness with a Worker via Wrangler config or inline config, then start it with `server.listen()`."; "The storage access shown is for a SQLite-backed Durable Object."

### createTestHarness can evict running Durable Objects (2026-07-15)
- slug: createtestharness-can-evict-running-durable-objects-dd8ee20330fe
- score: 0.96

How to use it:

When testing recovery after a running Durable Object is torn down, call `worker.evictDurableObject(classNameOrBindingName, { name })` from a Wrangler test harness. It preserves durable storage and resets in-memory state on the next start.

Examples:

```
const worker = server.getWorker();
await worker.evictDurableObject("Counter", { name: "user-123" });
```

- why_it_matters: Test how a running Durable Object recovers after its instance is torn down.
- before: The release note says this release adds Durable Object eviction support to `createTestHarness`; it does not specify an earlier workaround.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.111.0>, <https://github.com/cloudflare/workers-sdk/blob/wrangler%404.111.0/packages/wrangler/src/api/test-harness.ts>, <https://developers.cloudflare.com/workers/testing/test-harness/get-started/>
- gotchas: "Version: 4.111.0"; "classNameOrBindingName (required): Exported Durable Object class name or binding name; class names resolve first."; "options.name (required): Instance name; provide this or `id`."; "options.id (required): Instance ID; provide this or `name`, but not both."; "options.webSockets: Choose `\"close\"` or `\"hibernate\"` for WebSockets."; "Prerequisite: Use Wrangler 4.111.0 or later; the release adds Durable Object eviction support to `createTestHarness`."; "Prerequisite: Harness setup requires a Worker project with Wrangler configuration, a Node.js test runner, and Wrangler installed as a development dependency."

### wrangler Workflow steps support dynamic retry delays in local dev (2026-07-09)
- slug: wrangler-workflow-steps-support-dynamic-retry-delays-in-local-dev-6a1608ccc313
- score: 0.92

How to use it:

When a Workflow step needs a retry delay that varies by failed attempt, set `retries.delay` to a function that receives `{ ctx, error }` and returns milliseconds or a duration string.

Examples:

```
await step.do("call flaky API", { retries: { limit: 5, backoff: "constant", delay: ({ ctx }) => ctx.attempt * 1000 } }, async () => { /* ... */ });
```

- why_it_matters: Set per-attempt retry delays for a Workflow step when running it in local development.
- before: Step retries used fixed delay durations with a backoff strategy.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.110.0>, <https://developers.cloudflare.com/workflows/build/sleeping-and-retrying/>, <https://developers.cloudflare.com/workflows/build/step-context/>, <https://developers.cloudflare.com/workflows/>, <https://developers.cloudflare.com/changelog/post/2026-07-09-dynamic-retry-delays/>
- gotchas: "Version: 4.110.0"; "Availability: In local dev."; "retries.limit (required): Maximum number of retries for the step."; "retries.delay (required): Fixed duration or function returning the next delay in milliseconds or as a duration string."; "retries.backoff: Retry backoff strategy: `constant`, `linear`, or `exponential`."; "ctx (required): Current Workflow step context; `ctx.attempt` is the 1-indexed attempt number."; "error (required): Error that caused the retry."; "Prerequisite: Cloudflare Workflows is available on Free and Paid plans."; "The function is invoked once per failed attempt with a 5 second timeout."; "If the function throws, times out, or returns an invalid value, the step fails without further retries."; "Docs conflict: The current retry documentation was updated after Wrangler 4.110.0 and also documents Promise-returning delay functions; that support is not stated in the release note."

### createTestHarness can list Durable Object IDs (2026-07-09)
- slug: createtestharness-can-list-durable-object-ids-ebc38206c1d8
- score: 0.92

How to use it:

When an integration test needs persisted Durable Object IDs, call `listDurableObjectIds(<bindingName>)` on the `WorkerHandle` returned by `createTestHarness().getWorker()`. It returns a promise of string IDs for instances with persisted storage on that binding.

Examples:

```
import { createTestHarness } from "wrangler";
const server = createTestHarness({ workers: [{ configPath: "./wrangler.jsonc" }] });
const worker = server.getWorker();
const ids = await worker.listDurableObjectIds("<bindingName>");
```

- why_it_matters: Discover persisted Durable Object instances in an integration test using `createTestHarness`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.109.0>, <https://github.com/cloudflare/workers-sdk/blob/wrangler@4.109.0/packages/wrangler/src/api/test-harness.ts>, <https://developers.cloudflare.com/workers/testing/test-harness/configure/>, <https://developers.cloudflare.com/workers/testing/test-harness/get-started/>
- gotchas: "Version: 4.109.0"; "bindingName (required): Name of a Durable Object namespace binding configured on the Worker; the method returns persisted instance IDs as strings."; "workers[].configPath (required): Path to the Wrangler configuration file for the Worker; relative paths resolve from the harness root."; "Prerequisite: Use a Worker project with a Wrangler configuration file, a Node.js test runner, and Wrangler installed as a development dependency."; "The IDs are for persisted Durable Object instances associated with a Durable Object binding."; "Docs conflict: The newer Wrangler API page, last updated Sep 28, 2026, omits `listDurableObjectIds` from its listed WorkerHandle methods; the Wrangler 4.109.0 source defines it. https://developers.cloudflare.com/workers/wrangler/api/"

### wrangler turnstile widget CRUD commands (2026-07-09)
- slug: wrangler-turnstile-widget-crud-commands-cd46b9720486
- score: 0.98

How to use it:

When configuring or maintaining a repository's Turnstile integration, use Wrangler's widget subcommands to create, list, inspect, update, or delete widgets. For machine-readable output, add `--json`; deleting with JSON also requires `--skip-confirmation` or `-y`.

Examples:

```
wrangler turnstile widget create <name> --domain <domain> --mode managed
```

```
wrangler turnstile widget list --json
wrangler turnstile widget get <sitekey> --json
wrangler turnstile widget update <sitekey> --name "Renamed" --json
wrangler turnstile widget delete <sitekey> --json --skip-confirmation
```

- why_it_matters: Manage Turnstile widgets from the CLI while configuring or maintaining a repository's Turnstile integration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.109.0>, <https://developers.cloudflare.com/turnstile/spin/>
- gotchas: "Version: 4.109.0"; "<name> (required): Widget name."; "--domain <domain> (required): Accepted hostname; repeat the flag or provide comma-separated hostnames."; "--mode <mode> (required): Widget mode; create example uses `managed`."; "<sitekey> (required): Widget identifier for get, update, or delete."; "--json: Request machine-readable output; supported by all five subcommands."; "--skip-confirmation / -y (required): For delete with `--json`, bypass confirmation so output remains pipeable."; "Prerequisite: Wrangler 4.109 or later is required for the existing-widget recovery flow."; "Prerequisite: API token authentication uses `Account.Turnstile:Edit`."; "`delete --json` requires `--skip-confirmation` or `-y` to keep output pipeable."; "`--domain` accepts comma-separated values."; "`list` and `update` redact the secret; `get` can retrieve it later."; "Existing OAuth sessions need to run `wrangler login` again to obtain the `challenge-widgets.write` scope."; "API token users need a token with the `Account.Turnstile:Edit` permission."

### wrangler workflows instances terminate supports rollback (2026-07-09)
- slug: wrangler-workflows-instances-terminate-supports-rollback-6ecb3fdf677e
- score: 0.96

How to use it:

When terminating a Workflow instance and you want registered rollback handlers to run first, call `WorkflowInstance.terminate({ rollback: true })` or use Wrangler’s terminate command with `--rollback`.

Examples:

```
let instance = await env.MY_WORKFLOW.get("<INSTANCE_ID>");
await instance.terminate({ rollback: true });
```

```
npx wrangler workflows instances terminate <WORKFLOW_NAME> <INSTANCE_ID> --rollback
```

```
npx wrangler workflows instances terminate <WORKFLOW_NAME> <INSTANCE_ID> --local --rollback
```

- why_it_matters: Terminate a Workflow instance while running its registered rollback handlers.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.109.0>, <https://developers.cloudflare.com/workflows/build/workers-api/>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>, <https://developers.cloudflare.com/workflows/build/trigger-workflows/>
- gotchas: "Version: 4.109.0"; "Availability: CLI rollback support includes local mode."; "rollback: Set to `true` to run registered rollback handlers before the instance reaches `terminated`; steps without rollback handlers are skipped."; "--rollback: Run registered rollback handlers before terminating; default is `false`."; "<WORKFLOW_NAME> (required): Name of the workflow."; "<INSTANCE_ID> (required): ID of the instance; `latest` can be used instead of a UUID."; "--local: Interact with the local dev session."; "The rollback option is only sent for terminate operations."; "The Local Explorer API rejects the option for pause, resume, and restart actions."

### wrangler deploy declares Durable Object lifecycle with exports (2026-07-02)
- slug: wrangler-deploy-declares-durable-object-lifecycle-with-exports-efd1292b1b8a
- score: 0.97

How to use it:

When declaring Durable Object class lifecycle in Wrangler config, use `exports` entries keyed by class name and deploy with `wrangler deploy`.

Examples:

```
npx wrangler deploy
```

- why_it_matters: Declare Durable Object lifecycle changes and use the declarations in deployment, local development, tests, and generated types.
- before: The release note describes `migrations` as the legacy imperative alternative to declarative `exports`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.107.0>, <https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/changelog/post/2026-06-30-declarative-do-class-exports/>
- gotchas: "Version: 4.107.0"; "exports.<Class>.type (required): Set to `\"durable-object\"` for a Durable Object class entry."; "exports.<Class>.state: Lifecycle state: `created` (default), `deleted`, `renamed`, `transferred`, or `expecting-transfer`."; "exports.<Class>.storage (required): Required for `created` or `expecting-transfer`; use `sqlite` for new namespaces."; "exports.<Class>.renamed_to (required): For `renamed`, names the destination class, which must also be a live entry in `exports`."; "exports.<Class>.transferred_to (required): For `transferred`, names the target Worker."; "exports.<Class>.transfer_from (required): For `expecting-transfer`, names the source Worker."; "Prerequisite: Declare the class in Worker code and export it; add a `durable_objects.bindings` entry if the Worker needs to access it through `env`."; "Prerequisite: For newly created namespaces, use `storage: \"sqlite\"`; `legacy-kv` is accepted only for already provisioned key-value namespaces."; "`type` is currently always `\"durable-object\"`."; "The `state` field defaults to `\"created\"` (live) when omitted."; "An actor binding (`durable_objects.bindings`) to a class declared only in `exports` on the same `wrangler versions upload` is rejected with error code 100406 because the binding cannot resolve until the namespace is provisioned."; "For that version upload constraint, stage the class via `ctx.exports.X` without a binding and add the binding at deploy time, or use `wrangler deploy` to provision and bind in one step; the same constraint applies to the `migrations` flow."; "Multi-version percentage deploys with selected versions that disagree on declarative `exports` are rejected; deploy the version that changes `exports` at 100% first, then run the percentage-split deploy. Single-version (100%) deploys are unaffected."; "Docs conflict: The current Durable Object docs say `wrangler versions upload` fails when the configuration contains `exports`, and that lifecycle changes apply only through `wrangler deploy`; this differs from the supplied v4.107.0 release note, which says upload forwards `exports` and reconciliation occurs at version deploy or `wrangler deploy`. https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/"; "Docs conflict: The current docs say gradual deployments are unsupported with `exports`; this differs from the supplied release note's percentage-split deployment guidance. The current docs are newer than v4.107.0. https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/"

### wrangler flagship manages Flagship apps and flags (2026-07-02)
- slug: wrangler-flagship-manages-flagship-apps-and-flags-df9829b61730
- score: 0.94

How to use it:

If your Wrangler workflow needs to manage Flagship apps or feature flags, use `wrangler flagship apps` for apps and `wrangler flagship flags <APP-ID>` for flags; add the documented subcommand and arguments for the action, such as creating, inspecting, evaluating, rolling out, or deleting.

Examples:

```
wrangler flagship apps create <NAME>
```

```
wrangler flagship flags create <APP_ID> <KEY> --variation <NAME>=<VALUE> --default <NAME> --type <boolean|string|number|json>
```

```
wrangler flagship flags evaluate <APP_ID> <KEY> --context <NAME>=<VALUE> --targeting-key <KEY>
```

- why_it_matters: Manage Flagship apps and feature flags from a coding workflow that uses Wrangler.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.107.0>, <https://developers.cloudflare.com/workers/wrangler/commands/flagship/>, <https://developers.cloudflare.com/flagship/reference/wrangler-commands/>
- gotchas: "Version: 4.107.0"; "<NAME> (required): App name."; "<APP_ID> (required): App ID; first argument to flag commands."; "<KEY> (required): Flag key."; "--variation <name>=<value> (-V): Add a variation; repeatable. All variations on a flag must resolve to one value type."; "--default <NAME>: Choose the default variation."; "--type <TYPE>: Flag value type: boolean, string, number, or json; inferred if omitted."; "--context <NAME>=<VALUE>: Evaluation context attribute; repeatable. Values are sent as strings."; "--targeting-key <KEY>: Stable bucketing key for percentage rollouts."; "Prerequisite: Wrangler v4.107.0 or later."; "Prerequisite: Authenticate with `wrangler login` or `CLOUDFLARE_API_TOKEN` with Flagship permissions. Reads require `flagship:read`; writes require `flagship:write`. Most writes that update existing flags also need read permission."

### wrangler stores OAuth credentials in the OS keychain (2026-07-02)
- slug: wrangler-stores-oauth-credentials-in-the-os-keychain-eae9858ee267
- score: 0.90

How to use it:

When Wrangler OAuth credentials should be encrypted at rest, run `wrangler login --use-keyring` to store them in an encrypted file with its key in the OS keychain; existing plaintext credentials migrate on first opt-in.

Examples:

```
npx wrangler login --use-keyring
```

```
CLOUDFLARE_AUTH_USE_KEYRING=true npx wrangler deploy
```

```
npx wrangler login --no-use-keyring
```

- why_it_matters: Opt into encrypted OAuth credential storage when authenticating Wrangler on a development machine or CI runner.
- before: Wrangler stored OAuth access and refresh tokens in a plaintext TOML file by default.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.107.0>, <https://developers.cloudflare.com/workers/wrangler/commands/general/>, <https://developers.cloudflare.com/workers/wrangler/install-and-update/>
- gotchas: "Version: 4.107.0"; "Requires Windows lazily installs `@napi-rs/keyring` (~1.9 MB) on first opt-in; Linux requires `secret-tool` from `libsecret-tools`."; "--use-keyring: Store OAuth credentials in an encrypted file with the encryption key in the OS keychain; persists the choice."; "--no-use-keyring: Opt out; deletes encrypted credentials and the keychain entry."; "CLOUDFLARE_AUTH_USE_KEYRING: Set to `true` or `false` to override the saved preference for one invocation."; "Prerequisite: macOS uses `/usr/bin/security`; Linux requires `secret-tool` from the `libsecret-tools` package. Windows uses `@napi-rs/keyring`, installed lazily on opt-in; for non-interactive environments, install it ahead of time with `npm install -g @napi-rs/keyring@<version>`."; "Prerequisite: Wrangler CLI and an OAuth login flow are required for `wrangler login`; Wrangler recommends installing it locally in the project."; "Keyring storage is opt-in; plaintext-file storage remains the default."; "Opting out deletes encrypted credentials instead of decrypting them back to disk, so re-authentication is required."; "The preference applies to every auth profile; each named profile gets its own encrypted file and key."; "Windows errors with instructions in non-interactive/CI contexts when keyring support is first opted into."

### createTestHarness() introspects Workflow bindings (2026-06-30)
- slug: createtestharness-introspects-workflow-bindings-3961465cf9b0
- score: 0.98

How to use it:

When a Worker route starts a Workflow, use `createTestHarness()` to introspect its binding, disable the named sleep, trigger the route, and wait for the instance to complete.

Examples:

```
const harness = createTestHarness({ workers: [{ configPath: "./wrangler.json" }] });
const worker = harness.getWorker();
await using workflow = await worker.introspectWorkflow("MY_WORKFLOW");
await workflow.modifyAll(async (modifier) => {
  await modifier.disableSleeps([{ name: "wait-for-approval" }]);
});
await worker.fetch("/start-workflow");
const [instance] = await workflow.get();
await instance.waitForStatus("complete");
```

- why_it_matters: Test a Worker route that starts a Workflow and wait for the resulting Workflow instance to complete.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://developers.cloudflare.com/workers/testing/test-harness/interact-with-workers/>, <https://developers.cloudflare.com/workers/testing/test-harness/get-started/>
- gotchas: "Version: wrangler@4.106.0"; "workers[].configPath (required): Path to the Worker Wrangler configuration file."; "bindingName (required): Workflow binding name to introspect; instances created after introspection starts are captured."; "disableSleeps([{ name }]): Disables the specified Workflow sleep; `name` identifies the sleep step."; "waitForStatus(status) (required): Waits until the instance reaches the requested status; use `\"complete\"` here."; "Prerequisite: A Worker project with a Wrangler configuration file, a Node.js test runner, and `wrangler` installed as a development dependency."; "Introspection is by Workflow binding name."; "Tests can introspect a known Workflow instance by ID or track instances created after introspection starts."; "Docs conflict: Current documentation was last updated July 27, 2026, after Wrangler 4.106.0. Its example uses an async `modifyAll` callback and awaits `disableSleeps`; the release-note example uses a synchronous callback. The release note is retained for the target version."

### createTestHarness() overrides bindings and accesses Worker exports (2026-06-30)
- slug: createtestharness-overrides-bindings-and-accesses-worker-exports-7c2ceab48e4d
- score: 0.96

How to use it:

When a config-backed Worker needs a mock for a service binding, set `bindingOverrides` to the mock Worker’s harness name. To control the mock, call `getExport()` on `server.getWorker(name)` and use its default export’s RPC methods.

Examples:

```
import { createTestHarness } from "wrangler";

const server = createTestHarness({
  workers: [
    {
      configPath: "<path-to-worker-wrangler-config>",
      bindingOverrides: { <BINDING_NAME>: "<mock-worker-name>" },
    },
    { configPath: "<path-to-mock-worker-wrangler-config>" },
  ],
});

const mock = await server.getWorker("<mock-worker-name>").getExport();
await mock.<rpcMethod>(<arguments>);
```

- why_it_matters: Test a Worker that depends on a platform binding by replacing it with a mock Worker and controlling the mock's exported methods.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://developers.cloudflare.com/workers/wrangler/api/>
- gotchas: "Version: wrangler@4.106.0"; "bindingOverrides: A record mapping binding names in this Worker's environment to Worker names in this test harness."; "configPath (required): Path to a Wrangler configuration file; relative paths resolve from `root`."; "server.getWorker(name): Returns a Worker handle; omit the name to select the primary Worker."; "getExport(): Returns the default Worker export, including RPC methods."; "Prerequisite: Import `createTestHarness` from `wrangler`; use Node.js test runner environment. The harness runs production build output from Wrangler config files, Vite-generated configs, or inline Wrangler config objects."; "This applies to test harness Workers loaded from Wrangler config files."; "Binding overrides can target a Worker in the same harness."; "`getExport()` is called on a Worker returned by `server.getWorker(name)` and accesses JSRPC methods on its default Worker export."

### createTestHarness() Worker handles apply local D1 migrations (2026-06-30)
- slug: createtestharness-worker-handles-apply-local-d1-migrations-6fb2d71b8e9c
- score: 0.97

How to use it:

When tests need a local D1 schema before requests, call `applyD1Migrations("DATABASE")` on the Worker handle returned by `server.getWorker()`; call it after storage is reset.

Examples:

```
const worker = server.getWorker();
beforeEach(async () => {
  await worker.applyD1Migrations("DATABASE");
});
```

- why_it_matters: Run tests that need a local D1 database schema initialized before sending requests to a test harness Worker.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://developers.cloudflare.com/workers/testing/test-harness/prepare-test-state/>, <https://developers.cloudflare.com/workers/wrangler/api/>
- gotchas: "Version: wrangler@4.106.0"; "bindingName (required): D1 binding to migrate; reads its Wrangler migration settings."; "Prerequisite: Use a test harness Worker with a configured D1 binding. Migrations use configured `migrations_dir` and `migrations_pattern`; without them, `.sql` files are read from the `migrations` directory relative to the config file."; "Applies local D1 migrations before running requests."

### wrangler ai-search jobs manages indexing jobs (2026-06-30)
- slug: wrangler-ai-search-jobs-manages-indexing-jobs-ca916a2e029f
- score: 0.95

How to use it:

When managing indexing jobs for an AI Search instance, use `wrangler ai-search jobs` with the instance name and, for job-specific operations, the job ID. Add `--namespace`/`-n` to select a namespace (default `default`) and `--json` for machine-readable output except on `cancel`.

Examples:

```
wrangler ai-search jobs list <instance> [--namespace <namespace>] [--json]
```

```
wrangler ai-search jobs create <instance> --description "manual reindex" [--namespace <namespace>] [--json]
```

```
wrangler ai-search jobs get <instance> <job-id> [--namespace <namespace>] [--json]
wrangler ai-search jobs cancel <instance> <job-id> [--namespace <namespace>]
wrangler ai-search jobs logs <instance> <job-id> [--namespace <namespace>] [--json]
```

- why_it_matters: Manage indexing jobs for an AI Search instance from the CLI.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://9a51ac8b.previews.developers.cloudflare.com/ai-search/wrangler-commands/>
- gotchas: "Version: wrangler@4.106.0"; "<instance> (required): AI Search instance name."; "<job-id> (required): Indexing job ID; required for get, cancel, and logs."; "--namespace / -n: Select the instance namespace; defaults to `default`."; "--description: Optional description for the indexing job."; "--json: Return clean JSON; supported by list, create, get, and logs, but not cancel."; "All commands accept `--namespace`/`-n`; it defaults to `default`."; "All commands except `cancel` accept `--json`."

### wrangler auth profiles bind OAuth logins to directories (2026-06-30)
- slug: wrangler-auth-profiles-bind-oauth-logins-to-directories-d7a985ab01d2
- score: 0.98

How to use it:

When projects need separate Cloudflare OAuth logins, create a named profile and bind it to each project directory; bindings apply to subdirectories. Use `--profile` for a one-command override, and account ID settings remain respected.

Examples:

```
wrangler auth create <name>
wrangler auth activate <name> <directory>
```

```
wrangler auth list
wrangler auth deactivate <directory>
wrangler auth delete <name>
```

```
wrangler <command> --profile <name>
```

- why_it_matters: Use separate Wrangler OAuth logins for projects in different directories while retaining existing token and account settings.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://7617740f.previews.developers.cloudflare.com/workers/wrangler/profiles/>
- gotchas: "Version: wrangler@4.106.0"; "<name> (required): Profile name to create, activate, or delete; creation starts OAuth login."; "[dir]: Directory to bind or deactivate; activation defaults to the current working directory, and the binding applies to subdirectories."; "--profile <name>: Select a profile for one command run without changing directory bindings."; "CLOUDFLARE_API_TOKEN: When set, takes precedence over profiles."; "CLOUDFLARE_ACCOUNT_ID: Account ID setting respected when resolving the target account."; "account_id: Wrangler configuration setting respected when resolving the target account."; "Prerequisite: Creating a profile starts an OAuth flow; choose which accounts the profile may reach."; "`wrangler auth create <name>` creates or re-authenticates a named profile via OAuth."; "`wrangler auth activate <name> [dir]` defaults to cwd; subdirectories inherit the profile."; "`CLOUDFLARE_API_TOKEN` takes precedence over profiles when set."; "Account ID settings via `CLOUDFLARE_ACCOUNT_ID` or Wrangler config continue to be respected."; "Docs conflict: The documentation was updated Sep 17, 2026, after Wrangler 4.106.0. It says that when CLOUDFLARE_API_TOKEN is set, profile create, activate, deactivate, and delete commands cannot be used; the release note states token precedence but does not mention this restriction."

### wrangler versions upload adds strict pre-upload checks (2026-06-30)
- slug: wrangler-versions-upload-adds-strict-pre-upload-checks-4a84f9755000
- score: 0.96

How to use it:

When uploading a Worker version in CI or another non-interactive environment, run `wrangler versions upload --strict` to abort on the listed configuration conflicts.

Examples:

```
npx wrangler versions upload --strict
```

- why_it_matters: Upload a Worker version in CI or another non-interactive environment where configuration conflicts must stop the upload.
- before: Dashboard-edited Worker configuration previously triggered an unconditional warning; the release note says the check now warns only for destructive diffs.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: wrangler@4.106.0"; "--strict: Boolean; defaults to false. Enables strict mode, which prevents uploads when there are conflicting remote changes."; "[PATH]: Optional path to a Worker entry point or static assets directory."; "Prerequisite: Wrangler 3.40.0 or later is required for versions commands. Wrangler 4.106.0 meets this minimum."; "`--strict` aborts in non-interactive/CI environments when any of the listed conflicts are detected."; "Dashboard-edited Worker configurations are warned about only when the diff is destructive."; "Warnings are shown for local configuration values that conflict with remote secrets and workflows belonging to a different Worker."

### wrangler containers registries configure supports Google Artifact Registry credentials (2026-06-25)
- slug: wrangler-containers-registries-configure-supports-google-artifact-registry-crede-901987f49767
- score: 0.98

How to use it:

For a Google Artifact Registry host matching `*-docker.pkg.dev`, configure access with the service account email and key. The email must match the key’s `client_email`; if reusing an existing Secrets Store secret, omit the key and Wrangler validates it when images are pulled.

Examples:

```
cat <PATH_TO_KEY.json> | npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<SECRET_NAME> --skip-confirmation
```

```
npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<EXISTING_SECRET_NAME> --skip-confirmation
```

- why_it_matters: Configure a repository’s container registry access for images hosted in Google Artifact Registry.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.105.0>, <https://developers.cloudflare.com/containers/guides/image-management/>, <https://developers.cloudflare.com/containers/reference/wrangler-commands/>
- gotchas: "Version: 4.105.0"; "DOMAIN (required): Registry domain; for Google Artifact Registry, use a `*-docker.pkg.dev` host."; "--gar-email: Google service account email for the registry; must match `client_email` in the service account key."; "stdin secret: Service account JSON key as a file path, raw JSON, or base64; not needed when reusing an existing secret."; "--secret-store-id: ID of the Secrets Store for registry credentials."; "--secret-name: Name under which Wrangler stores the registry credentials, or the name of the existing secret to reuse."; "credential flags: Registry credential flags are mutually exclusive; use the one matching the registry provider."; "Prerequisite: Create a Google service account and grant it the Artifact Registry Reader role; obtain its JSON key."; "Prerequisite: Supported Google registry hosts match `*-docker.pkg.dev`; `gcr.io` and `*.gcr.io` are unsupported."; "The `--gar-email` value must match `client_email` in the service account key."; "The service account JSON key is provided via stdin (a file path, raw JSON, or base64) or an interactive prompt (a file path or base64); it is never a CLI flag."; "When the target Secrets Store secret already exists, it is reused by reference and the key is not required."; "When reusing an existing secret, the email cannot be verified locally; it is validated against the key when images are pulled."

### wrangler createTestHarness Worker handles expose getEnv() (2026-06-23)
- slug: wrangler-createtestharness-worker-handles-expose-getenv-b786c68f3df2
- score: 0.97

How to use it:

When inspecting a Worker environment in a `createTestHarness()` test, call `await server.getWorker<Env>().getEnv()` to read its configured variables, secrets, and bindings.

Examples:

```
const env = await server.getWorker<Env>().getEnv();
```

- why_it_matters: Inspect a test harness Worker’s environment while testing code that uses its vars, secrets, or bindings.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.104.0>, <https://developers.cloudflare.com/workers/wrangler/api/>, <https://developers.cloudflare.com/workers/testing/test-harness/configure/>, <https://developers.cloudflare.com/workers/testing/test-harness/get-started/>
- gotchas: "Version: 4.104.0"; "Env: Type argument for the Worker environment; define it manually or generate it from Wrangler configuration."; "getEnv() (required): Takes no arguments; returns the Worker’s full configured environment, including variables, secrets, and bindings."; "Prerequisite: Use a Worker project with a Wrangler configuration file, a Node.js test runner, and `wrangler` installed as a development dependency."

### wrangler build emits a Build Output API directory (2026-06-18)
- slug: wrangler-build-emits-a-build-output-api-directory-e980c0a12de2
- score: 0.90

How to use it:

When building with `--experimental-new-config`, run `wrangler build --experimental-new-config --experimental-cf-build-output` to emit the self-contained Build Output API directory under `.cloudflare/output/v0/`.

Examples:

```
wrangler build --experimental-new-config --experimental-cf-build-output
```

- why_it_matters: Build a project using the new configuration path and produce a self-contained Build Output API directory.
- before: The build delegated to `wrangler deploy --dry-run`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.102.0>
- gotchas: "Version: 4.102.0"; "Availability: experimental"; "--experimental-new-config (required): Use alongside `--experimental-cf-build-output`."; "--experimental-cf-build-output (required): Make `wrangler build` emit the Build Output API directory under `.cloudflare/output/v0/`; use alongside `--experimental-new-config`."; "Use `--experimental-cf-build-output` alongside `--experimental-new-config`."

### wrangler createTestHarness exposes per-Worker resource accessors (2026-06-16)
- slug: wrangler-createtestharness-exposes-per-worker-resource-accessors-2edb85540bdb
- score: 0.97

How to use it:

When testing a Worker with configured KV, R2, D1, or Durable Object bindings, call `server.getWorker(name)` and use that handle’s accessor for the binding.

Examples:

```
import { createTestHarness } from "wrangler";

const server = createTestHarness({ workers: [{ configPath: "<wrangler-config-path>" }] });
const worker = server.getWorker("<worker-name>");
const kv = await worker.getKVNamespace("<KV-binding>");
const bucket = await worker.getR2Bucket("<R2-binding>");
const db = await worker.getD1Database("<D1-binding>");
const objects = await worker.getDurableObjectNamespace("<DO-binding>");
```

- why_it_matters: Test a Worker that uses configured KV, R2, D1, or Durable Object resources.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.101.0>, <https://github.com/cloudflare/workers-sdk/blob/41f391fdda4112ee333782aad02d16dacaa95f8f/packages/wrangler/src/api/test-harness.ts>
- gotchas: "Version: 4.101.0"; "server.getWorker(name): Returns a handle for the named Worker; without a name, returns the primary Worker."; "bindingName (required): Binding name passed to `getKVNamespace`, `getR2Bucket`, `getD1Database`, or `getDurableObjectNamespace`; returns that configured resource on this Worker."; "Prerequisite: Create the harness with at least one Worker; the resource must be configured on the selected Worker."; "Accessors are for configured KV namespaces, R2 buckets, D1 databases, and Durable Object namespaces."; "Resources are scoped to the specific Worker returned by `server.getWorker(name)`. The source does not name accessor methods for KV namespaces or Durable Object namespaces."

### wrangler temporary preview account workflow with --temporary (2026-06-16)
- slug: wrangler-temporary-preview-account-workflow-with-temporary-362d237a49aa
- score: 0.96

How to use it:

When unauthenticated, run the supported Wrangler command with `--temporary` to use a temporary preview account. Follow Wrangler’s ToS and Privacy Policy notice, then claim the account using the printed URL within 60 minutes.

Examples:

```
npx wrangler deploy --temporary
```

- why_it_matters: Deploy or manage a Worker from an environment with no Cloudflare credentials using a temporary preview account.
- before: Start the OAuth login flow to authenticate before running the command.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.101.0>, <https://developers.cloudflare.com/workers/platform/claim-deployments/>
- gotchas: "Version: 4.101.0"; "Availability: Temporary Cloudflare preview account; short-lived account token. Available only on Workers (`deploy`, `versions upload`, and related commands), KV, D1, Hyperdrive, Queues, and certificate commands. For unauthenticated use only."; "--temporary: Use a temporary account; supported only on commands that accept temporary credentials. Existing OAuth, API token, or global API key credentials cause an error."; "Prerequisite: Wrangler 4.102.0 or later is required by the current deployment instructions. Claim the account within 60 minutes; the user must complete the claim flow before the deadline."; "Using `--temporary` while already authenticated with OAuth, `CLOUDFLARE_API_TOKEN`, or a global API key errors."; "Interactive terminals prompt for `yes` to accept Cloudflare's Terms of Service and Privacy Policy; non-interactive shells print a notice and continue."; "The account must be claimed using the printed claim URL before it expires."; "The cached account is cleared on successful login or logout."; "The exact expiration duration and complete list of supported commands are not stated."; "Docs conflict: The release note identifies this feature in Wrangler 4.101.0; current Cloudflare instructions say the `--temporary` deployment workflow requires Wrangler 4.102.0 or later."

### wrangler dev serves local R2 objects at a public URL (2026-06-11)
- slug: wrangler-dev-serves-local-r2-objects-at-a-public-url-30bd2cac29cd
- score: 0.95

How to use it:

When testing a Worker with a local R2 binding, request the object from the running `wrangler dev` server at `/cdn-cgi/local/r2/public/<bucket-id>/<key>`. Use `bucket_name` as `<bucket-id>` when set, otherwise the binding; `remote: true` bindings are not exposed.

Examples:

```
curl http://localhost:8787/cdn-cgi/local/r2/public/<bucket-id>/<key>
```

- why_it_matters: When testing a Worker locally that serves objects from a local R2 binding, request an object through the dev server’s public-bucket route.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.100.0>, <https://developers.cloudflare.com/r2/get-started/workers-api/>
- gotchas: "Version: 4.100.0"; "<bucket-id> (required): Use the binding’s `bucket_name` when set; otherwise use its `binding`."; "<key> (required): Object key appended to the local public-bucket route."; "Prerequisite: Run `wrangler dev` locally; by default it uses a local R2 simulation."; "Only local R2 bindings are exposed; bindings configured with `remote: true` are not exposed."

### wrangler experimental TypeScript config via --x-new-config (2026-06-11)
- slug: wrangler-experimental-typescript-config-via-x-new-config-87655c7b9a16
- score: 0.95

How to use it:

When authoring a Worker config in TypeScript, add the required `cloudflare.config.ts` using `defineWorker` from `wrangler/experimental-config`, then run a supported Wrangler command with `--x-new-config`. Optionally add `wrangler.config.ts` using `defineWranglerConfig`; branch on `ctx.mode` in either file’s function form for per-environment settings.

Examples:

```
wrangler dev --x-new-config
```

```
wrangler build --x-new-config
```

```
import { defineWorker, bindings } from "wrangler/experimental-config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineWorker((ctx) => ({
  name: "<worker-name>",
  entrypoint,
  compatibilityDate: "<YYYY-MM-DD>",
  env: {
    MY_KV: bindings.kv(),
    MY_TEXT: bindings.text(`The mode is ${ctx.mode}`),
  },
}));
```

- why_it_matters: When authoring a Worker configuration in TypeScript, run Wrangler commands using the experimental config files.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.100.0>
- gotchas: "Version: 4.100.0"; "Availability: Experimental, opt-in; the flag, config formats, and `wrangler/experimental-config` exports may change in any release."; "--x-new-config (required): Opt into loading Worker configuration from `cloudflare.config.ts` for the supported commands."; "cloudflare.config.ts (required): Worker runtime configuration, authored with `defineWorker` from `wrangler/experimental-config`."; "wrangler.config.ts: Wrangler-specific development/build configuration, authored with `defineWranglerConfig` from `wrangler/experimental-config`."; "ctx.mode: Use within the function form of either config file to branch configuration by environment mode."; "Prerequisite: Wrangler 4.100.0 introduced the experimental opt-in; flag and config exports may change in any release."; "Prerequisite: Provide `cloudflare.config.ts`; `wrangler.config.ts` is optional."; "`cloudflare.config.ts` is required."; "`wrangler.config.ts` is optional."; "Per-environment configuration uses `ctx.mode` branching inside the function form of either file."

### wrangler createTestHarness() supports integration testing Workers (2026-06-09)
- slug: wrangler-createtestharness-supports-integration-testing-workers-b393214940be
- score: 0.98

How to use it:

When writing Worker integration tests with a Node.js test runner, use `createTestHarness()` with Wrangler config paths for the Workers. Start it before tests, then send requests or scheduled events through its handles; reset between tests and close after the suite.

Examples:

```
import { after, afterEach, before, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
  workers: [
    { configPath: "<path-to-web-worker-wrangler-config>" },
    { configPath: "<path-to-api-worker-wrangler-config>" },
  ],
});
const apiWorker = server.getWorker("<api-worker-name>");

before(async () => { await server.listen(); });
afterEach(async () => { await server.reset(); });
after(async () => { await server.close(); });

test("dispatches a request", async () => {
  const response = await server.fetch("<url-matching-configured-route>");
});

test("dispatches directly and triggers a scheduled event", async () => {
  await apiWorker.fetch("<request-url>");
  await apiWorker.scheduled({ cron: "<cron-expression>", scheduledTime: new Date() });
});

server.getLogs();
// On test failure:
server.debug();
```

```
const server = createTestHarness({
  workers: [{ configPath: "<generated-vite-worker-wrangler-config>" }],
});
```

- why_it_matters: When writing integration tests for Workers built by Wrangler or the Cloudflare Vite plugin, run them in a local preview environment using production build output.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.99.0>, <https://developers.cloudflare.com/workers/wrangler/api/>, <https://developers.cloudflare.com/workers/testing/test-harness/configure/>, <https://developers.cloudflare.com/workers/testing/test-harness/get-started/>
- gotchas: "Version: 4.99.0"; "workers (required): Worker inputs for the test server; the first Worker is primary."; "configPath (required): Wrangler configuration file path or URL; relative paths resolve from `root`."; "root: Base directory for resolving relative Worker config paths; defaults to `process.cwd()`."; "env: Wrangler environment to load from the config file."; "scheduled({ cron, scheduledTime }) (required): Dispatches a scheduled event directly to the selected Worker; documented example supplies a cron expression and `new Date()`."; "listen() (required): Starts the test server."; "reset(): Restores the options used when the current session started and recreates storage; the URL may change."; "close() (required): Stops the server and releases runtime resources."; "getLogs(): Returns captured Workers runtime logs for the current server session."; "debug(): Prints a diagnostic timeline including server events and captured Workers runtime logs."; "Prerequisite: Use a Node.js test runner and install `wrangler` as a development dependency."; "Prerequisite: For Cloudflare Vite plugin Workers, run `npx vite build` first so tests use production build output."; "Runs Workers in a local preview environment using production build output."; "Works with Wrangler projects and Workers built by the Cloudflare Vite plugin."; "Use from a Node.js test runner."

### wrangler versions deploy accepts --version-tag (2026-06-09)
- slug: wrangler-versions-deploy-accepts-version-tag-16440f51b1a7
- score: 0.98

How to use it:

If you need to deploy or roll back a Worker version by its upload tag, run `wrangler versions deploy --version-tag <sha>@100%`. Tags resolve against deployable versions; if a tag is missing or ambiguous, or the version is no longer deployable, use its Version ID instead.

Examples:

```
wrangler versions deploy --version-tag <sha>@100%
```

- why_it_matters: Roll out or roll back a Worker version identified by its upload tag.
- before: Look up the version ID first, then deploy using that ID.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.99.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.99.0"; "--version-tag <tag> (required): Worker Version tag to deploy; resolves to a Version ID among deployable versions. Accepts `<tag>@<percentage>` shorthand."; "Prerequisite: Use Wrangler 4.99.0 or later for `--version-tag` support."; "Prerequisite: Wrangler versions commands require Wrangler 3.40.0 or later; versions before 3.73.0 require `--x-versions`."; "Tags resolve only against recent deployable versions."; "If a tag matches no deployable version or matches more than one, the command errors and asks you to deploy by Version ID directly."; "Older versions that have aged out of the deployable window must be deployed by Version ID."

### wrangler D1 migrations_pattern selects migration files (2026-06-05)
- slug: wrangler-d1-migrations-pattern-selects-migration-files-27bcd6116dd5
- score: 0.97

How to use it:

When D1 migrations use nested directories, set `migrations_pattern` in the binding and run `wrangler d1 migrations apply` or `wrangler d1 migrations list` for the database. The pattern must start with the configured `migrations_dir`; `migrations_pattern` is optional and defaults to `${migrations_dir}/*.sql`.

Examples:

```
{
  "d1_databases": [{
    "binding": "DB",
    "database_name": "<DATABASE_NAME>",
    "database_id": "<UUID>",
    "migrations_dir": "migrations",
    "migrations_pattern": "migrations/*/migration.sql"
  }]
}
```

```
npx wrangler d1 migrations apply <DATABASE>
```

```
npx wrangler d1 migrations list <DATABASE>
```

- why_it_matters: Apply and list D1 migrations stored in nested layouts such as ORM-generated migration folders.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.98.0>, <https://developers.cloudflare.com/d1/reference/migrations/>, <https://developers.cloudflare.com/d1/wrangler-commands/>
- gotchas: "Version: 4.98.0"; "migrations_pattern: Glob for discovering migrations, relative to the Wrangler config file. `*` matches one path segment; `**` matches any number. Must start with `migrations_dir`."; "migrations_dir (required): Required when `migrations_pattern` is set; pattern must start with this directory."; "<DATABASE> (required): Database name or binding for the migration command."; "Prerequisite: Set `migrations_dir` when configuring `migrations_pattern`."; "Prerequisite: For a nested-only pattern, Wrangler's `migrations create` writes top-level files; generate new migrations using the ORM's command, such as `drizzle-kit generate`."; "`migrations_pattern` is a glob relative to the Wrangler config file."; "Files that do not match the pattern are not executed."; "The default pattern is `${migrations_dir}/*.sql`, preserving today's behaviour."; "When no migrations match the configured pattern but files matching `migrations/*/migration.sql` exist, Wrangler logs a hint suggesting `migrations_pattern` as an opt-in."

### wrangler deploy and versions upload accept a positional path (2026-06-05)
- slug: wrangler-deploy-and-versions-upload-accept-a-positional-path-bae2ebf91d50
- score: 0.97

How to use it:

If deploying a Worker entry point or static asset directory, pass its path positionally to `wrangler deploy` or `wrangler versions upload`; Wrangler treats it as the entry point or assets directory. For directory deployments, the release note says the positional path avoids an interactive confirmation prompt.

Examples:

```
npx wrangler deploy ./src/index.ts
```

```
npx wrangler deploy ./public
```

```
npx wrangler versions upload <path>
```

- why_it_matters: Deploy a Worker entry point or a directory of static assets using Wrangler.
- before: Use `--script` for a Worker file; the positional argument was `[script]`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.98.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.98.0"; "[PATH]: Path to a Worker entry point or static assets directory. Required for a Worker when the Wrangler config has no `main` key. For static assets, overrides configured assets and is equivalent to `--assets`."; "--assets <directory>: Folder of static assets to serve; equivalent to passing the assets directory as the positional path."; "--script: Release note says this option is hidden and deprecated, remains for backwards compatibility, and accepts file paths only."; "`--script` remains available for backwards compatibility but only accepts file paths."; "Passing a directory to `--script` produces an error suggesting the positional `path` argument or `--assets` flag."; "Docs conflict: Current Wrangler docs say positional asset paths work only in interactive mode, conflicting with the release note's statement that directory deployment avoids an interactive confirmation prompt. Current docs may describe a newer version: https://developers.cloudflare.com/workers/wrangler/commands/workers/"

### wrangler workflows instances restart supports restarting from a step (2026-06-02)
- slug: wrangler-workflows-instances-restart-supports-restarting-from-a-step-f470e49c2b26
- score: 0.98

How to use it:

When debugging a Workflow instance, restart it from a specific step with `npx wrangler workflows instances restart <NAME> <ID> --from-step-name <STEP>`. Add `--from-step-count` or `--from-step-type` to disambiguate; add `--local` for a local dev session.

Examples:

```
npx wrangler workflows instances restart <NAME> <ID> --from-step-name <STEP>
```

```
npx wrangler workflows instances restart <NAME> <ID> --from-step-name <STEP> --local
```

```
npx wrangler workflows instances restart <NAME> <ID> --from-step-name <STEP> --from-step-count <COUNT> --from-step-type <TYPE>
```

- why_it_matters: When debugging a Workflow instance, restart it from a specific step in a remote instance or local `wrangler dev --local` session.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.97.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>
- gotchas: "Version: 4.97.0"; "<NAME> (required): Workflow name."; "<ID> (required): Instance ID; `latest` selects the latest instance."; "--from-step-name <string>: Name of the step to restart from."; "--from-step-count <number>: 1-based occurrence of the step name/type; defaults to 1."; "--from-step-type <string>: Disambiguates a name shared across step types; defaults to `do`."; "--local: Targets a Workflow in a local `wrangler dev` session."; "--port <number>: Local dev session port; defaults to 8787."; "Prerequisite: The `wrangler workflows` command requires Wrangler 3.83.0 or later."; "Prerequisite: The `--local` flag requires Wrangler 4.79.0 or later."; "Available for remote Workflow instances and local `wrangler dev --local` sessions."

### wrangler containers images delete confirmation (2026-06-01)
- slug: wrangler-containers-images-delete-confirmation-75f989c81664
- score: 0.96

How to use it:

When deleting a container image, run `wrangler containers images delete <IMAGE>:<TAG>` and confirm the prompt. For a non-interactive or scripted run, add `--skip-confirmation` (alias `-y`).

Examples:

```
wrangler containers images delete <IMAGE>:<TAG>
```

```
wrangler containers images delete <IMAGE>:<TAG> --skip-confirmation
```

- why_it_matters: Delete a container image by tag through the Wrangler CLI in an interactive session or script.
- before: The command deleted the image immediately without confirmation.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.96.0>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.96.0>, <https://developers.cloudflare.com/containers/reference/wrangler-commands/>
- gotchas: "Version: 4.96.0"; "IMAGE (required): Image to delete, in `IMAGE:TAG` form."; "--skip-confirmation` / `-y: Skip the confirmation prompt."; "The prompt can be bypassed with `-y` or `--skip-confirmation` in non-interactive or scripted environments."

### wrangler web_search binding and ad hoc CLI search (2026-06-01)
- slug: wrangler-web-search-binding-and-ad-hoc-cli-search-e0cae688c0b4
- score: 0.98

How to use it:

When adding web discovery to a Worker, declare the `web_search` binding and call its `search()` method; use global `fetch()` with a result URL to read content. For a one-off query, run the Wrangler `websearch search` command with optional `--limit` or `--json`.

Examples:

```
{"web_search": {"binding": "WEBSEARCH"}}
```

```
npx wrangler websearch search "cloudflare workers" --limit 5
```

```
npx wrangler websearch search "cloudflare workers" --json
```

- why_it_matters: Add web discovery to a Worker or run a one-off search while developing it.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.96.0>
- gotchas: "Version: 4.96.0"; "web_search.binding (required): Binding variable name available to Worker code; the example uses `WEBSEARCH`."; "search() query (required): Query searched by the binding; returns URLs and catalog metadata."; "--limit <number>: Maximum results; defaults to 10 and is capped at 20."; "--json: Print the raw response instead of a pretty table."; "Prerequisite: Wrangler login adds the `websearch.run` OAuth scope."; "Prerequisite: The binding connects remotely during local development through Miniflare’s remote-bindings transport."; "The shared corpus is singular; no namespace, instance, or other field is specified, only the variable name."; "The binding is always remote in local development: Miniflare proxies to the production Web Search service via remote-bindings transport."; "Web Search is discovery-only; invoke global `fetch()` against a result’s `url` to read its content."; "`--limit` defaults to 10 and is capped at 20."; "Docs conflict: The current Cloudflare Web Search docs describe calling `env.AI.websearch()` with an AI binding; that API differs from the Wrangler 4.96.0 `web_search` binding described in the release note. https://developers.cloudflare.com/web-search/how-to-use/"

### wrangler AI coding agent skills installation (2026-05-22)
- slug: wrangler-ai-coding-agent-skills-installation-a6e7d8ee6ecf
- score: 0.94

How to use it:

When using Wrangler with a detected AI coding agent, run the Wrangler command with `--install-skills` to install Cloudflare skills without prompting.

Examples:

```
npx wrangler <command> --install-skills
```

- why_it_matters: When using Wrangler with an AI coding agent, install the Cloudflare skill files for the agent.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.94.0>, <https://developers.cloudflare.com/workers/wrangler/commands/>
- gotchas: "Version: 4.94.0"; "--install-skills: Boolean flag; defaults to false. Installs Cloudflare skills for detected AI coding agents before running the command."; "Automatic detection and prompting are described for AI coding agents."; "The prompt is shown once interactively; subsequent runs skip it."

### wrangler ai models list queries the model catalog (2026-05-19)
- slug: wrangler-ai-models-list-queries-the-model-catalog-8e0e8b3ee1ea
- score: 0.98

How to use it:

When locating a Workers AI model for repository work, query the public model catalog with `wrangler ai models list` and add any relevant filters.

Examples:

```
wrangler ai models list
```

```
wrangler ai models list --search <search-term> --task <task> --author <author> --source <source> --hide-experimental
```

- why_it_matters: When locating a Workers AI model for repository work, query the public model catalog with relevant filters.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.93.0>
- gotchas: "Version: 4.93.0"; "--search <search-term>: Filter the model catalog by search term."; "--task <task>: Filter the model catalog by task."; "--author <author>: Filter the model catalog by author."; "--source <source>: Filter the model catalog by source."; "--hide-experimental: Hide experimental models."; "Prerequisite: Wrangler 4.93.0 or later for this command, per the release introducing it."; "The command matches the public model catalog search endpoint."

### wrangler ai models schema fetches model schemas (2026-05-19)
- slug: wrangler-ai-models-schema-fetches-model-schemas-72b14cb4ca72
- score: 0.98

How to use it:

When inspecting a Workers AI model’s input and output contract, run `wrangler ai models schema <model>` to fetch its schema from the public model catalog.

Examples:

```
wrangler ai models schema <model>
```

- why_it_matters: When inspecting a Workers AI model’s input and output contract, fetch its schema from the public model catalog.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.93.0>, <https://developers.cloudflare.com/api/resources/ai/subresources/models/subresources/schema/methods/get/>
- gotchas: "Version: 4.93.0"; "model (required): Workers AI model identifier; the API docs describe identifiers as including the namespace and model name."

### wrangler deploy can skip container rollout (2026-05-19)
- slug: wrangler-deploy-can-skip-container-rollout-504b85355a54
- score: 0.97

How to use it:

When changing a Worker without updating its container, run `wrangler deploy --containers-rollout=none` to deploy Worker code only and leave container images and instances unchanged.

Examples:

```
npx wrangler deploy --containers-rollout=none
```

- why_it_matters: When changing a Worker without updating its container, deploy the Worker while skipping the container rollout.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.93.0>, <https://developers.cloudflare.com/containers/configuration/rollouts/>
- gotchas: "Version: 4.93.0"; "--containers-rollout=none: For `wrangler deploy`, leave container images and running instances unchanged; deploy Worker code only."; "Useful when the container is not going to be updated or Docker is not available locally, but the Worker still needs changes."

### Wrangler configuration enables the Workers HTTP cache (2026-05-07)
- slug: wrangler-configuration-enables-the-workers-http-cache-cae14dbfc27f
- score: 0.96

How to use it:

When enabling the Workers HTTP cache, set `cache.enabled` to `true` in Wrangler configuration. For preview deployments, set `previews.cache` to override the top-level cache setting; omit it to inherit that setting.

Examples:

```
{"cache":{"enabled":true}}
```

```
[cache]
enabled = true
```

```
[previews.cache]
enabled = true
```

- why_it_matters: Enable an HTTP cache in front of a Worker’s `fetch` handler for a deployment or preview.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.89.0>, <https://developers.cloudflare.com/workers/cache/configuration/>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.89.0>
- gotchas: "Version: 4.89.0"; "cache.enabled (required): Boolean that turns caching on or off."; "previews.cache: Preview cache setting; overrides top-level `cache`, or inherits it when absent."; "Prerequisite: Wrangler 4.69.0 or above."; "The cache is an HTTP cache in front of the Worker's `fetch` handler."; "`previews.cache` overrides the top-level `cache` setting for preview deployments and falls back to the top-level value when absent."; "Docs conflict: The current configuration docs, updated October 3, 2026, say caching applies to every `fetch()` invocation. The v4.89.0 release note describes it as a cache in front of the Worker’s `fetch` handler; current docs postdate that release."

### wrangler ai-search create accepts custom metadata schemas (2026-05-05)
- slug: wrangler-ai-search-create-accepts-custom-metadata-schemas-7dc7270e5304
- score: 0.94

How to use it:

When creating an AI Search instance with custom metadata fields to index, run `wrangler ai-search create` with repeatable `--custom-metadata` flags or a JSON schema file via `--custom-metadata-schema`.

Examples:

```
wrangler ai-search create <NAME> --type r2 --source <BUCKET> --custom-metadata <FIELD>:<TYPE> --custom-metadata <FIELD>:<TYPE>
```

```
wrangler ai-search create <NAME> --type r2 --source <BUCKET> --custom-metadata-schema <SCHEMA.json>
```

- why_it_matters: Create an AI Search instance with metadata fields that it should index.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.88.0>, <https://developers.cloudflare.com/ai-search/wrangler-commands/>, <https://developers.cloudflare.com/ai-search/get-started/wrangler/>
- gotchas: "Version: 4.88.0"; "<NAME> (required): Unique AI Search instance name within its namespace."; "--type: Source type for the instance; use `r2` for an R2 bucket."; "--source: Data source identifier, such as an R2 bucket name."; "--custom-metadata: Repeatable field in `field_name:data_type` form; types: `text`, `number`, `boolean`, `datetime`. Mutually exclusive with `--custom-metadata-schema`."; "--custom-metadata-schema: Path to a JSON file containing an array of `{ \"field_name\", \"data_type\" }` objects. Mutually exclusive with `--custom-metadata`."; "Prerequisite: Install Wrangler before using its CLI; Cloudflare's AI Search CLI guide gives `npm install wrangler` as an installation command."; "Supported data types are `text`, `number`, `boolean`, and `datetime`."; "The JSON file must contain an array of `{ field_name, data_type }` objects."

### wrangler ai-search create supports builtin storage (2026-05-05)
- slug: wrangler-ai-search-create-supports-builtin-storage-8584c2dfbd81
- score: 0.97

How to use it:

To create an AI Search instance for Cloudflare-managed storage, run `npx wrangler ai-search create <name> --type builtin`; leave out `--source`, `--prefix`, `--include-items`, and `--exclude-items`.

Examples:

```
npx wrangler ai-search create <name> --type builtin
```

- why_it_matters: Create an AI Search instance that uses Cloudflare-managed storage.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.88.0>, <https://developers.cloudflare.com/ai-search/how-to/add-search-to-your-website/>, <https://developers.cloudflare.com/ai-search/wrangler-commands/>, <https://developers.cloudflare.com/ai-search/get-started/wrangler/>
- gotchas: "Version: 4.88.0"; "<name> (required): AI Search instance name; must be unique within its namespace."; "--type builtin: Select the source type for the instance; the guide uses `builtin` to create an instance without a data source."; "Prerequisite: Wrangler must be installed; the guide shows `npm install wrangler`."; "Builtin storage is created by omitting `type` and `source` from the API request."; "Builtin instances do not accept `--source`, `--prefix`, `--include-items`, or `--exclude-items`."

### wrangler exposes experimental experimental_generateTypes() API (2026-04-30)
- slug: wrangler-exposes-experimental-experimental-generatetypes-api-2581a66d0b2d
- score: 0.92

How to use it:

When code needs Worker types from Wrangler’s generation logic, import `experimental_generateTypes` from `wrangler` and await it with an optional options object. Use its `env` and `runtime` strings or combined `content`; the API does not write the output to disk automatically.

Examples:

```
import { experimental_generateTypes } from "wrangler";

const result = await experimental_generateTypes({
  config: "<wrangler-config>",
  includeRuntime: true,
  includeEnv: true,
});

// Use result.env, result.runtime, or result.content.
```

- why_it_matters: Generate Worker types programmatically in code using Wrangler's type-generation logic.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.87.0>, <https://developers.cloudflare.com/workers/wrangler/api/>
- gotchas: "Version: 4.87.0"; "Availability: experimental"; "options: Optional options object mirroring core `wrangler types` options."; "config: Wrangler config path; accepts a string or array for multi-config type resolution."; "env: Wrangler environment name for type generation."; "includeEnv: Include environment and bindings types; defaults to `true`."; "includeRuntime: Include runtime types; defaults to `true`."; "envInterface: Name the generated environment interface; defaults to `Env`."; "envFile: Paths to `.env` files used to infer local variables and secrets."; "path: Target declaration file path; defaults to `worker-configuration.d.ts`."; "strictVars: Generate strict literal and union types for variables; defaults to `true`."; "Supports the same core type-generation options as `wrangler types`, including env/runtime toggles."

### wrangler ai-search commands target namespaces (2026-04-28)
- slug: wrangler-ai-search-commands-target-namespaces-e7949eeba2f1
- score: 0.98

How to use it:

When targeting a non-default AI Search namespace, pass `--namespace <NAMESPACE>` (or `-n`); omission uses `default`. Use `wrangler ai-search namespace` subcommands to manage namespaces directly.

Examples:

```
npx wrangler ai-search list --namespace <NAMESPACE>
```

```
npx wrangler ai-search create <NAME> --namespace <NAMESPACE> --type <TYPE> --source <SOURCE>
```

```
npx wrangler ai-search namespace create <NAME> --description "<DESCRIPTION>"
```

- why_it_matters: Manage an AI Search instance in a specific namespace or manage namespaces directly.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.86.0>, <https://developers.cloudflare.com/ai-search/wrangler-commands/>, <https://developers.cloudflare.com/ai-search/get-started/wrangler/>
- gotchas: "Version: 4.86.0"; "<NAME> (required): Instance name for instance commands; namespace name for namespace commands."; "--namespace <NAMESPACE> / -n <NAMESPACE>: Selects the instance namespace; defaults to `default`."; "--type <TYPE>: Sets the AI Search instance source type."; "--source <SOURCE>: Sets the data source identifier, such as an R2 bucket name or web URL."; "--description <DESCRIPTION>: Sets an optional namespace description (maximum 256 characters)."; "Prerequisite: Install Wrangler to use its CLI commands; the docs do not specify a minimum version for these commands."; "Namespace picker is offered only when `--namespace` is not supplied in an interactive session."; "Docs conflict: The official Cloudflare changelog dated June 10, 2026 describes namespace-level Wrangler commands as newly supported, later than the card's Wrangler 4.86.0 release note. The current command reference documents those commands but does not resolve the version discrepancy."

### wrangler dev exposes local server with --tunnel (2026-04-28)
- slug: wrangler-dev-exposes-local-server-with-tunnel-d8855bc92ac8
- score: 0.98

How to use it:

When sharing a local Wrangler dev server without a Cloudflare account or configuration, run `wrangler dev --tunnel` to start a Quick Tunnel and get a random `*.trycloudflare.com` URL. The tunnel ends with the dev session.

Examples:

```
wrangler dev --tunnel
```

- why_it_matters: Share a local Wrangler development server publicly when you have no Cloudflare account or configuration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.86.0>, <https://github.com/cloudflare/workers-sdk/blob/wrangler%404.86.0/packages/wrangler/src/dev.ts>
- gotchas: "Version: 4.86.0"; "--tunnel (required): Boolean flag; exposes the local dev server via a Cloudflare Quick Tunnel. Required to enable the tunnel."; "Prerequisite: Quick Tunnels require no Cloudflare account or configuration."; "Prerequisite: `--tunnel` is supported only in local mode; it cannot be combined with `--remote`."; "Quick tunnels require no Cloudflare account or configuration."; "Quick tunnels do not support Server-Sent Events (SSE); a warning is shown when SSE responses are detected through the tunnel."; "The tunnel stops automatically when the dev session ends."; "Docs conflict: Later Cloudflare docs also describe pressing [t] to open or close a tunnel during a running dev session and support for named tunnels; those options are not in the Wrangler 4.86.0 source."

### wrangler browser manages Browser Rendering sessions (2026-04-13)
- slug: wrangler-browser-manages-browser-rendering-sessions-b58f5dd43a04
- score: 0.98

How to use it:

When your workflow needs a Browser Rendering DevTools session, use `wrangler browser create`, `close`, `list`, or `view` with the options below. Use `--json` for programmatic output; use `--no-open` to print the DevTools URL without opening it.

Examples:

```
wrangler browser create [--lab] [--keepAlive <seconds>] [--open] [--json]
```

```
wrangler browser close <sessionId> [--json]
```

```
wrangler browser list [--json]
```

- why_it_matters: Create, inspect, list, or close Browser Rendering DevTools sessions from a development workflow or script.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.82.0>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.82.0>, <https://developers.cloudflare.com/workers/wrangler/commands/browser/>, <https://developers.cloudflare.com/changelog/post/2026-04-14-browser-wrangler-commands/>
- gotchas: "Version: 4.82.0"; "`<sessionId>` (required): Session to close."; "`[sessionId]`: Session to view; optional when only one session exists. `view` prompts when multiple sessions are available."; "`--lab`: Enable a lab browser session."; "`--keepAlive <seconds>`: Set session keep-alive duration; the 4.82.0 changelog documents an example of 300 seconds."; "`--open` / `--no-open`: Control whether DevTools opens in a browser; `--no-open` prints the DevTools URL. Default is true interactively and false in CI/scripts."; "`--target <selector>`: Select a target for `view`."; "`--json`: Return programmatic JSON output."; "Prerequisite: `wrangler login` adds the `browser:write` OAuth scope."; "Prerequisite: The Cloudflare changelog says Wrangler handles authentication, so API tokens need not be passed in the commands."; "The default for `--open` is true in interactive mode and false in CI/scripts."; "When multiple sessions exist, `view` prompts for selection."; "Docs conflict: The current Wrangler command docs describe Browser Run and omit `--no-open`; they also document `--keepAlive` as 60–600 seconds. These docs were last updated after Wrangler 4.82.0, so those details are not applied here: https://developers.cloudflare.com/workers/wrangler/commands/browser/"

### wrangler.json configures Flagship feature flag bindings (2026-04-13)
- slug: wrangler-json-configures-flagship-feature-flag-bindings-146f3a876f62
- score: 0.94

How to use it:

When a Worker needs Flagship evaluations, add a `flagship` binding with its app ID to `wrangler.json`; set `remote` to `true` for live-service evaluation during local development. [Flagship configuration](https://developers.cloudflare.com/flagship/configuration/)

Examples:

```
{"flagship":[{"binding":"FLAGS","app_id":"<APP_ID>"}]}
```

```
{"flagship":[{"binding":"FLAGS","app_id":"<APP_ID>","remote":true}]}
```

- why_it_matters: Configure a Worker to evaluate Cloudflare Flagship feature flags during local development or against the live service.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.82.0>, <https://developers.cloudflare.com/flagship/configuration/>
- gotchas: "Version: 4.82.0"; "binding (required): Name of the Worker environment variable used to access Flagship, such as `env.FLAGS`."; "app_id (required): ID of the Flagship app to bind."; "remote: Set to `true` for live-service evaluation during local development, per the Wrangler 4.82.0 release note."; "Prerequisite: Use the app ID from a Flagship app."; "Local development returns default values for all flag evaluations unless the binding uses `\"remote\": true`."; "Docs conflict: Newer Flagship configuration docs (updated June 24, 2026) say local Workers use the live Flagship app configured by `app_id` and that there is no local flag store; they do not describe `remote` for Flagship. The Wrangler 4.82.0 release note says local evaluations return defaults unless `remote: true`. Do not infer current `remote` behavior from the newer docs."

### wrangler email routing and sending commands (2026-04-07)
- slug: wrangler-email-routing-and-sending-commands-e47387f11db3
- score: 0.98

How to use it:

If you need to inspect or change a zone’s email routing or sending, use `wrangler email routing` or `wrangler email sending` with the zone domain. For routing or sending setup, enable the feature; for sending, use `send` for builder-style email or `send-raw` for MIME.

Examples:

```
wrangler email routing settings <domain>
```

```
wrangler email routing enable <domain>
```

```
wrangler email sending enable <domain>
```

- why_it_matters: Configure or inspect email routing and sending for a zone from the command line.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.81.0>, <https://github.com/cloudflare/skills/blob/main/skills/cloudflare-email-service/references/cli-and-mcp.md>
- gotchas: "Version: 4.81.0"; "<domain> (required): Zone domain to inspect or enable; for sending, the release note says this may be a zone or subdomain."; "email_routing:write (required): OAuth scope added for Wrangler email routing commands."; "email_sending:write (required): OAuth scope added for Wrangler email sending commands."; "Prerequisite: Wrangler 4.81.0 introduced these command groups."; "Prerequisite: Log in with `wrangler login` and grant `email_routing:write` and/or `email_sending:write` for the respective commands."

### wrangler dev supports experimental headful browser rendering (2026-04-02)
- slug: wrangler-dev-supports-experimental-headful-browser-rendering-604eedae65d4
- score: 0.92

How to use it:

When debugging local development with the Browser Rendering API, set `X_BROWSER_HEADFUL=true` before starting `wrangler dev` or `vite dev` to show Chrome. This is experimental; with `@cloudflare/playwright`, two Chrome windows may appear because of browser contexts via CDP.

Examples:

```
X_BROWSER_HEADFUL=true wrangler dev
```

```
X_BROWSER_HEADFUL=true vite dev
```

- why_it_matters: Debug local development that uses the Browser Rendering API by viewing its browser window.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.80.0>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.80.0>, <https://developers.cloudflare.com/browser-run/faq/>
- gotchas: "Version: 4.80.0"; "Availability: Experimental; may be removed or changed without notice."; "X_BROWSER_HEADFUL=true (required): Environment variable that enables visible (headful) browser mode during local development."; "wrangler dev / vite dev (required): Start the local development server with the environment variable set before the command."; "Prerequisite: Use for local development with the Browser Rendering API; the feature is experimental and may change or be removed."; "When using `@cloudflare/playwright`, two Chrome windows may appear: an initial blank page and the page created by `browser.newPage()`. This is expected behavior due to how Playwright handles browser contexts via CDP."

### wrangler types generates AI Search binding types (2026-04-02)
- slug: wrangler-types-generates-ai-search-binding-types-05a9b9a8a4c3
- score: 0.95

How to use it:

When a Worker repository needs environment types for AI Search bindings, add `ai_search_namespaces` and/or `ai_search` to its Wrangler config, then run `wrangler types` to generate binding types. By default, Wrangler includes bindings from all configured environments.

Examples:

```
wrangler types
```

```
{"ai_search_namespaces":[{"binding":"<ENV_BINDING>","namespace":"<NAMESPACE>"}],"ai_search":[{"binding":"<ENV_BINDING>","instance_name":"<INSTANCE_NAME>"}]}
```

- why_it_matters: Generate Worker environment types for `ai_search_namespaces` and `ai_search` bindings in a repository.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.80.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://developers.cloudflare.com/ai-search/api/search/workers-binding/>
- gotchas: "Version: 4.80.0"; "PATH: Optional output path for generated types; defaults to `./worker-configuration.d.ts` and must end in `.d.ts`."; "--env: Restricts generated bindings to the named environment; without it, bindings from all configured environments are included."; "ai_search_namespaces[].binding (required): Environment variable name for the namespace binding."; "ai_search_namespaces[].namespace (required): Namespace to bind; Wrangler creates it on deploy if it does not exist."; "ai_search_namespaces[].remote: Set to `true` for local development with `wrangler dev`."; "ai_search[].binding (required): Environment variable name for the instance binding."; "ai_search[].instance_name (required): AI Search instance name; it must exist in the default namespace at deploy time."; "ai_search[].remote: Set to `true` for local development with `wrangler dev`."; "Supports both simple and per-environment modes."

### wrangler workflows commands target local dev with --local (2026-03-31)
- slug: wrangler-workflows-commands-target-local-dev-with-local-9411baa6a9bb
- score: 0.97

How to use it:

When developing locally, pass `--local` to a `wrangler workflows` command to target a Workflow in a running `wrangler dev` session. Add `--port <port>` when the session uses a custom port; the default is `8787`.

Examples:

```
wrangler workflows list --local
```

```
wrangler workflows trigger <NAME> '{"key":"value"}' --local
```

```
wrangler workflows instances pause <NAME> <ID> --local --port 9000
```

- why_it_matters: During local development, inspect or operate a Workflow against a running Wrangler dev session.
- before: Without `--local`, Workflows commands target production.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.79.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workflows/>
- gotchas: "Version: 4.79.0"; "--local: Interact with a Workflow in a local `wrangler dev` session; the docs say this requires Wrangler 4.79.0 or greater."; "--port <port>: Port of the local dev session; defaults to `8787`."; "<NAME> (required): Workflow name."; "[PARAMS]: JSON string passed as parameters to the Workflow instance."; "<ID> (required): Workflow instance ID to pause."; "Prerequisite: The `--local` flag requires Wrangler 4.79.0 or greater."; "Prerequisite: A running `wrangler dev` session is required for local targeting."; "The local target is a running `wrangler dev` session."; "Commands continue to target remote production by default."; "The default dev server port is 8787."

### wrangler dev supports local Cloudflare Stream bindings (2026-03-27)
- slug: wrangler-dev-supports-local-cloudflare-stream-bindings-ef5d6007c159
- score: 0.98

How to use it:

When developing or testing a Worker that uses Stream, bind Stream in Wrangler and run `npx wrangler dev`. Use the listed local operations; avoid direct uploads and `File`-based caption uploads or watermark generation, which throw locally.

Examples:

```
{"stream":{"binding":"STREAM"}}
```

```
npx wrangler dev
```

- why_it_matters: Develop or test Worker code locally that uses Cloudflare Stream bindings.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.78.0>, <https://developers.cloudflare.com/stream/manage-video-library/bindings/>, <https://developers.cloudflare.com/changelog/post/2026-05-07-stream-workers-binding/>
- gotchas: "Version: 4.78.0"; "stream.binding (required): Binding name exposed to Worker code, for example `env.STREAM`."; "streamPersist: Set to `false` in Miniflare options to disable Stream data persistence across restarts; persistence is on by default."; "Prerequisite: Use Wrangler 4.78.0 or later for the local Stream binding support introduced in 4.78.0."; "Prerequisite: Add the Stream binding to the Worker’s Wrangler configuration."; "Supported local operations: `upload()` (upload video via URL); `video(id).details()`, `.update()`, `.delete()`, `.generateToken()`; `videos.list()`; `captions.generate()`, `.list()`, `.delete()`; `downloads.generate()`, `.get()`, `.delete()`; and `watermarks.generate()`, `.list()`, `.get()`, `.delete()`."; "`createDirectUpload()`, caption upload via `File`, and watermark generation via `File` are not supported in local mode and will throw."; "Data persists across restarts by default. Set `streamPersist: false` in Miniflare options to disable persistence."

### wrangler vpc service create accepts --type tcp (2026-03-27)
- slug: wrangler-vpc-service-create-accepts-type-tcp-6645f75af912
- score: 0.93

How to use it:

When exposing a TCP database through Workers VPC, create a TCP service with its port, private IPv4 address, and tunnel ID.

Examples:

```
npx wrangler vpc service create my-db --type tcp --tcp-port 5432 --ipv4 10.0.0.1 --tunnel-id <tunnel-uuid>
```

- why_it_matters: Expose a TCP database service, such as PostgreSQL or MySQL, through Workers VPC.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.78.0>, <https://developers.cloudflare.com/workers-vpc/get-started/>, <https://developers.cloudflare.com/workers/wrangler/commands/vpc/>, <https://developers.cloudflare.com/workers-vpc/configuration/vpc-services/>
- gotchas: "Version: 4.78.0"; "<NAME> (required): Name of the VPC service."; "--type (required): VPC service type; use `tcp`."; "--tcp-port: TCP port number; provide the database service port."; "--ipv4: IPv4 address for the host; conflicts with `--ipv6`."; "--ipv6: IPv6 address for the host; conflicts with `--ipv4`."; "--tunnel-id (required): UUID of the Cloudflare tunnel."; "Prerequisite: Have a running tunnel that can reach the database host and port."; "Prerequisite: Wrangler authentication must have the `Connectivity Directory Admin` role to create VPC services."; "The service port, IPv4 address, and tunnel ID are needed in the example workflow."

### wrangler containers instances lists application instances (2026-03-16)
- slug: wrangler-containers-instances-lists-application-instances-d0d09240da3b
- score: 0.95

How to use it:

When inspecting an application’s container instances, run `wrangler containers instances <APPLICATION_ID>`; use `wrangler containers list` to find the UUID if needed. Interactive output paginates with Enter; piping or CI fetches all pages automatically.

Examples:

```
wrangler containers instances <APPLICATION_ID>
```

```
wrangler containers instances <APPLICATION_ID> --per-page <COUNT>
```

```
wrangler containers instances <APPLICATION_ID> --json
```

- why_it_matters: Inspect the container instances for an application during development or debugging.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.74.0>, <https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/partials/workers/wrangler-commands/containers.mdx>
- gotchas: "Version: 4.74.0"; "APPLICATION_ID (required): UUID of the application. Use `wrangler containers list` to find application IDs."; "--per-page <COUNT>: Instances per page; default 25."; "--json: Return clean JSON; default false in interactive mode and true in non-interactive environments."; "The command lists instances for a given application."; "Pagination is supported for applications with many instances."

### wrangler deploy and versions upload accept --secrets-file (2026-03-16)
- slug: wrangler-deploy-and-versions-upload-accept-secrets-file-911064e5fc18
- score: 0.97

How to use it:

When deploying Worker code with secrets from a file, pass `--secrets-file <FILE>` to `wrangler deploy` or `wrangler versions upload`. The file can be JSON or `.env`; secrets it omits are preserved from the previous version.

Examples:

```
npx wrangler deploy --secrets-file <PATH_TO_JSON_OR_ENV_FILE>
```

```
npx wrangler versions upload --secrets-file <PATH_TO_JSON_OR_ENV_FILE>
```

- why_it_matters: Deploy Worker code with secrets from a JSON or .env file in one operation.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.74.0>, <https://developers.cloudflare.com/workers/configuration/secrets/>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.74.0"; "--secrets-file <string>: Path to a JSON or `.env` file containing secrets to upload alongside the deployment; secrets omitted from the file are preserved from the previous version."; "The file format matches `wrangler versions secret bulk` and supports JSON and .env formats."; "Secrets not included in the file are inherited from the previous version."

### wrangler test helpers can disable persistence (2026-03-13)
- slug: wrangler-test-helpers-can-disable-persistence-775c1392d6a8
- score: 0.95

How to use it:

When tests need clean state on each run, set `persist: false` in `unstable_dev()` options or in the `dev` options passed to `unstable_startWorker()`.

Examples:

```
const worker = await unstable_dev("./src/worker.ts", { persist: false });
```

```
const worker = await unstable_startWorker({ entrypoint: "./src/worker.ts", dev: { persist: false } });
```

- why_it_matters: Run a Worker in tests that need a clean state on every run.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.73.0>, <https://github.com/cloudflare/workers-sdk/blob/wrangler@4.73.0/packages/wrangler/src/api/dev.ts>, <https://developers.cloudflare.com/workers/wrangler/api/>
- gotchas: "Version: 4.73.0"; "unstable_dev(script, options) — `script` (required): Worker script path, relative to the project root."; "unstable_dev options — `persist`: Set to `false` to prevent binding data from being read from or written to the filesystem."; "unstable_startWorker options — `entrypoint` (required): Worker entrypoint path, as shown in the v4.73.0 release example."; "unstable_startWorker options — `dev.persist`: Set to `false` in the `dev` options to disable persistence."; "Docs conflict: Current Wrangler API docs mark both unstable APIs as deprecated and recommend `createTestHarness()`; that is newer-version guidance and does not change the v4.73.0 release-note examples."

### wrangler containers configure DockerHub credentials and reference DockerHub images (2026-03-03)
- slug: wrangler-containers-configure-dockerhub-credentials-and-reference-dockerhub-imag-a49fabc84e56
- score: 0.97

How to use it:

For a private Docker Hub image, configure credentials for `docker.io` with a read-only Docker Hub personal access token, then set the container `image` to its fully qualified Docker Hub reference. Local development with a private image also requires authenticating to the registry locally.

Examples:

```
printf '%s' "$DOCKERHUB_PAT" | npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME> --secret-name=<SECRET_NAME> --skip-confirmation
```

```
{"containers":[{"image":"docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"}]}
```

- why_it_matters: Configure a Worker container to use a private DockerHub image during development or deployment.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.70.0>, <https://developers.cloudflare.com/containers/guides/image-management/>, <https://developers.cloudflare.com/workers/wrangler/commands/containers/>
- gotchas: "Version: 4.70.0"; "DOMAIN (`docker.io`) (required): Registry domain to configure."; "--dockerhub-username: Docker Hub username; use with `docker.io`. The secret is a Docker Hub personal access token."; "--secret-name: Name Wrangler stores the registry credentials under."; "--skip-confirmation: Use for non-interactive runs."; "--secret-store-id: ID of the Secrets Store to use for registry credentials."; "Credential flags: `--dockerhub-username`, `--aws-access-key-id`, and `--gar-email` are mutually exclusive; use the flag matching the registry."; "containers[].image (required): For this task, set it to `docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>`."; "Prerequisite: Use a Docker Hub personal access token with read-only access for the private image."; "Prerequisite: Wrangler stores the secret in Secrets Store; if no Secrets Store exists, Wrangler prompts to create one."; "Prerequisite: For a private Docker Hub image in local development, authenticate to the registry locally, for example with `docker login`."; "Docs conflict: Current docs say the `containers` configuration is an array (`containers: [{\"image\": ...}]`), while the release note example shows an object. Used the documented current configuration shape. Current docs scope direct external registry references and configured credentials to the `default` scheduling policy; `durable_object` requires pushing the image to Cloudflare's managed registry."

### wrangler containers registries credentials generates temporary registry credentials (2026-03-03)
- slug: wrangler-containers-registries-credentials-generates-temporary-registry-credenti-5ba0bb0dfc7d
- score: 0.97

How to use it:

When a CI or local Docker workflow needs Cloudflare managed registry access, run the credentials command with `--push`, `--pull`, or both; credentials default to 15 minutes, configurable with `--expiration-minutes`.

Examples:

```
wrangler containers registries credentials registry.cloudflare.com --push
```

```
wrangler containers registries credentials registry.cloudflare.com --pull
```

```
wrangler containers registries credentials registry.cloudflare.com --push --pull --expiration-minutes=30
```

- why_it_matters: Authenticate Docker in a CI/CD pipeline or local development workflow to push or pull container images from Cloudflare's managed registry.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.70.0>, <https://developers.cloudflare.com/workers/wrangler/commands/containers/>
- gotchas: "Version: 4.70.0"; "registry.cloudflare.com (required): Registry host targeted by the release-note invocations."; "--push: Generate credentials with push permission."; "--pull: Generate credentials with pull permission."; "--expiration-minutes: Credential validity in minutes; documented default is 15."; "Credentials are short-lived."; "The default expiration is 15 minutes."; "Docs conflict: Current Wrangler command docs (updated Apr 23, 2026, after v4.70.0) show `wrangler containers registries credentials [OPTIONS]` without a registry positional argument, while the v4.70.0 release note examples include `registry.cloudflare.com`. The current docs do not clarify whether the positional argument was removed or is optional."

### wrangler types generates bindings from required secrets (2026-03-03)
- slug: wrangler-types-generates-bindings-from-required-secrets-d6021edaf7f7
- score: 0.91

How to use it:

When Wrangler configuration declares `secrets`, generate bindings from `secrets.required`. Add the required secret names, then run `wrangler types` (or `npx wrangler types`); named environments get separate interfaces, and the aggregate `Env` makes environment-specific secrets optional.

Examples:

```
{
  "secrets": {
    "required": ["API_KEY", "DB_PASSWORD"]
  }
}
```

```
npx wrangler types
```

- why_it_matters: Generate typed Worker bindings for a project whose required secrets are declared in Wrangler configuration.
- before: The release note says that without `secrets`, the existing behavior is unchanged; with it, Wrangler previously inferred secret names from `.dev.vars` or `.env`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.70.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/workers/wrangler/commands/#types>
- gotchas: "Version: 4.70.0"; "Availability: Experimental configuration property."; "secrets.required (required): Array of required secret names; when `secrets` is defined, these names are the source for generated secret bindings."; "PATH: Optional output path for generated types; defaults to `./worker-configuration.d.ts` and must end in `.d.ts`."; "Prerequisite: Define the `secrets` property in Wrangler configuration for this type-generation behavior."; "Prerequisite: Install or otherwise make Wrangler available to run the command; Cloudflare documents `npx wrangler types` as an invocation."; "The `secrets` property must be defined for this behavior."; "Per-environment secrets are supported."

### wrangler Workflows configures per-instance step limits (2026-03-03)
- slug: wrangler-workflows-configures-per-instance-step-limits-89879eff68c2
- score: 0.94

How to use it:

When a Workflow needs a per-instance step cap, set `workflows[].limits.steps` to an integer from 1 to 25,000; the default is 10,000. Run `wrangler dev` to enforce the configured limit locally.

Examples:

```
{
  "workflows": [{
    "name": "<workflow-name>",
    "binding": "<binding-name>",
    "class_name": "<class-name>",
    "limits": { "steps": 5000 }
  }]
}
```

- why_it_matters: Set a maximum step count for a Workflow instance and reproduce that limit in local development.
- before: Instances were limited to 1,024 steps.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.70.0>, <https://developers.cloudflare.com/changelog/post/2026-03-03-step-limits-to-25k/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>, <https://developers.cloudflare.com/workflows/build/workers-api/>
- gotchas: "Version: 4.70.0"; "workflows[].limits.steps: Maximum steps per Workflow instance; integer from 1 to 25,000. Defaults to 10,000 when omitted."; "workflows[].name (required): Workflow name."; "workflows[].binding (required): Binding name used to access the Workflow."; "workflows[].class_name (required): Workflow class name."; "Prerequisite: The configurable 10,000–25,000 step limit applies to Workflows on Workers Paid; Workers Free has a 1,024-step limit."; "The `steps` value must be an integer between 1 and 25,000."; "The default limit is 10,000 steps when not specified."; "Docs conflict: The current general Wrangler configuration page says limits are enforced only when deployed, while the Wrangler 4.70.0 release note specifically says Workflow step limits are enforced by `wrangler dev` locally. https://developers.cloudflare.com/workers/wrangler/configuration/"

### wrangler types generates typed pipeline bindings from stream schemas (2026-02-19)
- slug: wrangler-types-generates-typed-pipeline-bindings-from-stream-schemas-786054d797e0
- score: 0.96

How to use it:

When a configured pipeline stream has a schema and Wrangler is authenticated, run `wrangler types` to generate schema-based TypeScript binding types. Otherwise, pipeline bindings use `Pipeline<PipelineRecord>`.

Examples:

```
wrangler types
```

```
{"pipelines":[{"binding":"ANALYTICS","pipeline":"<pipeline-id>"}]}
```

- why_it_matters: Generate types for a Worker that sends data to a schema-defined pipeline.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.67.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.67.0>
- gotchas: "Version: 4.67.0"; "PATH: Optional output path for the generated types; defaults to `./worker-configuration.d.ts` and must end in `.d.ts`."; "Prerequisite: Use Wrangler 4.67.0 or later for the release-note behavior."; "Prerequisite: Authenticate with Cloudflare and configure the pipeline binding; unauthenticated runs fall back to `Pipeline<PipelineRecord>`."; "Stream schema fields determine the generated TypeScript types."; "Unstructured streams or runs without authentication use the generic `Pipeline<PipelineRecord>` type."

### wrangler deploy accepts --tag and --message (2026-02-17)
- slug: wrangler-deploy-accepts-tag-and-message-060ed57ffa7a
- score: 0.97

How to use it:

When deploying a Worker with a version tag and message, run `wrangler deploy --tag <tag> --message <message>`. The tag applies to the version; the message applies to both the version and deployment.

Examples:

```
npx wrangler deploy --tag <tag> --message "<message>"
```

- why_it_matters: Deploy a Worker version with a tag and message using Wrangler.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.66.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.66.0"; "--tag <string>: Sets a tag for this Worker version."; "--message <string>: Sets a descriptive message for the Worker version and deployment."

### wrangler kv namespace delete accepts a namespace name (2026-02-12)
- slug: wrangler-kv-namespace-delete-accepts-a-namespace-name-893a7da5590d
- score: 0.98

How to use it:

When deleting a KV namespace by name, run `wrangler kv namespace delete <NAMESPACE>` with the namespace name as the positional argument.

Examples:

```
npx wrangler kv namespace delete <NAMESPACE>
```

- why_it_matters: Delete a KV namespace by its name from a coding workflow.
- before: Delete the namespace using `--namespace-id` or `--binding`.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.65.0>, <https://developers.cloudflare.com/workers/wrangler/commands/kv/>
- gotchas: "Version: 4.65.0"; "[NAMESPACE]: Name of the namespace to delete."; "--binding <string>: Binding name for the namespace to delete."; "--namespace-id <string>: ID of the namespace to delete."; "--skip-confirmation: Skip confirmation; alias `--y`, default false."; "The existing `--namespace-id` and `--binding` flags continue to work as before."

### wrangler pages dev injects Pages environment variables (2026-02-12)
- slug: wrangler-pages-dev-injects-pages-environment-variables-3e223a67db5d
- score: 0.97

How to use it:

When running a Pages project locally, use `wrangler pages dev` and check the startup bindings table to verify the Pages environment, branch, and commit values.

Examples:

```
npx wrangler pages dev [<DIRECTORY>]
```

```
npx wrangler pages dev --binding=CF_PAGES_BRANCH=<branch>
```

- why_it_matters: Run a Pages project locally and verify that its framework detects the Pages environment and current branch or commit.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.65.0>, <https://developers.cloudflare.com/workers/wrangler/commands/pages/>, <https://developers.cloudflare.com/pages/functions/bindings/>, <https://github.com/cloudflare/workers-sdk/blob/b900c5adc18c12d500e0fb8c58c2295843518695/packages/wrangler/src/pages/dev.ts>
- gotchas: "Version: 4.65.0"; "[DIRECTORY]: Directory of static assets to serve."; "--binding=<KEY>=<VALUE>: Binds a variable or secret; use the Pages variable name and desired value to override it."; "CF_PAGES: Injected as `1` to indicate the Pages environment."; "CF_PAGES_BRANCH: Injected from the current Git branch, or `local` when Git branch detection is unavailable."; "CF_PAGES_COMMIT_SHA: Injected from the current Git commit SHA, or a zero SHA placeholder when Git commit detection is unavailable."; "CF_PAGES_URL: Injected as `https://<short-sha>.<project-name>.pages.dev`."; "`CF_PAGES_BRANCH` defaults to the current git branch, or `\"local\"` when not in a git repository."; "`CF_PAGES_COMMIT_SHA` defaults to the current git commit SHA, or a placeholder when not in a git repository."; "`CF_PAGES_URL` is a simulated commit preview URL."

### wrangler whoami adds machine-readable JSON output (2026-02-12)
- slug: wrangler-whoami-adds-machine-readable-json-output-183d61d712e4
- score: 0.98

How to use it:

When a shell script needs to check Wrangler authentication without parsing text, run `wrangler whoami --json` and branch on its exit status; unauthenticated runs exit non-zero and output `{"loggedIn":false}`.

Examples:

```
wrangler whoami --json
```

```
if wrangler whoami --json > /dev/null 2>&1; then
  echo "Authenticated"
else
  echo "Not authenticated"
fi
```

- why_it_matters: Check Wrangler authentication status in a shell script without parsing text output.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.65.0>, <https://developers.cloudflare.com/workers/wrangler/commands/general/>
- gotchas: "Version: 4.65.0"; "--json (required): Boolean flag; default false. Return user information as JSON. Exits non-zero if not authenticated."; "When the user is not authenticated, the command exits with a non-zero status code and outputs `{\"loggedIn\":false}`."

### wrangler custom build commands receive WRANGLER_COMMAND (2026-02-10)
- slug: wrangler-custom-build-commands-receive-wrangler-command-e3e6c955da77
- score: 0.93

How to use it:

When Wrangler runs a configured custom build command, branch on `WRANGLER_COMMAND` to select the build behavior for `dev`, `deploy`, `versions upload`, or `types`.

Examples:

```
[build]
command = "./build.sh"
```

```
if [ "$WRANGLER_COMMAND" = "dev" ]; then
  echo "Building for development..."
else
  echo "Building for production..."
fi
```

- why_it_matters: Branch a custom build script on whether Wrangler invoked it for development, deployment, versions upload, or types.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.64.0>, <https://developers.cloudflare.com/workers/wrangler/custom-builds/>
- gotchas: "Version: 4.64.0"; "build.command: Command used to build the Worker; it runs as part of Wrangler commands that trigger the custom build."; "WRANGLER_COMMAND: Environment variable set for the custom build; values documented are `dev`, `deploy`, `versions upload`, and `types`."; "Prerequisite: Configure a custom build command in the Wrangler configuration file."; "The variable applies when using a custom build command in `wrangler.toml`."

### wrangler pages deployment delete command (2026-02-10)
- slug: wrangler-pages-deployment-delete-command-2e7786fae32f
- score: 0.98

How to use it:

When deleting a Pages deployment, run the delete command with its deployment ID and project name; add `--force` (or `-f`) to skip confirmation in CI/CD.

Examples:

```
npx wrangler pages deployment delete <DEPLOYMENT-ID> --project-name <PROJECT-NAME>
```

```
npx wrangler pages deployment delete <DEPLOYMENT-ID> --project-name <PROJECT-NAME> --force
```

- why_it_matters: Delete a Pages deployment from a project, including from a CI/CD workflow when confirmation should be skipped.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.64.0>, <https://developers.cloudflare.com/pages/platform/known-issues/>, <https://developers.cloudflare.com/workers/wrangler/commands/pages/>
- gotchas: "Version: 4.64.0"; "<DEPLOYMENT-ID> (required): ID of the deployment to delete."; "--project-name <PROJECT-NAME>: Name of the project the deployment belongs to."; "--force / -f: Release note says it skips confirmation; current command docs say it deletes even if the deployment has an active alias. The docs do not say these effects are mutually exclusive."; "Docs conflict: Current docs additionally describe --force as allowing deletion of deployments with active aliases; this behavior is not stated in the Wrangler 4.64.0 release note."

### wrangler pages project list supports --json (2026-02-10)
- slug: wrangler-pages-project-list-supports-json-08fd6afea07e
- score: 0.98

How to use it:

To process Cloudflare Pages project listings as JSON, run `wrangler pages project list --json`.

Examples:

```
npx wrangler pages project list --json
```

- why_it_matters: Process Pages project listings in a script as JSON.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.64.0>, <https://developers.cloudflare.com/workers/wrangler/commands/pages/>
- gotchas: "Version: 4.64.0"; "--json: Boolean flag (default false); return output as JSON."

### Wrangler configuration supports the `subrequests` limit (2026-02-03)
- slug: wrangler-configuration-supports-the-subrequests-limit-e18c3f6d7b8b
- score: 0.94

How to use it:

When a Worker invocation needs a request-count cap, set `limits.subrequests` in its Wrangler config. `limits` and `subrequests` are optional; the limit applies at runtime on Cloudflare’s network, not in local development.

Examples:

```
{
  "limits": {
    "cpu_ms": 1000,
    "subrequests": 150
  }
}
```

- why_it_matters: Limit the number of fetch requests a Worker's invocation can make by configuring the Worker limits.
- before: Before this change, only `cpu_ms` was supported in Wrangler’s `limits` field.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.62.0>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.62.0"; "limits: Configures limits imposed on Worker execution at runtime."; "limits.subrequests: Maximum subrequests allowed per invocation."; "limits.cpu_ms: Maximum CPU time allowed per invocation, in milliseconds."; "Prerequisite: Limits are supported for the Standard Usage Model and are enforced only on Cloudflare’s network, not during local development."; "Docs conflict: The current configuration docs say the maximum is 50 for free accounts and 10,000,000 for paid accounts. The release-note example uses 150 without specifying a plan; the current docs’ free-account maximum conflicts with using 150 on a free account. https://developers.cloudflare.com/workers/wrangler/configuration/"

### wrangler r2 bucket local-uploads manages local uploads (2026-02-03)
- slug: wrangler-r2-bucket-local-uploads-manages-local-uploads-68838c9d74c8
- score: 0.95

How to use it:

When managing local uploads for an R2 bucket, run `npx wrangler r2 bucket local-uploads get <BUCKET_NAME>` to check status, `enable <BUCKET_NAME>` to enable with confirmation, `enable <BUCKET_NAME> --force` to skip confirmation, or `disable <BUCKET_NAME>` to turn it off. With local uploads enabled, data is written near the client and asynchronously replicated to the bucket.

Examples:

```
npx wrangler r2 bucket local-uploads get <BUCKET_NAME>
```

```
npx wrangler r2 bucket local-uploads enable <BUCKET_NAME> --force
```

```
npx wrangler r2 bucket local-uploads disable <BUCKET_NAME>
```

- why_it_matters: Enable or disable local uploads for an R2 bucket from the command line.
- before: Without local uploads, object data travels from the client to the bucket's storage infrastructure.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.62.0>, <https://developers.cloudflare.com/r2/buckets/local-uploads/>, <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.62.0>
- gotchas: "Version: 4.62.0"; "<BUCKET_NAME> (required): Name of the R2 bucket to manage."; "--force: Enable local uploads without a confirmation prompt."; "Enabling without `--force` prompts for confirmation."

### wrangler types --check verifies generated types (2026-01-13)
- slug: wrangler-types-check-verifies-generated-types-7660f8508501
- score: 0.98

How to use it:

When you need to verify generated Worker types in CI or a pre-commit hook, run `wrangler types --check`; it checks the configured output path without regenerating types and exits 0 when current or 1 when out of date. Use `wrangler types <path>.d.ts --check` to check a custom output path.

Examples:

```
wrangler types --check
```

```
wrangler types <path>.d.ts --check
```

- why_it_matters: In CI or a pre-commit hook, verify that the repository’s generated Worker types are current.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.59.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>
- gotchas: "Version: 4.59.0"; "PATH: Output path for Worker types; defaults to `./worker-configuration.d.ts` and must have a `.d.ts` extension."; "--check: Check whether types at the specified path are up to date without regenerating them; exits 0 if current or 1 if out of date."

### wrangler auth token retrieves configured credentials (2026-01-07)
- slug: wrangler-auth-token-retrieves-configured-credentials-5121d6f66092
- score: 0.96

How to use it:

When a script needs Wrangler’s configured credentials, run `wrangler auth token`; add `--json` for structured output with token type, including API key/email credentials.

Examples:

```
wrangler auth token
```

```
wrangler auth token --json
```

- why_it_matters: When a script needs Wrangler’s currently configured authentication credential, retrieve it for the integration.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.57.0>, <https://developers.cloudflare.com/workers/wrangler/commands/general/>
- gotchas: "Version: 4.57.0"; "--json: Returns JSON with token type; required to retrieve API key/email credentials."; "Prerequisite: An authentication method must be available: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_API_KEY` plus `CLOUDFLARE_EMAIL` (with `--json`), or an OAuth token from `wrangler login`."; "Returns whichever authentication method is currently configured."

### wrangler dev generates worker configuration types (2026-01-07)
- slug: wrangler-dev-generates-worker-configuration-types-a0569a8053e7
- score: 0.97

How to use it:

When starting a Worker’s local development server, enable automatic configuration type generation with `wrangler dev --types` or set `dev.generate_types` to `true` in Wrangler configuration.

Examples:

```
wrangler dev --types
```

```
{
  "dev": {
    "generate_types": true
  }
}
```

- why_it_matters: When starting local development for a Worker, generate its configuration types automatically.
- sources: <https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.57.0>, <https://developers.cloudflare.com/workers/wrangler/commands/workers/>, <https://developers.cloudflare.com/workers/wrangler/configuration/>
- gotchas: "Version: 4.57.0"; "--types: Boolean flag; generate types from Worker configuration. Defaults to false."; "dev.generate_types: Boolean configuration option; generate types from Worker configuration. Defaults to false."; "Types are generated when the local Wrangler development server starts."