ターミナルの wp eval コマンドについて、オプション情報、wp eval-file との違い、AIエージェントが実行した場合の危険性などを紹介しています。

wp eval とは

wp eval（WP-CLI evaluate PHP code）は、WP-CLI が提供するサブコマンドで、WordPress の実行環境をロードした状態で任意の PHP コードを直接実行します。

データベース接続・投稿の作成・オプション値の変更・プラグイン関数の呼び出しなど、WordPress のあらゆる機能をターミナルから1行で操作できるため、開発・デバッグ・マイグレーション作業で広く活用されています。

一方で、コードの内容次第でデータベースの書き換えやファイルの削除も可能なため、実行内容の確認を怠ると取り返しのつかない損害を引き起こす可能性があります。

主なオプション

オプション	意味
--skip-wordpress	WordPress をロードせずに PHP コードを実行する。WordPress に依存しない純粋な PHP スクリプトを走らせたい場合に使用する
--path=<path>	WordPress のインストールパスを明示的に指定する。複数サイトを管理している環境で対象サイトを切り替えるときに使う
--url=<url>	マルチサイト環境で操作対象のサイト URL を指定する
--allow-root	root ユーザーでの実行を許可する。通常は root での WP-CLI 実行は警告が出るため、CI/CD 環境など必要な場面でのみ使用する

基本構文は wp eval '実行したいPHPコード' です。コードはシングルクォートで囲むのが一般的ですが、コード内にシングルクォートが含まれる場合はエスケープするか、ヒアドキュメント（wp eval "$(cat <<'EOF' ... EOF)"）を使う方法もあります。

よく使う組み合わせ

WordPress のオプション値を確認・変更する

# siteurl の値を確認する
wp eval 'echo get_option("siteurl");'

# home オプションを変更する
wp eval 'update_option("home", "https://example.com");'

get_option() や update_option() を直接呼び出してオプション値を確認・変更できます。
サイト移行後の URL 修正など、wp option コマンドで対応しにくい複雑な条件付き更新に便利です。

投稿データをまとめて操作する

# 下書き状態の投稿数を確認する
wp eval 'echo wp_count_posts()->draft;'

# 特定カテゴリの投稿をすべて取得してタイトルを出力する
wp eval '
$posts = get_posts(["category_name" => "news", "numberposts" => -1]);
foreach ($posts as $p) { echo $p->ID . ": " . $p->post_title . "\n"; }
'

WordPress の投稿取得・集計関数を直接呼び出せます。
管理画面では確認しにくい集計値の確認や、大量投稿の一括処理前の件数チェックに使えます。

プラグイン・テーマの関数を直接呼び出す

# WooCommerce の注文ステータスを確認する（WooCommerce インストール済み環境）
wp eval 'echo wc_get_order(123)->get_status();'

# ACF のフィールド値を取得する
wp eval 'echo get_field("my_field", 456);'

有効化されているプラグインやテーマの関数もそのまま呼び出せます。
プラグイン固有のデータを管理画面を通さずに確認・操作したいデバッグ場面に役立ちます。

wp eval と wp eval-file の違い

どちらも WordPress 環境で PHP コードを実行しますが、コードの渡し方と用途に違いがあります。

項目	wp eval	wp eval-file
コードの渡し方	コマンドライン引数に直接記述	PHP ファイルのパスを指定
向いている用途	1〜3行程度の簡単な確認・変更	複数行・複雑なロジックのバッチ処理
再利用性	低い（コマンド履歴にのみ残る）	高い（ファイルとして管理・バージョン管理可）
引数の受け渡し	シェル変数・ヒアドキュメントで対応	-- 以降の引数を $args で受け取れる
実行前レビュー	しにくい（インライン記述）	しやすい（ファイルを事前に確認できる）

一度きりの即席確認や短い処理には wp eval、定期バッチや複数環境で繰り返し使うスクリプトには wp eval-file が適しています。

本番環境での変更を伴う処理は、レビューしやすい wp eval-file を優先してください。

ユースケース

サイト移行後に URL を一括書き換える

# search-replace を使う標準的な方法（推奨）
wp search-replace 'https://old.example.com' 'https://new.example.com' --dry-run
wp search-replace 'https://old.example.com' 'https://new.example.com'

# wp eval で直接 siteurl / home だけ書き換える場合
wp eval '
update_option("siteurl", "https://new.example.com");
update_option("home", "https://new.example.com");
echo "Updated: " . get_option("siteurl") . "\n";
'

URL の全文置換には wp search-replace が推奨ですが、siteurl と home だけを素早く書き換えたい場面では wp eval でも対応できます。必ず --dry-run で影響範囲を確認してから実行してください。

トランジェントキャッシュをすべて削除する

# WP-CLI 標準コマンドで削除（推奨）
wp transient delete --all

# wp eval でデータベースから直接削除する場合
wp eval '
global $wpdb;
$deleted = $wpdb->query("DELETE FROM {$wpdb->options} WHERE option_name LIKE \"_transient_%\"");
echo "Deleted: {$deleted} rows\n";
'

トランジェントの削除には wp transient delete --all が標準ですが、wp eval で $wpdb を直接操作する方法も知っておくと、カスタムテーブルや特定プレフィックスのトランジェントを対象にする場面で応用できます。

AIエージェントが実行しようとした場合

AIエージェントの目的

AIエージェントは主に次のような目的で wp eval を実行しようとすることがあります。

• WordPress の設定値やデータを確認するために、管理画面を経由せず直接取得しようとすることがあります
• サイト移行・環境構築の自動化の一環として、オプション値の書き換えやデータの初期化を行おうとすることがあります
• エラーの原因調査として、特定の WordPress 関数やプラグイン関数の戻り値をその場で確認しようとすることがあります

危険性

wp eval コマンドは、任意の PHP コードを WordPress の管理者権限と同等以上の権限で即時実行する不可逆的な操作を伴います。

データベースの全削除・ユーザーパスワードのリセット・悪意あるコードの挿入なども技術的には1行のコードで可能であるため、AIエージェントが自動生成・自動実行することは推奨されません。

実行前にコード内容を人間が確認し、ステージング環境で動作を検証してから本番環境で実行するフローを徹底してください。エージェント設定でのブロックリスト登録も強く推奨します。