{
  "tool": "wrangler",
  "name": "Wrangler",
  "long_name": "Cloudflare Wrangler CLI (wrangler)",
  "aliases": [
    "wrangler-cli",
    "cloudflare-wrangler",
    "cloudflare-wrangler-cli",
    "workers-cli"
  ],
  "homepage": "https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler",
  "url": "https://insidetheloop.dev/tools/wrangler",
  "markdown_url": "https://insidetheloop.dev/tools/wrangler.md",
  "date_modified": "2026-10-07T12:39:57Z",
  "title": "Cloudflare Wrangler 4.148.0: latest version, changes and gotchas",
  "description": "Wrangler 4.148.0 (2026-10-06 UTC): upgrade command, last five releases, our --help diff, breaking config changes and errors we reproduced.",
  "answer": "The latest Cloudflare Wrangler is 4.148.0, published to npm on 2026-10-06 18:33 UTC. Upgrade inside your project with `npm i -D wrangler@latest`. Compared with 4.147.0 it adds four flags (`wrangler dev --tunnel-allowed-mail`, `kv namespace create --experimental-mode`, and two on `queues subscription create`), accepts `assets.base_path`, and fixes local R2 keys with spaces.",
  "latest": {
    "version": "4.148.0",
    "released_at": "2026-10-06T18:33:23Z",
    "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0"
  },
  "upgrade": [
    {
      "label": "In your project (Cloudflare's recommended install)",
      "command": "npm i -D wrangler@latest\nnpx wrangler --version   # 4.148.0"
    },
    {
      "label": "pnpm, yarn, bun",
      "command": "pnpm add -D wrangler@latest\nyarn add -D wrangler@latest\nbun add -d wrangler@latest"
    },
    {
      "label": "Pin this exact version",
      "command": "npm i -D wrangler@4.148.0"
    }
  ],
  "verified": {
    "date": "2026-10-07",
    "version": "4.148.0",
    "method": "Installed wrangler 4.147.0 and 4.148.0 from npm in throwaway Linux sandboxes with no Cloudflare credentials, captured `--help` for all 430 commands of each, and reproduced the errors below with a minimal Worker and `deploy --dry-run` or `--local`."
  },
  "updated_at": "2026-10-07T12:39:57Z",
  "key_facts": [
    "Latest: wrangler 4.148.0, npm publish 2026-10-06 18:33 UTC (GitHub release `wrangler@4.148.0` at 18:39 UTC in cloudflare/workers-sdk).",
    "Wrangler shipped 25 releases in September 2026, from 4.128.0 to 4.145.0, and 3 more by 2026-10-06.",
    "Both 4.147.0 and 4.148.0 expose 430 help pages (commands and subcommands) in our sandbox; the diff between them touches 5 pages and adds 5 flags on 3 commands.",
    "The `legacy_env` config field is an error since 4.111.0 (2026-07-15): service environments were removed and each environment deploys as `<name>-<environment>`.",
    "In a non-interactive shell without `CLOUDFLARE_API_TOKEN`, `wrangler deploy` exits 1 and suggests `--temporary` (a temporary account, added in 4.101.0).",
    "Release notes live in the cloudflare/workers-sdk monorepo, mixed with releases of miniflare, create-cloudflare and other packages."
  ],
  "releases": [
    {
      "version": "4.148.0",
      "released_at": "2026-10-06T18:33:23Z",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0",
      "changes": [
        {
          "text": "`assets.base_path` serves an asset directory under a public URL prefix (for example `/docs`).",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15998"
        },
        {
          "text": "`wrangler dev --tunnel-allowed-mail` requires email authentication on Quick Tunnels.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/16030"
        },
        {
          "text": "`wrangler kv namespace create --experimental-mode instant` creates KV Instant namespaces (private beta).",
          "url": "https://github.com/cloudflare/workers-sdk/pull/16005"
        },
        {
          "text": "`wrangler queues subscription create` adds `--source-namespace` and `--source-repo-name`, required for `--source artifacts.repo`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/16051"
        },
        {
          "text": "`wrangler versions secret bulk` deletes a secret whose JSON value is `null`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15283"
        },
        {
          "text": "Local `r2 object put` and `r2 bulk put` keep keys with spaces, non-ASCII characters, `#` and `%` intact.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15261"
        },
        {
          "text": "`--temporary` account notices and the claim URL now go to stderr, not stdout; scripts that read the claim URL from stdout must read stderr.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/16068"
        }
      ]
    },
    {
      "version": "4.147.0",
      "released_at": "2026-10-02T11:30:47Z",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.147.0",
      "changes": [
        {
          "text": "Container applications accept `constraints.jurisdiction: \"us\"`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15928"
        },
        {
          "text": "`wrangler containers list` reports live instances in `LIVE INSTANCES`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15974"
        },
        {
          "text": "`wrangler workflows instances list` and `describe` retry transient API failures.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15871"
        }
      ]
    },
    {
      "version": "4.146.0",
      "released_at": "2026-10-01T16:34:35Z",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.146.0",
      "changes": [
        {
          "text": "Local development supports the Workflows `createBatch()` API.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15777"
        },
        {
          "text": "`wrangler tunnel quick-start --allowed-mail` (experimental; needs cloudflared 2026.9.2 or later).",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15639"
        },
        {
          "text": "`wrangler tail --header \"Origin:https://app.example.com\"` keeps everything after the first colon.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15959"
        }
      ]
    },
    {
      "version": "4.145.0",
      "released_at": "2026-09-30T14:20:28Z",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0",
      "changes": [
        {
          "text": "Native support for the Analytics SQL binding.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15685"
        },
        {
          "text": "SQL, Catalog and Pipelines under `wrangler basin` graduate from beta to stable.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15943"
        },
        {
          "text": "Beta K2 stream management commands and producer bindings.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15948"
        }
      ]
    },
    {
      "version": "4.144.0",
      "released_at": "2026-09-29T21:12:31Z",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.144.0",
      "changes": [
        {
          "text": "`wrangler containers ssh --tty` (`-t`) forces pseudo-terminal allocation.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15919"
        },
        {
          "text": "SSH settings for Durable Object-managed Containers in the configuration API.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15951"
        }
      ]
    }
  ],
  "surface": [
    {
      "from": "4.147.0",
      "to": "4.148.0",
      "method": "`bin/tool-snapshot` ran `--help` for every wrangler subcommand of both versions in a throwaway Linux sandbox (430 and 430 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`.",
      "summary": "0 commands added, 0 removed, 3 commands with flags added or removed; 5 help pages changed in any way.",
      "commands_added": [],
      "commands_removed": [],
      "flags": [
        {
          "command": "wrangler dev",
          "added": [
            "--tunnel-allowed-mail"
          ],
          "removed": []
        },
        {
          "command": "wrangler kv namespace create",
          "added": [
            "--experimental-mode"
          ],
          "removed": []
        },
        {
          "command": "wrangler queues subscription create",
          "added": [
            "--source-namespace",
            "--source-repo-name"
          ],
          "removed": []
        }
      ],
      "notes": [
        "These are the last two minor versions. No command was added or removed; `kv namespace create` also gains the alias `--x-mode`, and the `queues subscription create --events` help now says to use `pushed`, not `cf.artifacts.repo.pushed`, for `artifacts.repo`."
      ]
    }
  ],
  "breaking": [
    {
      "version": "4.148.0",
      "change": "`--temporary` notices, the proof-of-work message and the claim URL moved from stdout to stderr.",
      "migrate": "Read the claim URL from stderr; stdout now carries only the command's own output (for example JSON from `kv namespace list --temporary`).",
      "url": "https://github.com/cloudflare/workers-sdk/pull/16068"
    },
    {
      "version": "4.131.0",
      "change": "Removed the `wrangler preview settings` commands.",
      "migrate": "Check `wrangler preview --help` in your installed version for the current Preview commands.",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.131.0"
    },
    {
      "version": "4.111.0",
      "change": "Service environments, the `legacy_env` config field and the `--legacy-env` flag were removed; `legacy_env` in config is now an error.",
      "migrate": "Delete `legacy_env` from the config. With the old default (`legacy_env = true`) nothing changes; with `legacy_env = false` each environment now deploys as a standalone Worker `<name>-<environment>`.",
      "url": "https://github.com/cloudflare/workers-sdk/pull/14620",
      "fix_page": "https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported"
    },
    {
      "version": "4.96.0",
      "change": "Pipeline bindings: the `pipeline` field was renamed to `stream`.",
      "migrate": "Rename `pipeline` to `stream` in pipeline binding configuration.",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.96.0"
    }
  ],
  "gotchas": [
    {
      "title": "`wrangler deploy` in CI without an API token",
      "version": "4.148.0",
      "command": "CI=1 npx wrangler deploy",
      "output": "✘ [ERROR] In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work. Please go to https://developers.cloudflare.com/fundamentals/api/get-started/create-token/ for instructions on how to create an api token, and assign its value to CLOUDFLARE_API_TOKEN.\n\n  To continue without logging in, rerun this command with `--temporary`. Wrangler will use a temporary account and print a claim URL.\n# exit 1 (same text in 4.147.0)",
      "fix": "Set `CLOUDFLARE_API_TOKEN` in the CI secrets, as the error says. `--temporary` uses a temporary account, not yours.",
      "url": "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/"
    },
    {
      "title": "`legacy_env` in the config is an error",
      "version": "4.148.0",
      "command": "npx wrangler deploy --dry-run -c legacy.jsonc   # legacy.jsonc contains \"legacy_env\": false",
      "output": "✘ [ERROR] Processing legacy.jsonc configuration:\n\n    - The \"legacy_env\" field is no longer supported, so please remove it from your configuration file.\n      Service environments have been removed, and each environment is now deployed as its own Worker named \"<name>-<environment>\". This matches the behaviour of \"legacy_env = true\", which was the default, so removing the field will not change how your Worker is deployed.\n      Refer to https://developers.cloudflare.com/workers/wrangler/environments/ for more information.\n# exit 1",
      "fix": "Remove `legacy_env`. If it was `false`, expect each environment to deploy as its own Worker.",
      "url": "https://github.com/cloudflare/workers-sdk/pull/14620",
      "fix_page": "https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported"
    },
    {
      "title": "`assets.base_path` is silently ignored before 4.148.0",
      "version": "4.147.0",
      "command": "npx wrangler@4.147.0 deploy --dry-run -c assets.jsonc   # \"assets\": { \"directory\": \"./public\", \"base_path\": \"/docs\" }",
      "output": "▲ [WARNING] Processing assets.jsonc configuration:\n\n    - Unexpected fields found in assets field: \"base_path\"\n\n✨ Read 1 file from the assets directory /root/w-4.147.0/public\n...\n--dry-run: exiting now.\nThere is a newer version of Wrangler available (current: 4.147.0, latest: 4.148.0). Try upgrading, as it might support this configuration option.\n# exit 0: the dry run passes and the field is dropped",
      "fix": "Upgrade to 4.148.0 or later before relying on `base_path`; 4.148.0 accepts the same config without a warning.",
      "url": "https://github.com/cloudflare/workers-sdk/pull/15998"
    },
    {
      "title": "Local R2 object with a space in its key cannot be read back",
      "version": "4.147.0",
      "command": "npx wrangler@4.147.0 r2 object put \"test-bucket/my file.txt\" --file hello.txt --local\nnpx wrangler@4.147.0 r2 object get \"test-bucket/my file.txt\" --local --pipe",
      "output": "Creating object \"my file.txt\" in bucket \"test-bucket\".\nUpload complete.\n✘ [ERROR] The specified key does not exist.",
      "fix": "Upgrade to 4.148.0: the same two commands print the object (`hello`). Objects already stored by older versions stay under their percent-encoded keys.",
      "url": "https://github.com/cloudflare/workers-sdk/pull/15261"
    }
  ],
  "monthly": [
    {
      "month": "2026-10",
      "versions": "4.146.0 to 4.148.0 (3 releases to 2026-10-07)",
      "highlights": [
        {
          "text": "4.148.0: `assets.base_path`, email-protected Quick Tunnels, KV Instant namespaces, temporary-account notices on stderr.",
          "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0"
        }
      ]
    },
    {
      "month": "2026-09",
      "versions": "4.128.0 to 4.145.0 (25 releases)",
      "highlights": [
        {
          "text": "4.129.0 added `--json` to the `wrangler workflows` commands.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15358"
        },
        {
          "text": "4.131.0 removed `wrangler preview settings`; 4.132.0 removed the gated Web Search binding and command.",
          "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.132.0"
        },
        {
          "text": "4.136.0 added experimental `--zone` and `--zone-id` to `wrangler deploy` and `wrangler triggers deploy`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/15720"
        }
      ]
    },
    {
      "month": "2026-08",
      "versions": "4.119.0 to 4.127.1 (11 releases)",
      "highlights": [
        {
          "text": "4.119.0 added OAuth 2.0 Device Authorization Grant to `wrangler login`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14064"
        },
        {
          "text": "4.121.0 honours `DO_NOT_TRACK=1` as a telemetry opt-out; 4.122.0 detects Node.js compatibility from the compatibility date.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14924"
        }
      ]
    },
    {
      "month": "2026-07",
      "versions": "4.107.0 to 4.118.0 (13 releases)",
      "highlights": [
        {
          "text": "4.111.0 (2026-07-15) removed service environments and `legacy_env`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14620"
        },
        {
          "text": "4.116.0 avoids Worker and workers.dev naming prompts in agent-driven deploys.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14907"
        }
      ]
    },
    {
      "month": "2026-06",
      "versions": "4.95.0 to 4.106.0 (12 releases)",
      "highlights": [
        {
          "text": "4.99.0 introduced `createTestHarness()` and `wrangler versions deploy --version-tag`.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14169"
        },
        {
          "text": "4.101.0 added `--temporary` (temporary account when there are no credentials).",
          "url": "https://github.com/cloudflare/workers-sdk/pull/14042"
        },
        {
          "text": "4.106.0 added auth profiles for multiple OAuth logins.",
          "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.106.0"
        }
      ]
    },
    {
      "month": "2026-05",
      "versions": "4.88.0 to 4.94.0 (10 releases)",
      "highlights": [
        {
          "text": "4.88.0 added `builtin` storage to `wrangler ai-search create`; 4.93.0 added `wrangler ai models schema` and `--containers-rollout=none`.",
          "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.93.0"
        },
        {
          "text": "4.90.0 warns that `delivery_delay` in queue producer bindings has had no effect since 2024.",
          "url": "https://github.com/cloudflare/workers-sdk/pull/12279"
        }
      ]
    }
  ],
  "sources": [
    {
      "title": "wrangler on the npm registry (versions and publish times)",
      "url": "https://registry.npmjs.org/wrangler",
      "read": "2026-10-07"
    },
    {
      "title": "cloudflare/workers-sdk releases (GitHub API)",
      "url": "https://api.github.com/repos/cloudflare/workers-sdk/releases",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.148.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.148.0",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.147.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.147.0",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.146.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.146.0",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.145.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.145.0",
      "read": "2026-10-07"
    },
    {
      "title": "wrangler@4.144.0 release notes",
      "url": "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.144.0",
      "read": "2026-10-07"
    },
    {
      "title": "PR #14620: remove service environments and legacy_env",
      "url": "https://github.com/cloudflare/workers-sdk/pull/14620",
      "read": "2026-10-07"
    },
    {
      "title": "Cloudflare docs: Install/Update Wrangler",
      "url": "https://developers.cloudflare.com/workers/wrangler/install-and-update/",
      "read": "2026-10-07"
    }
  ],
  "fixes": [
    {
      "url": "https://insidetheloop.dev/fixes/wrangler-legacy-env-no-longer-supported",
      "error": "The \"legacy_env\" field is no longer supported, so please remove it from your configuration file."
    }
  ]
}