Global runtime parameters rejected as "unknown" when used with an alias

[Genyus]

Bug Report

• Yes, I reviewed the contribution guidelines.
• Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.

Describe the current, buggy behavior

Since v2.1.10, passing a global parameter (e.g. --url) in conjunction with an alias causes an error:

Error: Parameter errors:
 unknown --url parameter

The failure only manifests when both an alias that carries a config key and a matching CLI flag are present simultaneously. Without an alias, the command runs correctly, but the same invocation worked correctly in v2.1.9.

Describe how other contributors can replicate this bug

Given a wp-cli.yml with an alias that includes a url key:

"@dev":
  path: web/wp
  url: https://example.test

Run the following commands:

# Fails — alias present alongside --url:
wp @dev --url=https://example.com search-replace 'example.com' 'example.test'
# Error: Parameter errors:
#  unknown --url parameter

# Works — no alias:
wp --url=https://example.com search-replace 'example.com' 'example.test'

# Works — alias without explicit --url (alias url used instead):
wp @dev search-replace 'example.com' 'example.test'

Describe what you would expect as the correct outcome

Global parameters should be processed correctly whether an alias is present or not.

Let us know what environment you are running this on

OS:     Darwin 25.2.0 Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:40 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6000 arm64
Shell:  /bin/zsh
PHP binary:     /opt/homebrew/bin/php
PHP version:    8.3.13
PHP memory limit:       128M
php.ini used:   /opt/homebrew/etc/php/8.3/php.ini
MySQL binary:   /opt/homebrew/bin/mysql
MySQL version:  mysql  Ver 8.4.3 for macos15.1 on arm64 (Homebrew)
SQL modes:
WP-CLI root dir:        /Users/genyus/Dev/cbf/wordpress/vendor/wp-cli/wp-cli
WP-CLI vendor dir:      /Users/genyus/Dev/cbf/wordpress/vendor
WP_CLI phar path:
WP-CLI packages dir:    /Users/genyus/.wp-cli/packages/
WP-CLI cache dir:       /Users/genyus/.wp-cli/cache
WP-CLI global config:   /Users/genyus/.wp-cli/config.yml
WP-CLI project config:  /Users/genyus/Dev/cbf/wordpress/wp-cli.yml
WP-CLI version: 2.13.0-alpha
Warning: PHP memory limit is set to 128M. This may be too low for some WP-CLI operations. Consider increasing it to at least 512M or setting it to -1 (unlimited) for CLI usage.

Provide additional context/Screenshots

I believe this bug was introduced when <old> and <new> changed from required to optional positional arguments and [--old=<value>] / [--new=<value>] alternatives were added in v2.1.10.

When an alias is used, its config is merged into the runtime config before CLI arg parsing completes. For any key is already present in the runtime config from the alias (e.g. url, path, etc), it appears the subsequently-parsed CLI flag is no longer consumed as a global runtime param — it falls through into $assoc_args and is rejected by WP_CLI\Dispatcher\Subcommand::validate_args().

The synopsis change appears to have altered the code path taken when an alias has already populated keys into the runtime config, causing any duplicate global parameter to no longer be identified and be stripped before subcommand validation runs.

[swissspidy]

Thanks for your report. This is an interesting one.

The test at https://github.com/wp-cli/wp-cli/blob/626c6662c7094ca73145677be01d9c6ef1dca479/features/aliases.feature#L49-L71 (which has been there for over 9 years) makes it sound like this is actually intended behavior. But this recent change in search-replace command indeed seems to have changed the code path being used.

While there's an AI-generated PR at wp-cli/wp-cli#6299, it would alter this existing behavior in the framework, which would make it a breaking change.

Hmm 🤔