WP-CLI¶

List, add and remove pins from the command line, for one site or in a script for many. The commands do the same as the Pins tab under Tools → Version Pin. The WordPress pin is set on that tab only.

wp version-pin list¶

Lists every pin, one row per plugin:

wp version-pin list

--format¶

--format=table (the default), json, csv, yaml or count. For a script, use json:

wp version-pin list --format=json

count prints the number of pins.

wp version-pin add¶

Pins a plugin, or replaces its pin if it already has one:

wp version-pin add <plugin> [<version>] [--mode=<mode>] [--note=<note>]

Examples:

wp version-pin add akismet
wp version-pin add classic-editor 1.6.6 --mode=exact --note="Signed off on this version."
wp version-pin add old-plugin/old-plugin.php 1.4.0

On success: "Success: Pinned Akismet Anti-spam: Spam Protection at 5.3.7 (patch)."

<plugin>¶

The plugin's folder name, such as akismet, or its basename, such as akismet/akismet.php.

<version>¶

The highest version allowed. Default: the installed version. The same rules apply as on the screen: a version starts with a digit and may hold digits, letters, dots and the characters +, _ and -, up to 40 characters. Otherwise the command stops: 'Error: "latest" is not a version number. Use digits and dots, for example 5.1.4.' A wildcard such as 5.x is refused too: 'Error: "5.x" is a wildcard. Type a version, for example 5.1.4: a patch-only pin also allows the later releases in its series.'

--mode¶

patch also allows releases in the pinned series; exact allows nothing newer. Default: patch when the version has a series, otherwise exact. Asking for patch on a version without a series pins it as exact, with a warning: "Warning: 3 cannot be read as a series, so the pin is treated as exact." See How it works.

--note¶

Why the plugin is pinned. Shown on the Plugins screen and wherever an update is refused. At most 200 characters.

A plugin that is not installed¶

To hold a plugin that is not installed yet, so that it can only be installed at a version the pin allows, give its basename and a version:

wp version-pin add example-plugin/example-plugin.php 2.4.1

The command warns "Warning: example-plugin/example-plugin.php is not installed. The pin applies when it is installed." and the pin shows Missing until the plugin is installed. Without a version, the command stops: 'Error: No installed plugin matches "example-plugin". To pin a plugin that is not installed, give its basename and a version.'

wp version-pin remove¶

Removes a pin, so the plugin updates as usual again:

wp version-pin remove akismet

On success: "Success: Removed the pin on Akismet Anti-spam: Spam Protection." For a plugin without a pin: 'Error: "akismet" is not pinned.'

Exit codes¶

Like every WP-CLI command, wp version-pin exits with 0 on success and 1 on an error, so a script can stop on a failed command. A warning does not change the exit code.

Updates from WP-CLI¶

wp plugin update, wp plugin install --force and wp core update respect the pins, and there is no flag to get past one. See WP-CLI on What a pin blocks.

WordPress core¶

wp version-pin pins plugins only. Pin WordPress on the Pins tab: see Settings.

Multisite¶

On a multisite network, list and add warn: "Warning: Version Pin does not support multisite yet. Pins are stored but nothing is enforced on this network." See Multisite.

Related¶

• What a pin blocks: what happens when an update meets a pin.
• Settings: the same pins on the screen.