Expose context sensitive help about any relevant CLI commands

Thanks for the suggestion. Moving the parent to the initiative meta, not the phase 1 implementation issue.

Wonder if we can/should extend the AsCommand attribute to have a parameter for the route where the help text should appear? It seems natural when defining the command to put the route info directly there. We don't want a hard-coded list somewhere in core, since that makes it impossible for contrib to extend this for its own commands.

The Symfony ListCommand is used by Symfony to list all available commands.

It's execute implementation is

        $helper = new DescriptorHelper();
        $helper->describe($output, $this->getApplication(), [
            'format' => $input->getOption('format'),
            'raw_text' => $input->getOption('raw'),
            'namespace' => $input->getArgument('namespace'),
            'short' => $input->getOption('short'),
        ]);

If I dig into that then there are MarkdownDescriptor and ReStructuredTextDescriptor implementations. Those seem like good basis to convert to HTML.

In theory having DrupalApplication and passing it to the helper should get you all the description output you need.

There's one complexity which is making sure DrupalApplication has performed its command discovery. DrupalApplication currently adds its commands from discovery only when it's being bootstrapped. However the bootstrap also assumes it's bootstrapping Drupal, that doesn't need to happen in a UI request because we already bootstrapped Drupal elsewhere.

If you have patience then blocking this issue on some of the child issues from #2282779: [meta] DrupalKernel has too many responsibilities that I'm working on would solve that. Particularly moving the bootstrap and settings from DrupalKernel into the runtime. If you don't have patience then making the bootstrap code resilient to being in a bootstrapped Drupal environment and/or splitting up the command discovery from that would be a problem to overcome.

Although I previously replied with some encouragement and possible suggestions, the more I ponder this issue, the less I think it should be implemented (at least in Core). 😅

1. Nearly every command is doing something there's already a UI for. The UI is spread throughout the Drupal backend, so the specific forms/buttons are all over the place. But each action already has a UI, and a UX, etc. Having a single page with a ton of (mostly unrelated) actions that you could do via the CLI seems a little overwhelming and not necessarily clear.
2. If the point is to provide contextually-aware blocks that notice you're on the page to do action X and that action also has a CLI command, I'm not clear how we'll know what action(s) could be triggered from the page we're on. Seems we'd need something yucky like comment #3 for this, but then this becomes much more Drupalism-y. We can no longer claim "Symfony commands work in Drupal". Now it becomes "Symfony commands work in Drupal if you Drupal-ify them", which is less appealing.
3. Any installed module could be adding more commands, so whatever UI this becomes needs to be able to scale to dozens or potentially 100+ commands. Yikes.
4. Some commands are implemented as CLI commands for security-in-depth. If the site codebase is not owned by the same system user that the web server is running as (the best-case scenario for better security!), some commands may only work via the CLI, and attempting to run them via the GUI would fail due to permission issues.
5. Each command potentially takes different arguments and options. If this UI lets you run commands, it's going to have to know quite a bit about each command to accept the right kinds of inputs. As described in the summary, this is a read-only list of available commands. But I think I saw some talk in Slack about being able to trigger commands from the UI, too.

So my suggestion would be that if folks are interested in this, it should start as a contrib module. There's no reason this has to be in Core itself. If it's a contrib project, the author(s) can iterate much more quickly than Core. Once someone works out some of the UI problems, see if this is viable and useful, and folks are installing it on real sites and getting real value, we can always move that code into Core at a later date. But for now, I'd either call this issue targeting Core "Postponed" or "Won't fix"...

Thanks/apologies,
-Derek

We have agreement between the subsystem maintainers (dww and I).

OK, reopening, retitling, and affiliating with the help component. This needs some refinement for UX, and then technical details should be relatively easy to work out.

I was thinking, rather over thinking this, with an interface to expose routes for commands to display help on, but adding to hook_help would be much easier and already does that.

We would want to remember to make this a check/suggestion for command authoring in core.

Usability review

We discussed this issue for the first time at #3592819: Drupal Usability Meeting 2026-06-26. The link to the recording: https://www.youtube.com/watch?v=AVUZmx8Fwm8. The attendees at the usability meeting were @rkoller, and @worldlinemine.

We discussed this issue for a second time with a bigger group at #3608083: Drupal Usability Meeting 2026-07-10. The link to the recording: https://www.youtube.com/watch?v=qnUirvZ9VmE. The attendees at the usability meeting were @benjifisher, @rkoller, @simohell, and @worldlinemine.

In general, the group was in line with the idea proposed in this issue. It solves the underlying germinal problem summarized by the following statement by @worldlinemine: "You don't even know what you don't know". So to whom would a feature like that provide any benefit?

• People who are new to Drupal, in particular those who are less technical.
• Advanced users who are not following core development that closely and/or skimming change logs briefly.

But on the other hand, as soon as such a block would be available to users with, for example, the Administrator role as suggested in the issue summary, that information could turn into a perceived clutter/noise sooner than later.

• For people that know Drupal inside out, that piece of information is self-evident, and having such a block with one to many commands would soon be perceived more like an unnecessary noise than an actual help.
• For people that know Drupal well but who also have either a small working memory and/or are insecure about their ability to remember things in general, such an informational block could sometimes be an appreciated safety net, but most of the time it would still be perceived as unnecessary noise.

So on one hand, it would be helpful to make such an informational block available via (a) certain role(s), but on the other hand, it is currently impossible to adjust the visibility within that given group of people on a per user basis catering to the different individual needs and preferences. And finally, looking at the initial mockup in #8, there are a few details to denote (*the following is not intended as a critique about the mockup it was a very helpful primer to spark the discussion).

• The content of the block does not really stand out from the help text. Help texts are rarely thoroughly read in full, and by appending an additional "blob" of text to that help text might lead to it going unnoticed - in consequence, the mockup illustrates that the block needs some bespoke styling to stand out and make it easily notice- and skim-able at the same time.
• The concept of CLI is not necessarily familiar to everyone; to some people, CLI might be just a sort of cryptic abstract acronym. In consequence, also, not everyone knows what to do with that kind of information and where to actually apply it.
• The command that is provided is also incomplete; it is missing dr and it is also not necessarily clear to everyone that the word in parentheses mset is just an alias and shorthand for maint:set.

In consequence, the group had a clear consensus about the following recommendations:

1. Provide a reusable block only on pages that contain functionality that could also be triggered within the CLI. And why a block? It provides the following two features out of the box:
   • The role visibility setting ensures that only a specific sub-group of people is able to see the block. Per default the role should be set to Administrator as suggested in the issue summary, but site builders and administrators are then still able to adjust the visibility of that block to the general needs of their user base and role structure later on.
   • The block can be placed within the help section on the block layout page (admin/structure/block) right after/underneath the Help block - semantically that would be the most obvious and straight forward choice. Again, site builders and administrators are still able to adjust the position within the page to their own needs later on.

   Content wise, the goal should be that the content is easily recognize- and skim-able. We came up with the following iteration on the mockup based on the page for the maintenance mode (*it was simply chopped together in the source mode of the ckeditor body field of a content block - in general the entire block would require design input).
   
   Within the title we've provided an explanation for the abbreviation CLI and added where to use the commands within the blocks description/help text - ideally it should be just the title, but that would probably require the glossary functionality outlined in point 3. In contrast to the screenshot each set of command and description should be in a single line and we would recommend using the dl element for wrapping the entire list of available commands; the commands should then be wrapped in dt elements, and the descriptions wrapped in dd elements.

2. It is always desirable to provide more than a single touchpoint for users to learn about new information and/or look up and refresh already known details. That is why, aside the addition of a context sensitive block to a page in point 1 we would also recommend adding a dedicated section about Drupal CLI to the main help page on admin/help. It should provide a list of all the commands (and their descriptions) for dr that are currently available in Drupal core. That way there wouldn't be any need for the user to leave the admin UI in search for information about how to accomplish certain tasks within the CLI - everything is available either in the context of the current page or is within reach on the help page. Point 2 is clearly out of the scope for the current issue and would require a dedicated follow-up issue.
3. As already mentioned earlier in this summary, as soon as the context sensitive block would be available to users with for example the Administrator role, that information rather sooner than later could turn into being perceived as clutter. From our point of view the solution would be the introduction of a user based visibility setting where the user is able to decide if the context sensitive block should be either:
   • ...completely hidden
   • ...replaced by a toggle button enabling the user to show and hide the information in a popover - the default should be hidden
   • ...always shown

   We are well aware that the introduction of that kind of functionality and the amount of work necessary to implement it, just for the sake of a context sensitive Drupal CLI block, would be sort of overeager and unjustified. But we had the broader picture in mind, and that pattern would provide the opportunity that it could be utilized in at least two more relevant contexts:

   • Descriptions - The Drupal admin UI is heavy on micro copy. Aside from labels, you also have a lot of help texts and descriptions, and in consequence, the user has to do a lot of reading. For people new to Drupal, its inner workings, and its concepts, that information is absolutely mandatory, but on the other hand, again from the perspective of experienced users on the other hand, those descriptions are rather considered as noise, and they are most likely phased out cognitively in the daily interaction - the cognitive load would be too high. By introducing a user-based setting, it would let the user choose if they want to completely hide those descriptions and help texts and streamline the interface, or if there should be a toggle button as a fallback to still being able to access that information via a popover, or if they prefer the current state and want to display all the descriptions and help texts all the time.
   • Glossary - The acronym CLI already illustrated one fundamental problem in the daily usage of Drupal: there are many terms for all the different abstract concepts it harbors, some from the general tech domain like CLI, but also many very specific to Drupal, aka Drupalisms that make the onboarding for even tech-savvy folks anything but flawless. One of the artifacts we've agreed on in the context of the Drupalism working group a few months ago, the group is on hiatus for a while now, was to create a glossary for all the terms used in the context of Drupal. That would provide the opportunity to add a user-based setting for glossary terms, they could be either disabled or when enabled, if a term is contained in the glossary it could be wrapped in a dt element and the corresponding definition wrapped in a dd element and it could accessed for example in a popover. Same as adding the list of available commands for Drupal CLI, the glossary could be added to a dedicated section on admin/help as well.

   Each of the three scenarios would benefit from having the described user-based setting, but each of the scenarios would require at least a dedicated follow-up issue - same as point 2, all the aspects of point 3 are completely out of the scope for this issue.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.