wp-cli

wp-cli

ターミナルを中心とした WordPress の運用。大量処理では wp-admin より安全で、スクリプト化しやすく、SSH に適しており、1 万行の更新でもタイムアウトしません。

確認コマンドと、バックアップを作成する wp db export だけは、プロンプトなしで実行されます。データを変更するすべてのコマンド（search-replace、db import、db reset、プラグインやテーマのインストール、ユーザーや投稿の書き込みなど）は、実行前に確認を求めます。この手間を意図的に設けているのは、このスキルが本番環境を対象にすることが多いためです。

リファレンスファイルは ${CLAUDE_SKILL_DIR}/references/ にあります。

使用しないケース

• コンテンツ編集者が管理画面で 10 秒でできる単発の編集。1 行だけをクリックする場合、CLI は大げさで、エラーも起きやすくなります。
• 数百万行に及ぶデータ変換。WP の ORM は処理が遅いため、トランザクションを明示した直接 SQL によるマイグレーションを検討してください。
• WordPress プラグインのフックのライフサイクル内で実行する必要がある処理（REST の検証、カスタム投稿タイプの登録など）。これは CLI ではなく PHP コードで行います。
• 最新のバックアップがない状態で実行する破壊的なコマンド。wp db reset、wp db clean、一括削除などは、必ず事前にスナップショットを作成してください。

事前確認

作業を始める前に、必ず確認してください。

wp --version                  # wp-cli is installed
wp core is-installed          # WordPress is actually set up at this path
wp core version               # which WP version

WordPress のルートディレクトリにいない場合は、--path=/path/to/wordpress を指定するか、先にそのディレクトリへ cd してください。リモートホストでは、--ssh=user@host/path または設定済みのエイリアスを使用してください（リモート実行を参照）。

安全対策のパターン

破壊的な操作の前にバックアップを作成する

# Database snapshot
wp db export backup-$(date +%Y%m%d-%H%M%S).sql

# Full site snapshot (db + content)
tar -czf site-backup-$(date +%Y%m%d-%H%M%S).tar.gz wp-content/ backup-*.sql

利用可能な場合はドライランを実行する

wp plugin update --all --dry-run
wp search-replace 'old.com' 'new.com' --dry-run

危険なコマンド — 明示的に確認する

これらの操作は、バックアップなしでは取り消せません。実行前にユーザーの確認を得てください。

• wp db reset — すべてのテーブルを削除します
• wp db clean — 現在の $table_prefix に一致するすべてのテーブルを削除します
• wp site delete（マルチサイト）— サイトとそのコンテンツを削除します
• --reassign を指定しない wp user delete — ユーザーの投稿が孤立します（投稿も削除されます）。コンテンツを先に再割り当てするため、必ず --reassign=<new_author_id> を指定してください。このフラグがあるのは、コンテンツを孤立させることが望まれるケースはほとんどないためです。ユーザーの投稿は組織の記録であり、ユーザー行ではありません。
• wp post delete $(wp post list --format=ids) などの一括削除パイプ — フィルターが間違っていると、サイト全体をいつの間にか空白のページにしてしまいます。

パフォーマンスフラグ

--format=json              # machine-readable
--format=csv               # spreadsheet import
--format=ids               # space-separated IDs, for piping
--fields=ID,post_title     # return only what you need
--skip-plugins             # bypass plugin load (fast, may break plugin-dependent commands)
--skip-themes              # bypass theme load
--quiet                    # suppress info output

--skip-plugins はメスのように使うフラグです。wp db export を瞬時に実行できますが、プラグインのフックに依存するコマンド（ACF エクスポーターや、プラグインが登録するカスタムタクソノミーなど）は動作しなくなります。

コマンドカタログ

フラグの詳細と注意点は references/commands.md にあります。カテゴリは次のとおりです。

カテゴリ	プレフィックス	主な用途
データベース	wp db	エクスポート、インポート、クエリ、最適化、検索と置換
コア	wp core	インストール、更新、チェックサムの検証、バージョン確認
プラグイン	wp plugin	一覧表示、インストール、有効化、更新、削除
テーマ	wp theme	一覧表示、インストール、有効化、更新、削除、theme mod
ユーザー	wp user	作成、一覧表示、削除（--reassign）、更新、権限、生成
投稿／固定ページ	wp post	一覧表示、作成、更新、削除、生成、post term
コメント	wp comment	一覧表示、承認、スパム指定、ゴミ箱へ移動、削除
オプション	wp option	取得、更新、削除、一覧表示、ネストされた値の pluck／patch
キャッシュ	wp cache / wp transient	フラッシュ、削除、設定、一覧表示
Cron	wp cron	イベントの一覧表示／実行／スケジュール／削除、Cron のテスト
設定	wp config	作成、取得、設定、ソルトの再生成
マルチサイト	wp site	一覧表示、作成、削除、空にする、有効化／アーカイブ

ワークフロー

手順を一つずつ示すワークフローの全容は references/ にあり、タスクごとに分かれています。最初から最後までユーザーが実行するものだけを読み込んでください。

ワークフロー	ファイル
サイトの移行（ローカル → 本番環境）＋検索と置換	references/examples-migration.md
ロールバック、デバッグ、DB メンテナンスを伴うプラグインの更新	references/examples-maintenance.md
ユーザー監査、クリーンアップ、安全なパスワードローテーション	references/examples-users.md
CSV からのコンテンツ一括インポート	references/examples-content.md
マルチサイト／ネットワーク運用	references/examples-multisite.md

リモート実行

アドホックな SSH

ssh [email protected] "cd /var/www/html && wp plugin list"

設定済みのエイリアス（推奨）

~/.wp-cli/config.yml でエイリアスを一度定義します。

@prod:
  ssh: [email protected]/var/www/html
@staging:
  ssh: [email protected]/var/www/staging

次に：

wp @prod plugin list
wp @staging db export

エイリアスはあらゆる wp-cli フラグと組み合わせられるため（wp @prod --dry-run search-replace ...）、アドホックな SSH より便利で、シェルの引用符に関する問題も起きにくくなります。

よくあるエラー

エラー	原因	解決方法
The site you have requested is not installed	WordPress のルートディレクトリにいない／wp-config.php がない	ルートディレクトリへ cd するか、--path=/path/to/wordpress を指定します
MySQL connection failed	認証情報が正しくない、または MySQL が停止している	wp-config.php を確認し、MySQL が実行中であることを確認します
Error: Can't select database	DB が存在しない	wp db create
PHP Fatal error: Allowed memory size exhausted	大規模な操作、または負荷の高いプラグイン	php -d memory_limit=512M $(which wp) db export
This does not seem to be a WordPress installation	WP ファイルが見つからない	ディレクトリを確認し、WP が実際にインストールされていることを確認します
The \guid` column is often used ... but should not be updated`	想定内の警告	--skip-columns=guid で抑制できます。GUID は永続的な ID であり、URL ではありません

アンチパターン — wp-cli が適切なツールではない場合

• シェルで xargs や for を使って数百万行をループ処理すること。wp を実行するたびに WordPress が初期化されるため、100 万回の反復には数日かかります。適切な SQL 文を使った単一の wp db query、または PHP 側でバッチ処理するジョブを優先してください。
• 趣味のブログを超える規模のシリアライズデータに対して、--precise を指定せずに wp search-replace を使うこと。--precise は遅くなりますが、PHP のシリアライズ文字列を正しく処理します。指定しない場合、シリアライズされた配列が気づかれないまま破損します。
• 検証とドメインロジック。ロジックが WP プラグインのフックのライフサイクル内に属するなら、そこで実行してください。wp-cli は運用作業用であり、ビジネスルール用ではありません。
• 認証情報を含むコマンドをシェルの履歴に残すこと。--user_pass=... を指定して wp user create を実行すると、パスワードが漏洩します。パスワードをパイプで渡すか、wp-cli のプロンプトに入力してください。

ベストプラクティス

1. まずステージング環境で実行してください。常にです。 テストしていないコマンドを本番環境で実行してはいけません。
2. 可能であれば wp-config.php の変更をバージョン管理で追跡します（シークレットは除外してください）。
3. 出力を確認してください。 wp-cli の警告は、データ損失に先立って表示されることがよくあります。
4. 分かりにくいワークフローを記録してください — 移行やマルチサイトへの変換などは、その都度記録します。後になれば、使ったフラグを思い出せなくなります。
5. jq やその他のスクリプトにパイプで渡す場合は、常に --format=json を指定してください。 デフォルトの人間向け形式はすぐに古くなります。
6. 大きな変更の後は検証してください — ホームページを読み込み、管理画面を確認し、重要な操作を実行します。
7. wp-cli を最新の状態に保ってください：wp cli update（Phar インストールの場合のみ — Homebrew と Composer によるインストールは、それぞれのパッケージマネージャーで更新します）。

参考資料

• references/commands.md — カテゴリ別の詳細なコマンドとフラグのリファレンス
• ワークフローガイド（必要に応じて読み込んでください）：
  • references/examples-migration.md — 移行と検索・置換
  • references/examples-maintenance.md — プラグインの更新、デバッグ、データベースのメンテナンス
  • references/examples-users.md — ユーザーの監査とクリーンアップ
  • references/examples-content.md — CSV コンテンツのインポート
  • references/examples-multisite.md — マルチサイトの操作
• 上流のドキュメント：https://developer.wordpress.org/cli/commands/