WP-CLI for coding agents

When a coding agent has shell access to a WordPress project, WP-CLI gives it commands for inspecting and managing the site from the terminal. WP-CLI is the command-line interface for WordPress, and its handbook is part of the official WordPress documentation. Its commands cover posts and users as well as plugins and the database. An agent can use those commands to check a site or prepare a migration without driving a browser. The WP-CLI command reference lists the available commands.

When a WordPress site moves to a new URL, an agent can use WP-CLI to count the database values that would change. WP-CLI’s search-replace --dry-run option previews the replacements without saving them. An agent can report the proposed changes from the preview before anyone runs the write command.

Install and check WP-CLI

On a Unix-like machine with PHP and curl installed, the official WP-CLI installation instructions use the project’s PHAR package, a PHP archive that runs as a command-line program. WP-CLI needs PHP 7.2.24 or later.

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info

The first --info check runs the downloaded file and displays information about WP-CLI and the PHP environment. The final check confirms that the installed wp command runs. The sudo command assumes you want to install WP-CLI in /usr/local/bin; use an installation location that exists and is writable in your environment. The installation guide also explains how to verify the download with a GPG signature before you run it.

To run a site command, change to the WordPress directory that contains wp-config.php, or pass the directory with --path. That file provides WordPress with its database connection settings. WP-CLI has to run where it can reach the WordPress files and database. For a remote site, the guide to running commands remotely uses the --ssh option, which connects over SSH and needs WP-CLI installed on the remote server. Aliases such as @prod are short names for remote environments that you register in wp-cli.yml or ~/.wp-cli/config.yml. Keep credentials outside the agent prompt.

Preview a URL migration

These commands show example URLs and a placeholder path. Replace /path/to/wordpress with the local WordPress directory, and replace the example URLs with the exact old and new site addresses.

cd /path/to/wordpress
wp option get home
wp search-replace 'http://old.example.test' 'https://site.example.test' --all-tables-with-prefix --skip-columns=guid --dry-run

wp option get home reads the site’s configured home URL, and the second command searches database tables with the site’s table prefix to report what it would replace. The search-replace reference says --dry-run runs the whole operation and shows the report, but does not save changes to the database. The exact results depend on the database contents. --skip-columns=guid leaves the guid column of posts alone. The WordPress guide to moving a site says never to change that column, because feed readers use it to recognize posts they have already shown.

WP-CLI handles PHP-serialized data during search and replace. Some themes and widgets store values in that format together with the length of the text, so replacing text directly in database exports can damage stored data when the URL length changes. The WP-CLI command accounts for serialized values while making replacements. It does not change primary key values, and it leaves out tables that have no primary key.

The preview does not change the database. After you review the report and approve the migration, run the same command without --dry-run to write the replacements:

wp search-replace 'http://old.example.test' 'https://site.example.test' --all-tables-with-prefix --skip-columns=guid

That command writes to the database connected to the WordPress installation in the current directory. If the agent targets a remote alias, the command reaches that host and changes its database. Keep the preview and write as separate steps so the agent cannot mistake a proposed migration for an approved one.

Give the agent a bounded task

A useful prompt names the target environment, the exact values to search for, and what the agent may do:

In the local WordPress directory, read the configured home URL and run wp search-replace with --dry-run for http://old.example.test to https://site.example.test, using all tables with the site prefix and leaving out the guid column. Report the replacement counts from the report. Do not run the write command.

Output formats differ between WP-CLI commands. Many commands that list or read data accept --format=json, for example wp option get home --format=json or wp plugin list --format=json. search-replace only offers a table or, with --format=count, the total number of replacements. The agent should check each command’s reference for its formats and report the command’s actual output rather than infer changes from a successful exit. The agent’s access depends on its shell account and the WordPress database credentials available to that installation. Limit the agent’s shell access to the environment and actions it needs.