Skip to content

Warn when commands override global arguments #6174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Copilot wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Warn when commands override global arguments #6174

Copilot wants to merge 5 commits into from
+162 −0

Conversation

Copy link
Contributor

Copilot AI commented Dec 20, 2025 •
edited
Loading

Custom commands can define arguments with the same names as WP-CLI's global arguments (--debug, --user, --quiet, etc.), causing flags to silently fail or behave unexpectedly. This makes it difficult to introduce new global arguments without breaking existing commands.

Changes

  • Added check_global_arg_conflicts() validation in WP_CLI::add_command()

    • Parses command synopsis to extract argument names (assoc/flag types)
    • Compares against global arguments from config spec
    • Caches global argument list for performance
    • Issues warning for each conflict detected

  • Added Behat test scenarios covering single conflicts, multiple conflicts, and no false positives

Example

Commands registering conflicting arguments now emit warnings at registration time:

/**
 * @synopsis [--debug]
 */
WP_CLI::add_command( 'mycommand', function() {} );

// Output:
// Warning: The `mycommand` command is registering an argument '--debug' that conflicts 
// with a global argument of the same name. This can lead to unexpected behavior.

Warnings are informational only—commands continue to work. The --quiet flag suppresses warnings as expected.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • example.com
    • Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php d asp_tags=Off' '-d short_open_tag=Off' '-d error_reporting=E_ALL' '-n' '-l' './bundle/rmccue/resh (dns block)
    • Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php tup_errors=0' '-d asp_tags=Off' -v (dns block)
  • nosuchhost_asdf_asdf_asdf.com
    • Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php d asp_tags=Off' '-d short_open_tag=Off' '-d error_reporting=E_ALL' '-n' '-l' './bundle/rmccue/resh (dns block)
    • Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php tup_errors=0' '-d asp_tags=Off' -v (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>Warn if overriding global argument</issue_title>
<issue_description>## Feature Request

Describe your use case and the problem you are facing

Right now, it's possible for custom commands to override global arguments such as debug or user, either accidentally or willingly.

This can make for confusing user experience because flags won't work as expected.

Plus, it makes it difficult to introduce new global arguments in the future because you won't know about it.

Describe the solution you'd like

If a command defines an argument with the same name as an existing global argument in WP-CLI, there should be a warning either when registering that command or when running the command.

Stretch goal:

This functionality could be used to more easily introduce new global arguments as well, by warning if an argument clashes with one we intend to introduce in the future. For example, in v3.0.0 we could warn you about using argument "foo", but only actually introduce it in v3.1.0, where it would error instead.
</issue_description>

Comments on the Issue (you are @copilot in this section)

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI self-assigned this Dec 20, 2025
Copilot AI and others added 3 commits December 20, 2025 19:50
@swissspidy
Add warning when command arguments conflict with global arguments
b86abdc 
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy
Address code review feedback - improve docblock and add comment about…
14e2756 
… generic type

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy
Optimize with caching and improve documentation
dedd375 
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Copilot AI changed the title [WIP] Add warning for overriding global arguments in commands Warn when commands override global arguments Dec 20, 2025
Copilot AI requested a review from swissspidy December 20, 2025 19:56
@codecov
Copy link

codecov bot commented Dec 20, 2025 •
edited
Loading

Codecov Report

❌ Patch coverage is 68.96552% with 9 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
php/class-wp-cli.php 68.96% 9 Missing ⚠️

📢 Thoughts on this report? Let us know!

@swissspidy swissspidy marked this pull request as ready for review December 20, 2025 20:23
@swissspidy swissspidy requested a review from a team as a code owner December 20, 2025 20:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@swissspidy swissspidy Awaiting requested review from swissspidy

At least 1 approving review is required to merge this pull request.

Assignees

@swissspidy swissspidy

Copilot code review Copilot

Labels

breaking-change command:cli command:config

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Warn if overriding global argument

2 participants

@swissspidy