2026年10月16日

WP-CLIのエイリアス（@alias）を設定して複数サーバーのWordPressを操作する方法

カスタマイズ

WP-CLI のエイリアスを設定すると、wp @prod plugin list のように頭に @名前 を付けるだけで、手元のPCからSSH越しに本番やステージングのWordPressを操作できます。毎回サーバーにログインしてディレクトリを移動する手間が減り、複数のサイトに同じコマンドを流すこともできます。この記事では、設定ファイルの置き場所と書き方、SSHの準備、グループの使い方、つまずきやすい点と安全な運用方法を説明します。

エイリアスの仕組み

エイリアスは「接続先（SSHのホスト）」と「WordPressの場所（パス）」に名前を付けたものです。wp @prod core version を実行すると、手元の WP-CLI が SSH で本番サーバーに接続し、サーバー上の WP-CLI に同じコマンドを実行させて、結果を手元に表示します。

このため、次の2点が前提になります。

手元のPCから対象サーバーへ SSH でログインできること（パスワードではなく鍵認証が扱いやすい）
接続先のサーバーにも WP-CLI がインストールされ、wp コマンドとして実行できること

ここで紹介する書き方は WP-CLI 2系を前提にしています（2026年10月現在）。設定項目や wp cli alias のサブコマンドはバージョンで変わることがあるため、手元で wp help cli alias も確認してください。

SSH接続を先に整える

エイリアスで失敗する原因の多くは、WP-CLI ではなく SSH の設定にあります。まず、普通の SSH でログインできるかを確認します。

接続先の情報は ~/.ssh/config にまとめておくと、エイリアス側の記述を短くできます。

# ~/.ssh/config の例（ホスト名・ユーザー名・鍵は環境に合わせる）
Host prod
    HostName prod.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519_prod

Host staging
    HostName staging.example.com
    User deploy
    IdentityFile ~/.ssh/id_ed25519_staging

# ログインと、サーバー側の wp が使えるかを確認
ssh prod 'wp --info'

この確認で wp: command not found になる場合は、サーバー側の WP-CLI が、SSHでコマンドを実行したときのPATHに入っていません。対話的にログインしたときは使えるのにこのコマンドだけ失敗する、というのはよくある症状です。/usr/local/bin/wp のように、標準でPATHが通っている場所に配置すると解消しやすくなります。

鍵にはパスフレーズを設定し、ssh-agent で読み込んで使うと、鍵ファイルが漏れたときの被害を抑えられます。

設定ファイルにエイリアスを書く

エイリアスは YAML 形式の設定ファイルに書きます。置き場所は2種類あります。

~/.wp-cli/config.yml：自分のPC全体で使うグローバル設定
wp-cli.yml：プロジェクトのディレクトリに置く設定。実行したディレクトリから上の階層へ向かって探されます

個人で複数の案件を扱うならグローバル設定、チームで同じ接続先を共有するならプロジェクトの wp-cli.yml が向いています。

# ~/.wp-cli/config.yml の例
@prod:
  ssh: prod/var/www/example.com/public_html
  url: https://example.com

@staging:
  ssh: staging/var/www/staging.example.com/public_html
  url: https://staging.example.com

@local:
  path: /home/me/sites/example
  url: http://example.test

ssh: は ユーザー@ホスト:ポート/WordPressのパス の形で書きます。上の例では ~/.ssh/config の Host prod を使っているため、ホスト名の部分は prod だけで済み、その直後にWordPressのディレクトリを続けています。~/.ssh/config を使わない場合は deploy@prod.example.com:22/var/www/example.com/public_html のように書きます。path: だけを指定したエイリアスは、手元のPC上のWordPressを指します。

url: はマルチサイトで対象サイトを決めるときや、URLを使うコマンドの基準になります。シングルサイトでも書いておくと、どのサイトの設定かが一目で分かります。

エイリアスを使ってみる

まず、読み取りだけのコマンドで接続を確認します。

# 登録済みエイリアスの一覧
wp cli alias list

# 接続確認
wp @prod core version
wp @staging plugin list --status=active

エイリアスはコマンド名より前、wp の直後に書きます。wp plugin list @prod の順では認識されません。

コマンドで追加・変更する

設定ファイルを直接編集する代わりに、wp cli alias のサブコマンドでも追加できます。

wp cli alias add @dev --set-ssh=deploy@dev.example.com --set-path=/var/www/dev
wp cli alias get @dev
wp cli alias delete @dev

どの設定ファイルに書き込まれるかは指定やバージョンによって異なるため、追加後に wp cli alias list で反映を確認してください。

グループで複数サイトに同じコマンドを流す

エイリアスを束ねたグループを作ると、1回のコマンドで複数の接続先に実行できます。

@sites:
  - @prod
  - @staging

# 両方のWordPressのバージョンを確認
wp @sites core version

# 定義済みのエイリアスすべてに実行（読み取り系から使う）
wp @all plugin list --update=available

@all は定義したすべてのエイリアスが対象になる特別な名前です。更新や削除など変更系のコマンドを @all やグループに流すと、すべての環境が一度に変わります。変更系は1つずつ実行するか、ステージングで結果を確認してから本番に流す運用にしてください。

よく使う組み合わせ

本番のデータベースを手元に持ってくる

# 手元のバックアップを取ってから、本番のDBを手元に流し込む
wp @local db export ~/backup/local-before-pull.sql
wp @prod db export - | wp @local db import -

# 手元のURLに置き換える（まず dry-run）
wp @local search-replace 'https://example.com' 'http://example.test' --skip-columns=guid --dry-run

本番のデータベースには会員情報や問い合わせ内容などの個人情報が含まれることがあります。手元のPCに持ち出してよいか、社内の取り扱いルールを先に確認し、作業後は不要なダンプファイルを削除してください。逆方向（手元から本番への上書き）は影響が大きいため、エイリアスがあるからといって気軽に実行しない運用が安全です。

一時的な接続には --ssh

設定ファイルに書くほどでもない接続先には、グローバル引数 --ssh= でその場だけ指定できます。

wp --ssh=deploy@old.example.com/var/www/html core version

つまずきやすい点と確認方法

「エイリアスが見つからない」旨のエラー：設定ファイルの場所と、YAML のインデント（スペース2つ）を確認します。プロジェクトの wp-cli.yml は、そのディレクトリ配下で実行したときだけ読み込まれます。
接続できない：ssh prod 単体でログインできるかを先に確かめます。踏み台サーバーを経由する環境では、~/.ssh/config の ProxyJump で経路を設定すると、エイリアス側は変えずに済みます。
別のWordPressが操作される：ssh: のパス部分が間違っていると、サーバー上の別ディレクトリが対象になることがあります。wp @prod option get home で対象のURLを確認する習慣をつけると誤操作を防げます。
日本語の出力が文字化けする：サーバー側のロケール設定の影響を受けることがあります。読み取り結果をファイルに保存して確認すると原因を切り分けやすくなります。

設定ファイルの管理と安全面

エイリアスの設定ファイルにはホスト名やユーザー名、ディレクトリ構成が書かれます。パスワードや秘密鍵そのものは書かず、認証は SSH の鍵に任せてください。チームで wp-cli.yml を Git 管理する場合も、鍵ファイルや個人の接続設定は含めず、各自の ~/.ssh/config に置く形にすると、メンバーの入れ替わりにも対応しやすくなります。退職者や外部委託先の鍵は、サーバー側の authorized_keys から速やかに外します。

まとめ

エイリアスは「SSHの接続先」と「WordPressのパス」に名前を付けたもので、wp @名前コマンド で使う
先に ssh ホスト 'wp --info' でSSH接続とサーバー側の WP-CLI を確認する
個人用は ~/.wp-cli/config.yml、チーム共有はプロジェクトの wp-cli.yml に書く
グループや @all は便利だが、変更系のコマンドは1環境ずつ確認しながら実行する
本番データを手元に持ってくるときは個人情報の扱いに注意し、認証情報は設定ファイルに書かない