Skip to main content

wp cli alias

Overview

WP-CLI aliases are named shortcuts defined in wp-cli.yml or ~/.wp-cli/config.yml that point to a WordPress installation — local path, remote SSH, or multisite URL. They let you manage any number of environments with a single consistent command interface.

What It Does​

wp cli alias provides subcommands to list, get, add, update, and delete aliases programmatically — without editing YAML files manually.

Subcommands​

SubcommandDescription
wp cli alias listList all defined aliases
wp cli alias get ALIASShow configuration for a specific alias
wp cli alias add ALIASDefine a new alias
wp cli alias update ALIASUpdate an existing alias
wp cli alias delete ALIASRemove an alias

Syntax​

wp cli alias <subcommand> [OPTIONS]

Where Aliases Are Stored​

FileScope
~/.wp-cli/config.ymlGlobal — applies to all projects
wp-cli.yml in WP rootProject-level — applies only to that install

Basic Usage​

List all aliases​

wp cli alias list

Output:

@production
@staging
@local
@all

Get details of an alias​

wp cli alias get @production

Output:

@production:
  ssh: deploy@prod.example.com/var/www/wordpress

Alias Structure in wp-cli.yml​

# ~/.wp-cli/config.yml

@production:
  ssh: deploy@prod.example.com/var/www/html
  path: /var/www/html

@staging:
  ssh: deploy@staging.example.com/var/www/html

@local:
  path: /var/www/local-dev

@docker:
  ssh: docker:wordpress_app/var/www/html

Using Aliases​

# Run a command on the production server via SSH
wp @production cache flush

# Check the WordPress version on staging
wp @staging core version

# List plugins on local
wp @local plugin list --status=active

Real-World Scenarios​

Scenario 1: Sync production to staging​

#!/bin/bash
# sync-prod-to-staging.sh

echo "Exporting production database..."
wp @production db export /tmp/prod-$(date +%Y%m%d).sql

echo "Transferring to staging server..."
scp deploy@prod.example.com:/tmp/prod-*.sql deploy@staging.example.com:/tmp/

echo "Importing on staging..."
wp @staging db import /tmp/prod-$(date +%Y%m%d).sql

echo "Replacing production URLs with staging..."
wp @staging search-replace 'https://prod.example.com' 'https://staging.example.com' --skip-columns=guid

echo "Flushing staging cache..."
wp @staging cache flush

echo "Done!"

Scenario 2: Fleet-wide plugin audit​

for env in @production @staging @local; do
  echo "=== $env ==="
  wp "$env" plugin list --update=available --format=count | xargs echo "  Plugins needing update:"
done

Scenario 3: Deploy to all environments​

for env in @staging @production; do
  wp "$env" maintenance-mode activate
  wp "$env" plugin update --all
  wp "$env" cache flush
  wp "$env" maintenance-mode deactivate
  echo "Updated: $env"
done

Group Aliases (Targeting Multiple Sites at Once)​

# wp-cli.yml

@all:
  - @production
  - @staging
  - @local
# Run on all environments simultaneously
wp @all core version
wp @all cache flush

Docker Container Aliases​

@wordpress-docker:
  ssh: docker:my_wordpress_container/var/www/html
wp @wordpress-docker plugin list

Best Practices​

  1. Store aliases in ~/.wp-cli/config.yml globally so they work across all projects.
  2. Store project aliases in wp-cli.yml in the repo so teammates share them.
  3. Use group aliases (@all) for bulk operations across environments.
  4. Always test commands on @staging before running on @production.
  5. Use SSH key authentication for remote aliases — no password prompts in automation.

Troubleshooting​

ProblemCauseFix
Error: Unknown aliasAlias not in config fileRun wp cli alias list to verify
SSH connection refusedWrong SSH address or portTest with ssh user@host directly
Command runs on wrong siteWrong --path in alias definitionVerify with wp @alias option get siteurl

Quick Reference​

wp cli alias list                     # List all aliases
wp cli alias get @production          # Show alias config
wp @production cache flush            # Use alias
wp @staging core version              # Target staging

Next Steps​