How WP-CLI Aliases Supercharge Your Agents

As much as I love skills, MCPs, APIs, and so on, nothing really beats the combination of a coding agent with the WordPress CLI. If you aren’t familiar with WP-CLI, I give an intro to it in my video series on WordPress developer tools.

With WP-CLI running, your LLM can check settings, update content, compare environments, run migrations, and even test arbitrary PHP snippets without relying on browser automation.

When I’m developing locally, I run WP-CLI from the root of the WordPress installation. Recently, however, I’ve been using use CLI aliases for my production environments:

wp plugin list
wp @prod plugin listCode language: PHP (php)

Getting to that point requires four pieces of setup: SSH access to the server, an SSH config entry, WP-CLI on your local computer, and WP-CLI aliases.

After that, I document the commands and safety rules in your project’s AGENTS.md file, letting it know when to use my production alias and run commands on the live site.

1. Get SSH access to the server

First, you need SSH access to the server where the remote WordPress site is hosted. Your hosting company should provide the hostname, username, port, and authentication method.

Make sure you can connect before configuring anything else:

ssh username@example.comCode language: CSS (css)

Once connected, find the path to the WordPress installation and confirm that WP-CLI is available on the server:

cd /path/to/wordpress
wp core version

This second check matters because WP-CLI proxies remote commands through SSH. Your local WP-CLI command connects over SSH and asks the server to run its own wp command. If your host doesn’t include WP-CLI, I’d look into a new host, or installing it yourself (if you run your own hosting environment).

At the end of this step, you should know:

• The SSH hostname
• The SSH username
• The SSH port, if it is not port 22
• How you will authenticate, usually with an SSH key
• The full path to the WordPress installation and if WP-CLI is installed.

2. Add the connection to your SSH config

Next, I recommend putting the connection details in ~/.ssh/config. This lets SSH handle the hostname, username, port, and key without requiring you—or an agent—to repeat them in every command.

For example, your SSH settings might look something like this:

Host example-prod
    HostName example.com
    User username
    Port 22
    IdentityFile ~/.ssh/id_ed25519_example
    IdentitiesOnly yesCode language: JavaScript (javascript)

The value after Host is your local nickname for the connection. It does not need to match the site’s domain. I prefer names that include the environment, such as example-prod or example-staging.

Test the new entry:

ssh example-prodCode language: Shell Session (shell)

If that works, the lower-level SSH details are now handled by your SSH configuration. You can also keep hostnames, usernames, ports, and key paths out of project files that may be committed to a repository.

The important note is that SSH keys and credentials should never be added to AGENTS.md files or wp-cli.yml or visible to your agent.

3. Install WP-CLI on your local computer

You also need WP-CLI installed locally. This is the wp command you will run in your terminal and the command your local coding agent will use.

Confirm that it is installed and available on your path:

wp --info

The output should show the local WP-CLI version and the PHP binary it is using.

At this point, WP-CLI should be available in two places:

• On your local computer, where you and your coding agent run commands
• On the remote server, where commands sent over SSH are executed

If you only plan to use a local WordPress site, the remote installation is irrelevant. It is required when using an SSH-based alias for production or staging.

4. Create WP-CLI aliases for remote sites

Now add aliases for the remote WordPress environments you want to use. WP-CLI aliases can live in a project’s wp-cli.yml file or your global ~/.wp-cli/config.yml file.

I use the global file for aliases tied to my computer because they depend on my SSH configuration.

A basic configuration looks like this:

@prod:
  ssh: example-prod
  path: /path/to/wordpressCode language: JavaScript (javascript)

The @prod alias refers to the example-prod entry from ~/.ssh/config and specifies the WordPress path on that server.

I do not normally create an alias for local development. When I am in the root of a local WordPress installation, I can run wp directly. If I need to run a local command from another directory, I can make an alias or just pass the path explicitly:

wp --path=/path/to/local/wordpress plugin listCode language: JavaScript (javascript)

But this is usually not necessary for the way I usually work.

You can also group aliases together, which lets you run one command across multiple environments. The WP-CLI configuration documentation lists the available alias settings.

Start by testing read-only commands:

wp core version
wp @prod core version

wp option get home
wp @prod option get homeCode language: JavaScript (javascript)

Run the commands without an alias from the local WordPress root. If both local and production return the expected values, the setup is complete:

wp <command>
wp @prod <command>Code language: HTML, XML (xml)

The WP-CLI command reference is useful for checking the available commands and their supported arguments before adding more examples to your project instructions.

Tell your coding agent how to use the aliases

The last step is to document the commands in your project’s AGENTS.md file. The agent needs to know how to run WP-CLI locally, which aliases point to remote environments, and what it is allowed to do with them.

Here is a starting point:

## WordPress environments

- Run local WP-CLI commands with `wp` from the root of the local WordPress site.
- Use `wp @prod` for production.
- Run commands locally by default.
- Production access is read-only unless I explicitly approve a write.
- Before a production write, show me the exact command and explain what it
  will change.
- Use `--dry-run` first when the command supports it.
- Never run destructive database or content commands against production.
- Prefer `--format=json` for list data that needs further processing.Code language: CSS (css)

I normally run wp from the root of the local site, and that’s generally where I start my Claude Code or Codex session, too. The point is to record the exact working command instead of making each new agent session determine how the environment is configured.

The completed setup

Once these pieces are in place, the responsibility of each file is fairly clear:

• ~/.ssh/config handles the server connection.
• ~/.wp-cli/config.yml names the remote WordPress environments.
• Each project’s AGENTS.md tells the coding agent which commands to use and where the permission boundaries are.

Once this is set up, your agent has deep access to your WordPress site. Ask it to do an SEO audit and it can check active plugins, configuration settings, post meta descriptions, etc. Deploy a new plugin and have your agent run the set up and migration. Write a bash script with reusable tasks that an agent can execute for you on demand.

With the new wp block command your agent can even interact with your blocks, bindings, patterns, styles, templates, and more.

Let me know what you’re doing with WP-CLI!