Document CLOUDFLARE_ENV environment variable for Wrangler

src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx

@@ -0,0 +1,46 @@
+---
+title: Select Wrangler environments using the CLOUDFLARE_ENV environment variable
+description: Wrangler now supports the CLOUDFLARE_ENV environment variable to select the active environment without using the --env flag.
+products:
+  - workers
+date: 2025-11-09
+---
+
+Wrangler now supports using the `CLOUDFLARE_ENV` [environment variable](/workers/wrangler/system-environment-variables/#supported-environment-variables) to select the active [environment](/workers/wrangler/environments/) for your Worker commands. This provides a more flexible way to manage environments, especially when working with build tools and CI/CD pipelines.
+
+## What's new
+
+**Environment selection via environment variable:**
+- Set `CLOUDFLARE_ENV` to specify which environment to use for Wrangler commands
+- Works with all Wrangler commands that support the `--env` flag
+- The `--env` command line argument takes precedence over the `CLOUDFLARE_ENV` environment variable
+
+## Example usage
+
+```bash
+# Deploy to the production environment using CLOUDFLARE_ENV
+CLOUDFLARE_ENV=production wrangler deploy
+
+# Upload a version to the staging environment
+CLOUDFLARE_ENV=staging wrangler versions upload
+
+# The --env flag takes precedence over CLOUDFLARE_ENV
+CLOUDFLARE_ENV=dev wrangler deploy --env production
+# This will deploy to production, not dev
+```
+
+## Use with build tools
+
+The `CLOUDFLARE_ENV` environment variable is particularly useful when working with build tools like Vite. You can set the environment once during the build process, and it will be used for both building and deploying your Worker:
+
+```bash
+# Set the environment for both build and deploy
+CLOUDFLARE_ENV=production npm run build & wrangler deploy
+```
+
+When using `@cloudflare/vite-plugin`, the build process generates a ["redirected deploy config"](/workers/wrangler/configuration/#generated-wrangler-configuration) that is flattened to only contain the active environment. Wrangler will validate that the environment specified matches the environment used during the build to prevent accidentally deploying a Worker built for one environment to a different environment.
+
+## Learn more
+
+- [System environment variables](/workers/wrangler/system-environment-variables/)
+- [Environments](/workers/wrangler/environments/)

src/content/docs/workers/wrangler/environments.mdx

@@ -48,6 +48,8 @@ Review the following environments flow:
 
 4.  Environments are used with the `--env` or `-e` flag on Wrangler commands. For example, you can develop the Worker in the `dev` environment by running `npx wrangler dev -e=dev`, and deploy it with `npx wrangler deploy -e=dev`.
 
+    Alternatively, you can use the [`CLOUDFLARE_ENV` environment variable](/workers/wrangler/system-environment-variables/#supported-environment-variables) to select the active environment. For example, `CLOUDFLARE_ENV=dev npx wrangler deploy` will deploy to the `dev` environment. The `--env` command line argument takes precedence over the `CLOUDFLARE_ENV` environment variable.
+
         <Render file="vite-environments" product="workers" />
 
 </Steps>

src/content/docs/workers/wrangler/system-environment-variables.mdx

@@ -51,6 +51,10 @@ Wrangler supports the following environment variables:
 
   - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`.
 
+- `CLOUDFLARE_ENV` <Type text="string" /> <MetaInfo text="optional" />
+
+  - The [environment](/workers/wrangler/environments/) to use for Wrangler commands. This allows you to select an environment without using the `--env` flag. For example, `CLOUDFLARE_ENV=production wrangler deploy` will deploy to the `production` environment. The `--env` command line argument takes precedence over this environment variable.
+
 - `WRANGLER_SEND_METRICS` <Type text="string" /> <MetaInfo text="optional" />
 
   - Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).