diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx
index 76be72036acb1..8e057eb96357e 100644
--- a/src/content/docs/en/guides/environment-variables.mdx
+++ b/src/content/docs/en/guides/environment-variables.mdx
@@ -71,8 +71,6 @@ const isDev = import.meta.env.DEV;
 ### `.env` files
 Environment variables can be loaded from `.env` files in your project directory.
 
-You can also attach a mode (either `production` or `development`) to the filename, like `.env.production` or `.env.development`, which makes the environment variables only take effect in that mode.
-
 Just create a `.env` file in the project directory and add some variables to it.
 
 ```ini title=".env"
@@ -82,6 +80,23 @@ DB_PASSWORD="foobar"
 PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
 ```
 
+You can also add `.production`, `.development` or a custom mode name to the filename itself (e.g `env.testing`, `.env.staging`). This allows you to use different sets of environment variables at different times.
+
+The `astro dev` and `astro build` commands default to `"development"` and `"production"` modes, respectively. You can run these commands with the [`--mode` flag](#--mode-string) to pass a different value for `mode` and load the matching `.env` file.
+
+This allows you to run the dev server or build your site connecting to different APIs:
+
+```bash
+# Run the dev server connected to a "staging" API
+astro dev --mode staging
+
+# Build a site that connects to a "production" API with additional debug information
+astro build --devOutput
+
+# Build a site that connects to a "testing" API
+astro build --mode testing
+```
+
 For more on `.env` files, [see the Vite documentation](https://vite.dev/guide/env-and-mode.html#env-files).
 
 ### Using the CLI
diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
index 2c60d0c63ac0d..8393756fc5431 100644
--- a/src/content/docs/en/reference/cli-reference.mdx
+++ b/src/content/docs/en/reference/cli-reference.mdx
@@ -146,7 +146,15 @@ Runs Astro's development server. This is a local HTTP server that doesn't bundle
 
 Builds your site for deployment. By default, this will generate static files and place them in a `dist/` directory. If [SSR is enabled](/en/guides/on-demand-rendering/), this will generate the necessary server files to serve your site.
 
-Can be combined with the [common flags](#common-flags) documented below.
+### Flags
+
+The command accepts [common flags](#common-flags) and the following additional flags:
+
+#### `--devOutput`
+
+<p><Since v="5.0.0" /></p>
+
+Outputs a development-based build similar to code transformed in `astro dev`. This can be useful to test build-only issues with additional debugging information included.
 
 ## `astro preview`
 
@@ -343,6 +351,12 @@ Specifies the path to the config file relative to the project root. Defaults to
 astro --config config/astro.config.mjs dev
 ```
 
+### `--mode <string>`
+
+<p><Since v="5.0.0" /></p>
+
+Configures the [`mode`](#mode) inline config for your project.
+
 ### `--outDir <path>`
 
 <p><Since v="3.3.0" /></p>
@@ -411,7 +425,7 @@ The `AstroInlineConfig` type is used by all of the command APIs below. It extend
 ```ts
 interface AstroInlineConfig extends AstroUserConfig {
 	configFile?: string | false;
-	mode?: "development" | "production";
+	mode?: string;
 	logLevel?: "debug" | "info" | "warn" | "error" | "silent";
 }
 ```
@@ -438,11 +452,16 @@ The inline config passed in this object will take highest priority when merging
 
 <p>
 
-**Type:** `"development" | "production"`<br />
-**Default:** `"development"` when running `astro dev`, `"production"` when running `astro build`
+**Type:** `string`<br />
+**Default:** `"development"` when running `astro dev`, `"production"` when running `astro build`<br />
+<Since v="5.0.0" />
 </p>
 
-The mode used when building your site to generate either "development" or "production" code.
+The mode used when developing or building your site (e.g. `"production"`, `"testing"`).
+
+This value is passed to Vite using [the `--mode` flag](#--mode-string) when the `astro build` or `astro dev` commands are run to determine the value of `import.meta.env.MODE`. This also determines which `.env` files are loaded, and therefore the values of `astro:env`. See the [environment variables page](/en/guides/environment-variables/) for more details.
+
+To output a development-based build, you can run `astro build` with the [`--devOutput` flag](#--devoutput).
 
 #### `logLevel`