Using WP-CLI aliases to switch between multiple WordPress environments safely

Anyone managing several WordPress environments — production, staging, or separate installs for different languages — ends up re-typing SSH connection details and install paths every time they run a command. Building that connection string by hand each time invites mistakes: a copy-paste error, or reusing a stale path, can send a command to the wrong environment entirely. That risk matters most for write commands — bulk plugin updates or database operations — where hitting the wrong target has real consequences.

WP-CLI has a built-in feature for exactly this problem: aliases.

Note: A WP-CLI “alias” assigns a short name (like @production) to a set of connection details — an SSH target and a WordPress install path. Once registered, that short name replaces the full connection string on every subsequent command.

Where aliases live

Aliases are registered in one of two config files:

Project-level: wp-cli.yml in the working directory
Global: ~/.wp-cli/config.yml in the home directory

If the same alias name exists in both, the project-level file takes precedence. If the same environments get used across multiple projects, consolidating aliases in ~/.wp-cli/config.yml keeps things easier to manage.

Example registration (config.yml):

@production:
  ssh: user@production.example.com:22
  path: /var/www/production/wordpress

@staging:
  ssh: user@staging.example.com:22
  path: /var/www/staging/wordpress

ssh specifies the username, host, and port; path points to the WordPress install directory. This assumes key-based SSH authentication — passwords should never be written into config.yml. If this file is tracked in a repository, an accidental commit turns it into a leak vector for connection details, so keep it in .gitignore, or store it outside the repository in the home directory instead.

Calling a single alias

Once registered, commands that previously required an ssh login first can run in a single line from your local machine:

wp @production plugin list
wp @staging plugin list

Under the hood, WP-CLI reads the alias’s connection details and runs the command against the remote WordPress install over SSH, streaming the result back to the local terminal exactly as if it had run locally.

Running the same command across multiple environments with group aliases

Individual aliases can also be bundled into a “group alias”:

@all:
  - @production
  - @staging

wp @all plugin list

Running a group alias makes WP-CLI execute the command against every listed alias in turn, labeling each block of output with which alias it came from. There’s no need to retype the same command per environment, and the labeled output makes it easy to trace which result belongs to which site — a form of record-keeping that matters when reviewing what ran where.

Points to watch when using aliases

Aliases trade convenience for a wider blast radius when something is misconfigured. A few things worth keeping in mind:

Name aliases so the environment is obvious at a glance. Short forms like @a or @b become ambiguous the moment you’re not looking at the config file — @production and @staging remove that ambiguity
Get in the habit of running wp cli alias list before executing anything unfamiliar. It shows the currently registered aliases and their targets without needing to open the config file directly
Avoid running write commands through a group alias. Something like wp plugin update --all or a wp db command run against @all can’t be stopped partway if the first environment produces an unexpected result. Read-only commands (plugin list, checking core version, and similar) are a good fit for group execution when you just need a status overview; commands that change state are safer run one alias at a time, with a chance to confirm each result before moving to the next
Consider separating SSH keys by environment. Reusing one key across multiple production environments means a single key compromise affects all of them. Depending on how critical each environment is, splitting keys is worth considering

Summary

What you want to do	Command
List registered aliases	`wp cli alias list`
Run a command against a single alias	`wp @production plugin list`
Run a command across all environments at once	`wp @all plugin list`
Run one environment at a time (safer for write commands)	Execute manually per alias

When working across multiple WordPress environments, registering aliases once tends to prevent more mistakes than building connection strings by hand each time. Group alias output labels which environment produced which result, which makes it well suited to read-only status checks. Bulk-running write commands across environments deserves more caution — in situations where accuracy and traceability matter more than speed, running one environment at a time on purpose is a reasonable choice to keep.

WP-CLI’s ability to reach into WordPress without going through the admin dashboard shows up elsewhere in this series too: inspecting what’s actually scheduled in WP-Cron and recovering from a wp-admin lockout. Aliases extend that same idea to the problem of managing connection details across several environments at once.