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 multiple locations:

  • In WP_CLI::add_command() for commands added via the public API
  • In CommandFactory::create_subcommand() to catch class-based command methods
  • 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 @skipglobalargcheck annotation to allow opt-out:

  • Commands can add @skipglobalargcheck to their PHPdoc to silence warnings
  • Useful for built-in commands that intentionally override global arguments
  • Uses regex pattern matching to avoid false positives

• Added Behat test scenarios covering:

  • Single conflicts
  • Multiple conflicts
  • No false positives
  • Class-based command method conflicts
  • Skip annotation functionality

Example

Commands registering conflicting arguments now emit warnings at registration time:

Function-based command (with warning):

/**
 * @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.

Function-based command (warning suppressed):

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

// No warning - intentional override

Class-based command:

class MyCommand {
    /**
     * @synopsis [--debug]
     */
    public function my_method( $args, $assoc_args ) {}
}
WP_CLI::add_command( 'mycommand', 'MyCommand' );

// Output:
// Warning: The `mycommand my_method` command is registering an argument '--debug' that 
// conflicts with a global argument of the same name.

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

• Fixes Warn if overriding global argument #6173

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