Skip to content

Improve help screens: show disabled commands with reason and add --full recursive help#6287

Draft
Copilot wants to merge 3 commits intomainfrom
copilot/improve-help-screens-user-experience
Draft

Improve help screens: show disabled commands with reason and add --full recursive help#6287
Copilot wants to merge 3 commits intomainfrom
copilot/improve-help-screens-user-experience

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 22, 2026 •
edited
Loading

Disabled commands were silently hidden from help listings, making it hard to understand why a command seemed to be missing. There was also no way to get a comprehensive view of all subcommands and their documentation in one place.

Changes

Show disabled commands with reason in help listings

  • CompositeCommand::show_usage() — disabled subcommands now appear with the reason appended rather than being omitted (affects wp core, wp db, etc.)
  • Help_Command::render_subcommands() — the SUBCOMMANDS section in wp help <cmd> now lists disabled commands at the end with the reason included
  • Runner::get_command_disabled_reason() — new method returning the reason why a command is disabled (e.g. "from the config file") or false if it isn't; is_command_disabled() now delegates to it
SUBCOMMANDS
  check-update       Check for WordPress updates, with optional support for...
  download           Downloads core WordPress files.
  multisite-convert  Transforms an installation into a multisite... (disabled: from the config file)

Trying to run or get detailed help on a disabled command still errors as before.

wp help --full for recursive help output

Adds a --full flag to wp help that recursively outputs help for the specified command and all its non-disabled subcommands, separated by --- dividers — a man-page-style overview of the entire command tree.

wp help core --full      # shows wp core + all core subcommands in one output
wp help --full           # full help for everything (piped through pager)

Internal refactor

show_help() is now a thin wrapper around the extracted get_help_as_string() helper, which get_help_full() uses to accumulate output before a single pager pass.

Test updates

  • features/config.feature: updated assertions to verify (disabled: from the config file) appears in listings
  • features/help.feature: new scenarios for disabled-command visibility with reason and --full behavior
Original prompt

This section details on the original issue you should resolve

<issue_title>Improve user experience of the help screens</issue_title>
<issue_description>This is a placeholder issue for potential improvements to the help screens:

  • Show disabled commands with the reason why they were disabled
  • Extended help view, or a man page
  • Web links in console output

Show disabled commands with the reason why they were disabled

commands-dependency-mockup

From #4035

Extended help view, or a man page

I find that the single-page layout of a man page aids with the discoverability of features of a command. While I'm looking for details of the option I need help with, I often see something that I wasn't previously aware of or had forgotten.

This sort of discoverability doesn't exist in the wp help command as it only lists the top level subcommands. Some form of extended help view which lists the description and complete synopsis for every available command could help with discoverability. A trimmed example is below.

$ man wp
NAME

  wp

DESCRIPTION

  Manage WordPress through the command-line.

SYNOPSIS

  wp <command>

SUBCOMMANDS

  wp cache add <key> <value> [<group>] [<expiration>]
          Add a value to the object cache.

  wp cache decr <key> [<offset>] [<group>]
          Decrement a value in the object cache.

From #4565

Web links in console output

If we want to bridge the gap between the console (where the "product" is being used) and the web (where the "product" is being documented and worked on), we need to define in what form hyperlinks can or should be used in console output.

See #4158</issue_description>

<agent_instructions>I like the "Show disabled commands with the reason why they were disabled" part. Can we just build that?

For the "Extended help view", perhaps if someone does wp help --full we do that? Would be convenient, everything in one place.</agent_instructions>

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

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

@swissspidy
Improve help screens: show disabled commands and add --full flag
623ad14 
- Show disabled commands in help listings with a '(disabled)' indicator
  instead of silently hiding them. This applies to both `wp help <cmd>`
  subcommand listings and `wp <cmd>` usage listings.
- Add `--full` flag to `wp help` that recursively shows help for the
  command and all its non-disabled subcommands, separated by '---'
  dividers. Useful for a 'man page'-style view of all commands.
- Refactor show_help() to extract get_help_as_string() helper for reuse.
- Update Behat tests to reflect new disabled command behavior, and add
  new scenarios for both features.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Agent-Logs-Url: https://github.com/wp-cli/wp-cli/sessions/7f17cb62-25d6-4243-902b-b91c72b3a439
Copilot AI changed the title [WIP] Improve user experience of the help screens Improve help screens: show disabled commands and add --full recursive help Mar 22, 2026
Copilot AI requested a review from swissspidy March 22, 2026 00:22
@swissspidy

This comment was marked as resolved.

Sign in to view
@swissspidy
Show reason why command is disabled in help listings
78424b6 
Add get_command_disabled_reason() to Runner that returns the reason why
a command is disabled (e.g. "from the config file") or false if it isn't.
Refactor is_command_disabled() to delegate to this new method.

Update render_subcommands() in Help_Command and show_usage() in
CompositeCommand to display the reason: "(disabled: from the config file)"
instead of just "(disabled)".

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Agent-Logs-Url: https://github.com/wp-cli/wp-cli/sessions/390953ed-6fff-4d07-8ddd-cba8679902e6

This comment was marked as resolved.

Sign in to view
Copilot AI changed the title Improve help screens: show disabled commands and add --full recursive help Improve help screens: show disabled commands with reason and add --full recursive help Mar 22, 2026
@codecov
Copy link
Copy Markdown

codecov bot commented Mar 22, 2026

Codecov Report

❌ Patch coverage is 0% with 71 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
php/commands/src/Help_Command.php 0.00% 62 Missing ⚠️
php/WP_CLI/Runner.php 0.00% 5 Missing ⚠️
php/WP_CLI/Dispatcher/CompositeCommand.php 0.00% 4 Missing ⚠️

📢 Thoughts on this report? Let us know!

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

command:cli-help

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Improve user experience of the help screens

2 participants

@swissspidy