よく使う WP-CLI コマンドは、composer.json の scripts に登録しておくと composer wp:check のような短い名前で呼び出せます。チーム全員が同じ手順を同じコマンドで実行でき、CI からも同じ名前で呼べるのが利点です。この記事では WP-CLI をプロジェクトの開発用依存として入れる方法から、スクリプトの定義、引数の渡し方、wp-cli.yml との組み合わせ、自作コマンドの登録、タイムアウトや Windows での注意点までを順に説明します。
どんなプロジェクトで役に立つか
Composer スクリプトが向いているのは、WordPress のサイトやテーマ・プラグインを Git リポジトリで管理し、composer.json がすでにある（または置ける）プロジェクトです。たとえば次のような作業を名前付きでまとめられます。
- デプロイ後の定型処理（データベースの更新、キャッシュとリライトルールのクリア）
- コアやプラグインのファイルが改ざんされていないかの検証
- 開発環境のデータベースの書き出しや、URLの置換（ドライラン付き）
「手順書を見ながらコマンドを1つずつ打つ」作業を減らし、打ち間違いや手順の抜けを防ぐのが目的です。
WP-CLIをプロジェクトに入れる
WP-CLI はサーバーにグローバルで入れる方法（phar ファイル）が一般的ですが、Composer で開発用依存として入れると、プロジェクトごとに版をそろえられます。
composer require --dev wp-cli/wp-cli-bundlewp-cli-bundle は WP-CLI 本体と標準コマンド群をまとめたパッケージです。インストールすると vendor/bin/wp が作られます。Composer はスクリプトを実行するとき vendor/bin（bin-dir）を一時的に PATH の先頭に加えるため、スクリプトの中では単に wp と書くだけでこのプロジェクトの WP-CLI が使われます。
注意点として、wp-cli-bundle は多くの依存パッケージを含むため、プロジェクト側の依存と版が衝突することがあります。衝突して解決できない場合は、Composer では入れずにサーバーのグローバルな wp を使う形でも、以下のスクリプト定義はそのまま使えます（PATH 上の wp が呼ばれます）。
基本のscripts定義
composer.json に scripts を追加します。値は文字列（コマンド1つ）か配列（上から順に実行）です。
{
"require-dev": {
"wp-cli/wp-cli-bundle": "^2.11"
},
"scripts": {
"wp:check": [
"wp core verify-checksums",
"wp plugin verify-checksums --all"
],
"wp:updates": [
"wp core check-update",
"wp plugin list --update=available"
],
"wp:flush": [
"wp cache flush",
"wp rewrite flush"
],
"wp:after-deploy": [
"wp core update-db",
"@wp:flush"
],
"wp:db-export": "wp db export"
},
"scripts-descriptions": {
"wp:check": "コアとプラグインのファイルをチェックサムで検証する",
"wp:updates": "更新が出ているコアとプラグインを一覧する",
"wp:flush": "オブジェクトキャッシュとリライトルールをクリアする",
"wp:after-deploy": "デプロイ後のDB更新とキャッシュクリア",
"wp:db-export": "データベースをSQLファイルに書き出す"
}
}require-dev の版指定は例です。実際には composer require を実行したときに書き込まれる値をそのまま使ってください。
実行は composer wp:check または composer run-script wp:check です。配列の途中でコマンドが失敗（終了コードが0以外）すると、そこで止まって以降は実行されません。デプロイ後処理のように順序が大事な作業では、この性質が安全側に働きます。
他のスクリプトを呼び出す
"@wp:flush" のように @ + スクリプト名を書くと、別のスクリプトを呼び出せます。共通の処理を1か所にまとめておけば、変更したいときも1か所の修正で済みます。同じ仕組みで @php（Composer を動かしている PHP）や @composer も使えます。
説明文を付ける
scripts-descriptions に書いた説明は composer list の一覧に表示されます。登録したスクリプトを後から見た人が用途を理解できるよう、付けておくのがおすすめです。
名前の付け方
update や install など Composer 自体のコマンドと同じ名前は避けてください。wp: のような接頭辞を付けておくと、衝突を避けられるうえ一覧でも見つけやすくなります。
引数を渡す
スクリプト名の後に -- を置くと、その後ろの文字列がコマンドの末尾に追加されます。URL置換をスクリプトにしておき、置換する値は実行時に渡す例です。
"scripts": {
"wp:sr-dry": "wp search-replace --dry-run --report-changed-only",
"wp:sr": "wp search-replace --report-changed-only"
}composer wp:sr-dry -- "http://old.example.test" "https://new.example.test"まずドライランで変更件数を確認し、問題なければ wp:sr で実行する、という2段階にしておくと安全です。データベースを書き換えるスクリプトの前には composer wp:db-export でバックアップを取ってください。
wp-cli.ymlでパスと接続先を決める
WordPress 本体がプロジェクトのサブディレクトリ（例: web/wp）にある構成では、スクリプトのたびに --path を書く代わりに、プロジェクト直下の wp-cli.yml にまとめます。
path: web/wp
@staging:
ssh: deploy@staging.example.com/var/www/example/web/wp@staging のようなエイリアスを定義すると、wp @staging core version のようにリモートのサイトへ SSH 経由でコマンドを送れます（リモート側にも WP-CLI が必要です）。これを Composer スクリプトにすれば、composer wp:staging-check の一言でステージングの検証を走らせることもできます。
"wp:staging-check": "wp @staging core verify-checksums"自作のWP-CLIコマンドを登録して呼び出す
プロジェクト固有の処理（外部APIとの同期など）は、WP-CLI のカスタムコマンドとして作り、それを Composer スクリプトから呼ぶ形にすると整理しやすくなります。mu-plugin に書く例です。
<?php
/**
* Plugin Name: Project CLI Commands
*/
if ( defined( 'WP_CLI' ) && WP_CLI ) {
/**
* 公開中の投稿数を表示する。
*
* ## EXAMPLES
*
* wp myproject stats
*/
WP_CLI::add_command(
'myproject stats',
function () {
$count = wp_count_posts( 'post' );
WP_CLI::success( sprintf( '公開中の投稿: %d件', (int) $count->publish ) );
}
);
}"project:stats": "wp myproject stats"WP_CLI 定数の確認で囲んでいるのは、通常のページ表示時にこのコードを読み込まないためです。コメントの ## EXAMPLES などは wp help myproject stats のヘルプとして表示されます。
タイムアウト・Windows・CIでの注意
長い処理のタイムアウト
Composer にはスクリプトの実行時間の上限があり、既定では300秒です。大きなデータベースの書き出しや大量の置換で止まる場合は、配列の先頭に Composer\\Config::disableProcessTimeout を置くと、そのスクリプトだけ上限を外せます。
"wp:db-export": [
"Composer\\Config::disableProcessTimeout",
"wp db export"
]設定 process-timeout や環境変数 COMPOSER_PROCESS_TIMEOUT で全体の上限を変える方法もあります。
Windowsで動かす場合
スクリプトはOSのシェルで実行されるため、Windows ではコマンドプロンプトの文法になります。$(date +%Y%m%d) のようなシェル展開や、シングルクォートでの引数の囲みは期待どおりに動きません。チームにWindows利用者がいる場合は、シェル固有の書き方を避け、日付付きのファイル名などは WP-CLI の既定の動作に任せるか、自作コマンドの中で処理してください。
インストール時イベントとの組み合わせ
post-install-cmd や post-update-cmd に WP-CLI コマンドを登録すると、composer install のたびに自動実行されます。ただし CI のようにデータベースが無い環境では WordPress に接続できずに失敗し、インストール自体が失敗扱いになります。データベースを使う処理はイベントに入れず、明示的に呼ぶスクリプトにしておく方が扱いやすいです。
登録できたかを確認する
composer run-script --list
composer wp:check一覧に名前が出ていれば登録できています。実行して「Success」が表示されれば WP-CLI まで正しく動いています。wp が見つからないというエラーが出る場合は、composer install を実行して vendor/bin/wp があるか、または PATH 上に wp があるかを確認してください。WP-CLI の版や同梱コマンドの構成は更新で変わることがあるため（2026年10月現在）、wp cli version で使っている版を把握しておくと、トラブル時の切り分けが楽になります。
まとめ
composer require --dev wp-cli/wp-cli-bundleで入れると、スクリプト内ではwpと書くだけでプロジェクトの WP-CLI が使われる。scriptsは文字列か配列で定義し、@名前で他のスクリプトを呼べる。scripts-descriptionsで説明を付けておく。- 実行時の引数は
--の後ろに渡す。DBを書き換える処理はドライランとバックアップをセットにする。 - WordPress の場所やリモート接続先は wp-cli.yml にまとめ、固有の処理は
WP_CLI::add_command()で自作コマンドにする。 - タイムアウト（既定300秒）、Windows のシェル差、インストール時イベントでのDB接続失敗に注意する。