---

This section details on the original issue you should resolve

<issue_title>Portions of a multi-line command description are located in a misleading place when viewed via wp help</issue_title>
<issue_description>## 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

Here is a sample PHP DocBlock for a command I created called clear-cloudflare-cache:

	/**
	 * Clear the Cloudflare cache. Default: purge everything. Uses $CLOUDFLARE_API_KEY environment variable.
	 *
	 * API documentation: https://developers.cloudflare.com/api/resources/cache/
	 *
	 * ## OPTIONS
	 *
	 * <zone_id>
	 * : Cloudflare zone ID.
	 *
	 * ## EXAMPLES
	 *
	 *     # Clear the cloudflare cache for a domain.
	 *     wp bzmn clear-cloudflare-cache 12345
	 *     Success: The Cloudflare cache has been cleared.
	 *
	 * @subcommand clear-cloudflare-cache
	 * @alias clear_cloudflare_cache
	 */

As you can see, the command description falls on multiple lines:

Clear the Cloudflare cache. Default: purge everything. Uses $CLOUDFLARE_API_KEY environment variable.

API documentation: https://developers.cloudflare.com/api/resources/cache/

When I view the help documentation via wp help bzmn clear-cloudflare-cache, here is what it looks like:

NAME

  wp bzmn clear-cloudflare-cache

DESCRIPTION

  Clear the Cloudflare cache. Default: purge everything. Uses
  $CLOUDFLARE_API_KEY environment variable.

SYNOPSIS

  wp bzmn clear-cloudflare-cache <zone_id>

ALIAS

  clear_cloudflare_cache

  API documentation: https://developers.cloudflare.com/api/resources/cache/

OPTIONS
...

As you can see, the second line beginning with "API documentation..." is displayed in the ALIAS section. This is very misleading and not desirable.

If I remove the @alias definition, here is what the output of wp help bzmn clear-cloudflare-cache looks like:

NAME

  wp bzmn clear-cloudflare-cache

DESCRIPTION

  Clear the Cloudflare cache. Default: purge everything. Uses
  $CLOUDFLARE_API_KEY environment variable.

SYNOPSIS

  wp bzmn clear-cloudflare-cache <zone_id>

  API documentation: https://developers.cloudflare.com/api/resources/cache/

OPTIONS

  <zone_id>
    Cloudflare zone ID.

EXAMPLES
...

The second line beginning with "API documentation..." is now in the SYNOPSIS section. This to me is still not right. What I would like to see is the "API documentation..." line under the first line of the DESCRIPTION section like so:

NAME

  wp bzmn clear-cloudflare-cache

DESCRIPTION

  Clear the Cloudflare cache. Default: purge everything. Uses
  $CLOUDFLARE_API_KEY environment variable.

  API documentation: https://developers.cloudflare.com/api/resources/cache/

SYNOPSIS

  wp bzmn clear-cloudflare-cache <zone_id>

ALIAS

  clear_cloudflare_cache

OPTIONS
...

Finally, here's the output of "wp cli info":

OS:     Darwin 24.6.0 Darwin Kernel Version 24.6.0: Wed Nov  5 21:33:59 PST 2025; root:xnu-11417.140.69.705.2~1/RELEASE_ARM64_T8112 x86_64
Shell:  /bin/zsh
PHP binary:     /usr/local/Cellar/php@8.3/8.3.23/bin/php
PHP version:    8.3.23
php.ini used:   /usr/local/etc/php/8.3/php.ini
MySQL binary:   /Users/Shared/DBngin/mysql/8.0.27/bin/mysql
MySQL version:  mysql  Ver 8.0.27 for macos11 on x86_64 (MySQL Community Server - GPL)
SQL modes:      ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
WP-CLI root dir:        phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:      phar://wp-cli.phar/vendor
WP_CLI phar path:       phar:///usr/local/bin/wp
WP-CLI packages dir:    /Users/saul/.wp-cli/packages/
WP-CLI cache dir:       /Users/saul/.wp-cli/cache
WP-CLI global config:   /Users/saul/.wp-cli/config.yml
WP-CLI project config:
WP-CLI version: 2.12.0
```</issue_description>

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

<comments>
</comments>