When running `wp scaffold package-readme`, the output of `README.md` is incomplete if the custom package is not installed

[baizmandesign]

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

I created a custom package containing a command named "bzmn." When I am in the directory containing the source, and I run wp scaffold package-readme ., the output in README.md is substantially truncated. For an example, please refer to README - without bzmn custom command installed.md. Command descriptions, options, and examples are all absent.

If I install the bzmn custom command via wp package install ., then run wp scaffold package-readme ., the output is complete. For an example, please refer to README - with bzmn custom command installed.md.

If you diff the files, the issue is glaring.

It seems to be the case that the README information is only correct (comprehensive, as in the second example) if the custom package is installed on the system. If it isn't installed, you get the incomplete "style" of README, as in the first example. Is that behaviour intentional? If so, is that desirable? My expectation is that the wp scaffold package-readme . command only sees and operates on the files in the current directory. If the developer's custom package needs to be installed for the package-readme subcommand to work, it may be helpful to note that in the documentation.

Since a developer running the command to generate the README probably already has the package installed, this issue may have been overlooked. I only encountered the issue when creating a Docker container to automatically generate the README. The container, of course, didn't have my custom package pre-installed, and it took a bit of time to figure out why the command output wasn't the same as on my local computer, when the commands themselves were identical.

Let us know what environment you are running this on

The output of wp --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

[swissspidy]

Hi there,

Thanks for your report!

It sounds like some clarification in the documentation is in order.

Indeed, the scaffold package-readme command requires your command to be loaded by WP-CLI in order to fetch all the documentation etc. for the readme. The alternative would be some static analysis of the codebase, but we don't do that.

That doesn't mean you have to use wp package install though.

Typically, packages like yours have a wp-cli.yml file in the root with content like this:

require:
  - bzmn.php

Then, when you run wp scaffold package-readme . in your package folder, WP-CLI will read that file and load your command. The generated README then has the full contents in it as expected, I just tested it.

Tip: if you wanna keep the "There are a few automated processes. [...]" section at the end, check out the note regarding custom sections.

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: The service is temporarily unavailable. Please try again later.

[baizmandesign]

@swissspidy Thanks for your response. And I agree, the documentation should be updated to reflect that the package needs to be loaded either by installing it or by requiring it via wp-cli.yml.

When I added a wp-cli.yml file to my project and ran wp scaffold package-readme ., I received this error message:

Error: Callable "baizman_design_cli\\cli" does not exist, and cannot be registered as `wp bzmn`.

I suspect it's because I'm relying on Composer's autoloader, and the required vendor directory and its contents didn't exist. Running composer dump-autoload resolved the issue. I guess what I'm saying is that simply requiring the main package file does not guarantee the correct operation of the wp scaffold package-readme command.

A few thoughts:

• Yes, of course it would be great to update the documentation. Could we provide examples of "loading" the plugin in all three scenarios (installing the command, requiring it via wp-cli.yml, or requiring it via wp-cli.yml and doing a Composer autoload "refresh")?
• You mentioned the package-readme subcommand isn't using static analysis. But it's clearly pulling some information from the source, no? Isn't the contents of the "incomplete" README.md (from the first the scenario in my initial comment) evidence of this?
• My biggest question is around failure and why the package-readme subcommand didn't simply fail when I ran it and my package wasn't loaded. In my case, my package included a command, and it would have been trivial to check whether the command was visible to WP CLI before attempting to generate the documentation. (The has-command subcommand can do this.) But, I realize, not every package contains a command. I guess my question is this: is there any way to provide an error to the user if they try to run wp scaffold package-readme and their package isn't loaded?

I have one or two other thoughts / questions, but they're minor.

Oh, and thanks for the tip! I really appreciate it. (I'd seen one could add custom sections to the README.md file and have been meaning to revise the one for this package.)

[swissspidy]

You mentioned the package-readme subcommand isn't using static analysis. But it's clearly pulling some information from the source, no?

It loads some information from composer.json, yes. See:

scaffold-package-command/src/ScaffoldPackageCommand.php

Lines 262 to 296 in 233838d

	$bits = explode( '/', $composer_obj['name'] );
	$readme_args = [
	'package_name' => $composer_obj['name'],
	'package_short_name' => $bits[1],
	'package_name_border' => str_pad( '', strlen( $composer_obj['name'] ), '=' ),
	'package_description' => isset( $composer_obj['description'] ) ? $composer_obj['description'] : '',
	'branch' => $branch,
	'required_wp_cli_version' => ! empty( $composer_obj['require']['wp-cli/wp-cli'] ) ? str_replace( [ '~', '^', '>=' ], 'v', $composer_obj['require']['wp-cli/wp-cli'] ) : 'v1.3.0',
	'shields' => '',
	'has_commands' => false,
	'wp_cli_update_to_instructions' => 'the latest stable release with `wp cli update`',
	'show_powered_by' => isset( $composer_obj['extra']['readme']['show_powered_by'] ) ? (bool) $composer_obj['extra']['readme']['show_powered_by'] : true,
	];
	if ( isset( $composer_obj['extra']['readme']['shields'] ) ) {
	$readme_args['shields'] = implode( ' ', $composer_obj['extra']['readme']['shields'] );
	} else {
	$shields = [];
	if ( file_exists( $package_dir . '/.github/workflows/testing.yml' ) ) {
	$shields[] = "[](https://github.com/{$readme_args['package_name']}/actions/workflows/testing.yml)";
	}
	if ( file_exists( $package_dir . '/.travis.yml' ) ) {
	$shields[] = "[](https://travis-ci.org/{$readme_args['package_name']})";
	}
	if ( file_exists( $package_dir . '/.circleci/config.yml' ) ) {
	$shields[] = "[](https://circleci.com/gh/{$readme_args['package_name']}/tree/{$branch})";
	}
	if ( file_exists( $package_dir . '/codecov.yml' ) ) {
	$shields[] = "[](https://codecov.io/gh/{$readme_args['package_name']}/tree/{$branch})";
	}
	if ( count( $shields ) ) {
	$readme_args['shields'] = implode( ' ', $shields );
	}
	}

My biggest question is around failure and why the package-readme subcommand didn't simply fail when I ran it and my package wasn't loaded.
is there any way to provide an error to the user if they try to run wp scaffold package-readme and their package isn't loaded?

That's a good point, we should do that. This would be a better experience than silently passing and giving you a half-baked readme.

Here we're looping through the commands defined in composer.json:

scaffold-package-command/src/ScaffoldPackageCommand.php

Lines 309 to 333 in 233838d

	$cmd_dump = WP_CLI::runcommand(
	'cli cmd-dump',
	[
	'launch' => false,
	'return' => true,
	'parse' => 'json',
	]
	);
	foreach ( $composer_obj['extra']['commands'] as $command ) {
	$bits = explode( ' ', $command );
	$parent_command = $cmd_dump;
	do {
	$cmd_bit = array_shift( $bits );
	$found = false;
	foreach ( $parent_command['subcommands'] as $subcommand ) {
	if ( $subcommand['name'] === $cmd_bit ) {
	$parent_command = $subcommand;
	$found = true;
	break;
	}
	}
	if ( ! $found ) {
	$parent_command = false;
	}
	} while ( $parent_command && $bits );

When doing that, we can simply throw an error if the command was not found by WP-CLI