Runner::back_compat_conversions() (in php/WP_CLI/Runner.php) silently rewrites a set of pre-1.0 command and flag syntaxes to their modern equivalents. It has always done this without emitting any warning, so a user still on the old syntax gets no signal that it is outdated. Several of these rewrites predate the 1.0 release.
For 3.0.0 the original plan was to remove them outright. That would break existing scripts with a bare "unknown command" and no pointer to the replacement, for syntaxes we never told anyone were deprecated. That is too abrupt.
Decision: deprecate the genuinely-legacy rewrites in 3.0.0 by emitting a deprecation warning that names the modern form, keep the rewrite working through the whole 3.x cycle, and remove them in 4.0.0. This starts the deprecation clock at the major boundary, which is the first time we have ever signalled that these are on the way out.
Deprecate in 3.0.0 (warn, keep working; remove in 4.0.0)
Emit a deprecation warning pointing at the replacement, then apply the existing rewrite as before:
wp sql ... → wp db ...wp blog ... → wp site ...wp {post|comment|user|network}-meta ... → wp {post|comment|user|network} meta ...wp cli aliases → wp cli alias listwp core config → wp config createwp core language → wp language corewp core install|multisite-install --admin_name= → --admin_user=wp checksum core → wp core verify-checksumswp checksum plugin → wp plugin verify-checksumswp site create --site_id= → --network_id=wp {plugin|theme} update-all → wp {plugin|theme} update --allwp transient delete-expired → wp transient delete --expiredwp transient delete-all → wp transient delete --allwp plugin scaffold → wp scaffold pluginwp {post|user} list --ids → wp {post|user} list --format=idswp {post|comment|site|term} url <ids> → wp {post|comment|site|term} list --*__in --field=url
Keep as permanent features (do NOT deprecate)
These live in the same method but are not legacy rewrites. They are the actual implementation of current, documented behavior:
wp <command> --help → wp help <command> (this is how --help is implemented)wp --version / wp --info → wp cli version / wp cli info--json → --format=json (kept as a convenient shorthand, not treated as legacy)- Windows PowerShell space-separated numeric ID splitting (recent cross-platform compatibility work, not legacy)
Mechanism
The declarative @deprecated handling from #6343 does not apply here. Those warnings come from command and argument docblocks, but these conversions run in the Runner before command dispatch and are argument-syntax transforms, not deprecated command metadata. Each warning has to be emitted manually at its conversion site, ideally through one small shared helper so the message format stays consistent (old form, arrow, modern form). The warning goes to STDERR via WP_CLI::warning() and must not change the command's behavior or exit code in 3.x.
Tasks
This makes the 3.0.0 change additive (warnings only), so it does not carry the breaking-change label. The breaking removal moves to 4.0.0.
Runner::back_compat_conversions()(inphp/WP_CLI/Runner.php) silently rewrites a set of pre-1.0 command and flag syntaxes to their modern equivalents. It has always done this without emitting any warning, so a user still on the old syntax gets no signal that it is outdated. Several of these rewrites predate the 1.0 release.For 3.0.0 the original plan was to remove them outright. That would break existing scripts with a bare "unknown command" and no pointer to the replacement, for syntaxes we never told anyone were deprecated. That is too abrupt.
Decision: deprecate the genuinely-legacy rewrites in 3.0.0 by emitting a deprecation warning that names the modern form, keep the rewrite working through the whole 3.x cycle, and remove them in 4.0.0. This starts the deprecation clock at the major boundary, which is the first time we have ever signalled that these are on the way out.
Deprecate in 3.0.0 (warn, keep working; remove in 4.0.0)
Emit a deprecation warning pointing at the replacement, then apply the existing rewrite as before:
wp sql ...→wp db ...wp blog ...→wp site ...wp {post|comment|user|network}-meta ...→wp {post|comment|user|network} meta ...wp cli aliases→wp cli alias listwp core config→wp config createwp core language→wp language corewp core install|multisite-install --admin_name=→--admin_user=wp checksum core→wp core verify-checksumswp checksum plugin→wp plugin verify-checksumswp site create --site_id=→--network_id=wp {plugin|theme} update-all→wp {plugin|theme} update --allwp transient delete-expired→wp transient delete --expiredwp transient delete-all→wp transient delete --allwp plugin scaffold→wp scaffold pluginwp {post|user} list --ids→wp {post|user} list --format=idswp {post|comment|site|term} url <ids>→wp {post|comment|site|term} list --*__in --field=urlKeep as permanent features (do NOT deprecate)
These live in the same method but are not legacy rewrites. They are the actual implementation of current, documented behavior:
wp <command> --help→wp help <command>(this is how--helpis implemented)wp --version/wp --info→wp cli version/wp cli info--json→--format=json(kept as a convenient shorthand, not treated as legacy)Mechanism
The declarative
@deprecatedhandling from #6343 does not apply here. Those warnings come from command and argument docblocks, but these conversions run in the Runner before command dispatch and are argument-syntax transforms, not deprecated command metadata. Each warning has to be emitted manually at its conversion site, ideally through one small shared helper so the message format stays consistent (old form, arrow, modern form). The warning goes to STDERR viaWP_CLI::warning()and must not change the command's behavior or exit code in 3.x.Tasks
--help,--version/--info, and PowerShell ID splitting untouchedThis makes the 3.0.0 change additive (warnings only), so it does not carry the
breaking-changelabel. The breaking removal moves to 4.0.0.