@wordpress/env 11.0.1-next.v.20260206T143.0 → 11.0.1-next.v.202602111440.0

package/README.md

@@ -295,6 +295,42 @@ Here is a summary:
 
 `wp-env` creates generated files in the `wp-env` home directory. By default, this is `~/.wp-env`. The exception is Linux, where files are placed at `~/wp-env` [for compatibility with Snap Packages](https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325). The `wp-env` home directory contains a subdirectory for each project named `/$md5_of_project_path`. To change the `wp-env` home directory, set the `WP_ENV_HOME` environment variable. For example, running `WP_ENV_HOME="something" wp-env start` will download the project files to the directory `./something/$md5_of_project_path` (relative to the current directory).
 
+### Global options
+
+These options apply to all `wp-env` commands:
+
+```
+--debug    Enable debug output.                      [boolean] [default: false]
+--config   Path to a custom .wp-env.json configuration file.           [string]
+```
+
+The `--config` option allows you to use a custom configuration file instead of the default `.wp-env.json`. This is useful for running multiple parallel environments from the same directory.
+
+When using a custom config file, the override file is derived from its name. For example:
+- `--config=staging.json` will look for `staging.override.json`
+- `--config=./configs/dev.wp-env.json` will look for `./configs/dev.wp-env.override.json`
+
+#### Running parallel environments
+
+You can run multiple wp-env environments from the same folder by using different config files and ports:
+
+```sh
+# Start first environment with default config
+wp-env start
+
+# Start second environment with custom config on different ports
+WP_ENV_PORT=8890 WP_ENV_TESTS_PORT=8891 wp-env start --config=./staging.json
+
+# Check status of each environment
+wp-env status
+wp-env status --config=./staging.json
+
+# Stop specific environment
+wp-env stop --config=./staging.json
+```
+
+Each config file gets its own isolated Docker containers and data, so changes in one environment don't affect the other.
+
 ### `wp-env start`
 
 The start command installs and initializes the WordPress environment, which includes downloading any specified remote sources. By default, `wp-env` will not update or re-configure the environment except when the configuration file changes. Tell `wp-env` to update sources and apply the configuration options again with `wp-env start --update`. This will not overwrite any existing content.

package/lib/cli.js

@@ -101,6 +101,11 @@ module.exports = function cli() {
 		describe: 'Enable debug output.',
 		default: false,
 	} );
+	yargs.option( 'config', {
+		type: 'string',
+		describe: 'Path to a custom .wp-env.json configuration file.',
+		requiresArg: true,
+	} );
 
 	yargs.parserConfiguration( {
 		// Treats unknown options as arguments for commands to deal with instead of discarding them.

package/lib/commands/clean.js

@@ -26,16 +26,18 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  * @param {Object}                 options.spinner     A CLI spinner which indicates progress.
  * @param {boolean}                options.scripts     Indicates whether or not lifecycle scripts should be executed.
  * @param {boolean}                options.debug       True if debug mode is enabled.
+ * @param {string|null}            options.config      Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function clean( {
 	environment,
 	spinner,
 	scripts,
 	debug,
+	config: customConfigPath,
 } ) {
 	spinner.warn( 'The `clean` command is deprecated. Use `reset` instead.' );
 
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	const runtime = getRuntime(
 		await detectRuntime( config.workDirectoryPath )
 	);

package/lib/commands/cleanup.js

@@ -19,14 +19,21 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  * Removes Docker containers, volumes, networks, and local files,
  * but preserves Docker images for faster re-starts.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
- * @param {boolean} options.force   If true, skips the confirmation prompt.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.force   If true, skips the confirmation prompt.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function cleanup( { spinner, scripts, force, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+module.exports = async function cleanup( {
+	spinner,
+	scripts,
+	force,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 
 	try {
 		await fs.readdir( config.workDirectoryPath );
@@ -35,7 +42,9 @@ module.exports = async function cleanup( { spinner, scripts, force, debug } ) {
 		return;
 	}
 
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 
 	spinner.info( runtime.getCleanupWarningMessage() );
 

package/lib/commands/destroy.js

@@ -16,14 +16,21 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Destroy the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
- * @param {boolean} options.force   If true, skips the confirmation prompt.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.force   If true, skips the confirmation prompt.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function destroy( { spinner, scripts, force, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+module.exports = async function destroy( {
+	spinner,
+	scripts,
+	force,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 
 	try {
 		await fs.readdir( config.workDirectoryPath );

package/lib/commands/logs.js

@@ -13,14 +13,21 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Displays the Docker & PHP logs on the given environment.
  *
- * @param {Object}  options
- * @param {Object}  options.environment The environment to run the command in (develop or tests).
- * @param {Object}  options.watch       If true, follow along with log output.
- * @param {Object}  options.spinner     A CLI spinner which indicates progress.
- * @param {boolean} options.debug       True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.environment The environment to run the command in (develop or tests).
+ * @param {Object}      options.watch       If true, follow along with log output.
+ * @param {Object}      options.spinner     A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug       True if debug mode is enabled.
+ * @param {string|null} options.config      Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function logs( { environment, watch, spinner, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+module.exports = async function logs( {
+	environment,
+	watch,
+	spinner,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	const runtime = getRuntime(
 		await detectRuntime( config.workDirectoryPath )
 	);

package/lib/commands/reset.js

@@ -24,15 +24,19 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  * @param {Object}                 options.spinner     A CLI spinner which indicates progress.
  * @param {boolean}                options.scripts     Indicates whether or not lifecycle scripts should be executed.
  * @param {boolean}                options.debug       True if debug mode is enabled.
+ * @param {string|null}            options.config      Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function reset( {
 	environment,
 	spinner,
 	scripts,
 	debug,
+	config: customConfigPath,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 
 	await runtime.clean( config, { environment, spinner, debug } );
 

package/lib/commands/run.js

@@ -13,13 +13,14 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Runs an arbitrary command on the given Docker container.
  *
- * @param {Object}   options
- * @param {string}   options.container The Docker container to run the command on.
- * @param {string[]} options.command   The command to run.
- * @param {string[]} options.'--'      Any arguments that were passed after a double dash.
- * @param {string}   options.envCwd    The working directory for the command to be executed from.
- * @param {Object}   options.spinner   A CLI spinner which indicates progress.
- * @param {boolean}  options.debug     True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {string}      options.container The Docker container to run the command on.
+ * @param {string[]}    options.command   The command to run.
+ * @param {string[]}    options.'--'      Any arguments that were passed after a double dash.
+ * @param {string}      options.envCwd    The working directory for the command to be executed from.
+ * @param {Object}      options.spinner   A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug     True if debug mode is enabled.
+ * @param {string|null} options.config    Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function run( {
 	container,
@@ -28,8 +29,9 @@ module.exports = async function run( {
 	envCwd,
 	spinner,
 	debug,
+	config: customConfigPath,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	const runtime = getRuntime(
 		await detectRuntime( config.workDirectoryPath )
 	);

package/lib/commands/start.js

@@ -21,14 +21,15 @@ const { getRuntime, getSavedRuntime, saveRuntime } = require( '../runtime' );
 /**
  * Starts the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.update  If true, update sources.
- * @param {string}  options.xdebug  The Xdebug mode to set.
- * @param {string}  options.spx     The SPX mode to set.
- * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
- * @param {boolean} options.debug   True if debug mode is enabled.
- * @param {string}  options.runtime The runtime to use ('docker' or 'playground').
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.update  If true, update sources.
+ * @param {string}      options.xdebug  The Xdebug mode to set.
+ * @param {string}      options.spx     The SPX mode to set.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string}      options.runtime The runtime to use ('docker' or 'playground').
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function start( {
 	spinner,
@@ -38,6 +39,7 @@ module.exports = async function start( {
 	scripts,
 	debug,
 	runtime: runtimeName = 'docker',
+	config: customConfigPath,
 } ) {
 	spinner.text = 'Reading configuration.';
 
@@ -48,7 +50,7 @@ module.exports = async function start( {
 		await checkForLegacyInstall( spinner );
 	}
 
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	config.debug = debug;
 
 	// Check if switching runtimes and prompt user to destroy old environment first.

package/lib/commands/status.js

@@ -39,15 +39,21 @@ function isEnvironmentInitialized( config ) {
 /**
  * Outputs the status of the wp-env environment.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
- * @param {boolean} options.json    True to output as JSON.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {boolean}     options.json    True to output as JSON.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function status( { spinner, debug, json } ) {
+module.exports = async function status( {
+	spinner,
+	debug,
+	json,
+	config: customConfigPath,
+} ) {
 	spinner.text = 'Getting environment status.';
 
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 
 	// Check if environment is initialized by looking for runtime-specific files.
 	// We check for these files specifically because the work directory may exist
@@ -70,7 +76,7 @@ module.exports = async function status( { spinner, debug, json } ) {
 	}
 
 	// Detect and get runtime.
-	const runtimeName = detectRuntime( config.workDirectoryPath );
+	const runtimeName = await detectRuntime( config.workDirectoryPath );
 	const runtime = getRuntime( runtimeName );
 
 	// Get status from runtime.

package/lib/commands/stop.js

@@ -13,12 +13,17 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Stops the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function stop( { spinner, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+module.exports = async function stop( {
+	spinner,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	const runtime = getRuntime(
 		await detectRuntime( config.workDirectoryPath )
 	);

package/lib/config/load-config.js

@@ -11,6 +11,7 @@ const fs = require( 'fs' ).promises;
 const getCacheDirectory = require( './get-cache-directory' );
 const md5 = require( '../md5' );
 const { parseConfig, getConfigFilePath } = require( './parse-config' );
+const { ValidationError } = require( './validate-config' );
 const postProcessConfig = require( './post-process-config' );
 
 /**
@@ -35,12 +36,31 @@ const postProcessConfig = require( './post-process-config' );
 /**
  * Loads any configuration from a given directory.
  *
- * @param {string} configDirectoryPath The directory we want to load the config from.
+ * @param {string}      configDirectoryPath The directory we want to load the config from.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPConfig>} The config object we've loaded.
  */
-module.exports = async function loadConfig( configDirectoryPath ) {
-	const configFilePath = getConfigFilePath( configDirectoryPath );
+module.exports = async function loadConfig(
+	configDirectoryPath,
+	customConfigPath = null
+) {
+	const configFilePath = getConfigFilePath(
+		configDirectoryPath,
+		'local',
+		customConfigPath
+	);
+
+	// If a custom config path was provided, verify the file exists.
+	if ( customConfigPath ) {
+		try {
+			await fs.stat( configFilePath );
+		} catch ( error ) {
+			throw new ValidationError(
+				`Config file not found: ${ configFilePath }`
+			);
+		}
+	}
 
 	const cacheDirectoryPath = path.resolve(
 		await getCacheDirectory(),
@@ -49,7 +69,11 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 
 	// Parse any configuration we found in the given directory.
 	// This comes merged and prepared for internal consumption.
-	let config = await parseConfig( configDirectoryPath, cacheDirectoryPath );
+	let config = await parseConfig(
+		configDirectoryPath,
+		cacheDirectoryPath,
+		customConfigPath
+	);
 
 	// Make sure to perform any additional post-processing that
 	// may be needed before the config object is ready for
@@ -64,9 +88,14 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 		),
 		configDirectoryPath,
 		workDirectoryPath: cacheDirectoryPath,
+		customConfigPath,
 		detectedLocalConfig: await hasLocalConfig( [
 			configFilePath,
-			getConfigFilePath( configDirectoryPath, 'override' ),
+			getConfigFilePath(
+				configDirectoryPath,
+				'override',
+				customConfigPath
+			),
 		] ),
 		lifecycleScripts: config.lifecycleScripts,
 		env: config.env,

package/lib/config/parse-config.js

@@ -111,22 +111,27 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
  * constructs an object in the format used internally.
  *
  *
- * @param {string} configDirectoryPath A path to the directory we are parsing the config for.
- * @param {string} cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string}      configDirectoryPath A path to the directory we are parsing the config for.
+ * @param {string}      cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPRootConfig>} Parsed config.
  */
-async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
+async function parseConfig(
+	configDirectoryPath,
+	cacheDirectoryPath,
+	customConfigPath = null
+) {
 	// The local config will be used to override any defaults.
 	const localConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath ),
+		getConfigFilePath( configDirectoryPath, 'local', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
 	// Any overrides that can be used in place
 	// of properties set by the local config.
 	const overrideConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath, 'override' ),
+		getConfigFilePath( configDirectoryPath, 'override', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
@@ -161,27 +166,37 @@ async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
 /**
  * Gets the path to the config file.
  *
- * @param {string} configDirectoryPath The path to the directory containing config files.
- * @param {string} type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string}      configDirectoryPath The path to the directory containing config files.
+ * @param {string}      type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string|null} customConfigPath    Optional custom config file path (only used for 'local' type).
  *
  * @return {string} The path to the config file.
  */
-function getConfigFilePath( configDirectoryPath, type = 'local' ) {
-	let fileName;
-	switch ( type ) {
-		case 'local': {
-			fileName = '.wp-env.json';
-			break;
-		}
+function getConfigFilePath(
+	configDirectoryPath,
+	type = 'local',
+	customConfigPath = null
+) {
+	// If a custom config path is provided for the local config, use it.
+	if ( type === 'local' && customConfigPath ) {
+		return path.resolve( customConfigPath );
+	}
 
-		case 'override': {
-			fileName = '.wp-env.override.json';
-			break;
-		}
+	// For override, derive from custom config: staging.json -> staging.override.json
+	if ( type === 'override' && customConfigPath ) {
+		const resolved = path.resolve( customConfigPath );
+		const ext = path.extname( resolved );
+		const base = path.basename( resolved, ext );
+		const dir = path.dirname( resolved );
+		return path.join( dir, `${ base }.override${ ext }` );
+	}
 
-		default: {
-			throw new Error( `Invalid config file type "${ type }.` );
-		}
+	// Default behavior.
+	const fileName =
+		type === 'local' ? '.wp-env.json' : '.wp-env.override.json';
+
+	if ( type !== 'local' && type !== 'override' ) {
+		throw new Error( `Invalid config file type "${ type }.` );
 	}
 
 	return path.resolve( configDirectoryPath, fileName );

package/lib/config/test/__snapshots__/config-integration.js.snap

@@ -3,6 +3,7 @@
 exports[`Config Integration should load local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -84,6 +85,7 @@ exports[`Config Integration should load local and override configuration files 1
 exports[`Config Integration should load local configuration file 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -165,6 +167,7 @@ exports[`Config Integration should load local configuration file 1`] = `
 exports[`Config Integration should use default configuration 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -246,6 +249,7 @@ exports[`Config Integration should use default configuration 1`] = `
 exports[`Config Integration should use environment variables over local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {

package/lib/runtime/docker/index.js

@@ -107,6 +107,7 @@ class DockerRuntime {
 			xdebug,
 			spx,
 			writeChanges: true,
+			customConfigPath: config.customConfigPath,
 		} );
 
 		// Check if the hash of the config has changed. If so, run configuration.
@@ -375,6 +376,7 @@ class DockerRuntime {
 		const { dockerComposeConfigPath } = await initConfig( {
 			spinner,
 			debug,
+			customConfigPath: config.customConfigPath,
 		} );
 
 		spinner.text = 'Stopping WordPress.';
@@ -452,7 +454,11 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async clean( config, { environment, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		const description = `${ environment } environment${
 			environment === 'all' ? 's' : ''
@@ -525,7 +531,11 @@ class DockerRuntime {
 		// Validate the container name (throws for deprecated containers)
 		validateRunContainer( container );
 
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		// Shows a contextual tip for the given command.
 		const joinedCommand = command.join( ' ' );
@@ -552,7 +562,11 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async logs( config, { environment, watch, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		// If we show text while watching the logs, it will continue showing up every
 		// few lines in the logs as they happen, which isn't a good look. So only
@@ -621,7 +635,11 @@ class DockerRuntime {
 	async getStatus( config, { spinner, debug } ) {
 		spinner.text = 'Getting environment status.';
 
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 		const dockerComposeConfig = {
 			config: fullConfig.dockerComposeConfigPath,
 			log: debug,

package/lib/runtime/docker/init-config.js

@@ -22,16 +22,17 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  * ./.wp-env.json, creates ~/.wp-env, ~/.wp-env/docker-compose.yml, and
  * ~/.wp-env/Dockerfile.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner      A CLI spinner which indicates progress.
- * @param {boolean} options.debug        True if debug mode is enabled.
- * @param {string}  options.xdebug       The Xdebug mode to set. Defaults to "off".
- * @param {string}  options.spx          The SPX mode to set. Defaults to "off".
- * @param {boolean} options.writeChanges If true, writes the parsed config to the
- *                                       required docker files like docker-compose
- *                                       and Dockerfile. By default, this is false
- *                                       and only the `start` command writes any
- *                                       changes.
+ * @param {Object}      options
+ * @param {Object}      options.spinner          A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug            True if debug mode is enabled.
+ * @param {string}      options.xdebug           The Xdebug mode to set. Defaults to "off".
+ * @param {string}      options.spx              The SPX mode to set. Defaults to "off".
+ * @param {boolean}     options.writeChanges     If true, writes the parsed config to the
+ *                                               required docker files like docker-compose
+ *                                               and Dockerfile. By default, this is false
+ *                                               and only the `start` command writes any
+ *                                               changes.
+ * @param {string|null} options.customConfigPath Path to a custom .wp-env.json configuration file.
  * @return {WPConfig} The-env config object.
  */
 module.exports = async function initConfig( {
@@ -40,8 +41,9 @@ module.exports = async function initConfig( {
 	xdebug = 'off',
 	spx = 'off',
 	writeChanges = false,
+	customConfigPath = null,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	config.debug = debug;
 
 	// Adding this to the config allows the start command to understand that the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/env",
-	"version": "11.0.1-next.v.20260206T143.0+81f8de885",
+	"version": "11.0.1-next.v.202602111440.0+a307a2e35",
 	"description": "A zero-config, self contained local WordPress environment for development and testing.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -64,5 +64,5 @@
 	"scripts": {
 		"test": "echo \"Error: run tests from root\" && exit 1"
 	},
-	"gitHead": "6ae3fbb907e6c309ff6a0685e5e5ff0c2ee23b15"
+	"gitHead": "e0a2324a9690e55f4101d61113f4bbbf240b55ed"
 }