WP-CLI は、公式リポジトリで配布されている補完用スクリプト wp-completion.bash を読み込むだけで、wp pl と打って Tab キーを押すと wp plugin まで補完されるようになります。この記事では、補完の仕組み、bash と zsh それぞれの設定手順、動作確認の方法、補完が効かないときの確認ポイントを説明します。
WP-CLIの補完の仕組み
WP-CLI のタブ補完は、シェルの補完機能から WP-CLI 自身に候補を問い合わせる仕組みです。補完スクリプトは、入力途中のコマンドラインを wp cli completions というコマンドに渡し、返ってきた候補をシェルに表示させます。
この問い合わせ用のコマンドは手動でも実行できるので、補完の動作確認にも使えます。
# 「wp plugin 」の次に入りうる候補を表示する
wp cli completions --line="wp plugin " --point=100--line には入力途中のコマンド全体、--point にはカーソル位置を渡します。activate、deactivate、install などのサブコマンドが並べば、WP-CLI 側は正しく候補を返せています。
候補は WP-CLI 本体から取得されるため、パッケージやプラグインが追加したコマンドも補完の対象になりえます。手で一覧を作る必要がないのがこの方式の利点です。一方で、Tab を押すたびに PHP で WP-CLI が起動するので、候補が出るまで一瞬待つことがあります。
前提：wp コマンドが PATH 上にあること
補完スクリプトは wp という名前のコマンドに対して登録されます。まず、シェルから wp で WP-CLI が起動できる状態かを確認します。
which wp
wp cli versionwp-cli.phar を php wp-cli.phar のように直接実行している場合は、公式の手順どおり実行権限を付けて /usr/local/bin/wp などに配置し、wp で呼べるようにしておきます。補完の候補は WP-CLI のバージョンによって変わるため、wp cli version でバージョンも確認しておくと、後で挙動を比べるときに役立ちます。WP-CLI の安定版は 2系です（2026年10月現在）。
bash で補完を有効にする
1. 補完スクリプトを取得する
wp-completion.bash は WP-CLI の GitHub リポジトリ（wp-cli/wp-cli）の utils ディレクトリで公開されています。公式ハンドブックのインストール手順にも取得方法が載っているので、URL はそちらで最新のものを確認してください。ブランチ名などが変わっている可能性があります。
mkdir -p ~/.wp-cli
cd ~/.wp-cli
curl -fsSL -o wp-completion.bash \
https://raw.githubusercontent.com/wp-cli/wp-cli/main/utils/wp-completion.bash取得したら、中身をひととおり開いて確認してから使います。シェルの起動時に毎回読み込まれるファイルなので、出どころの分からないコピーではなく公式リポジトリのものを使ってください。
2. .bashrc から読み込む
~/.bashrc の末尾に次の1行を追加します。パスはスクリプトを置いた場所に合わせます。
# ~/.bashrc
source ~/.wp-cli/wp-completion.bash追加したら、設定を読み直すか、ターミナルを開き直します。
source ~/.bashrc3. 動作を確認する
wp と入力してから Tab キーを2回押し、cache、core、plugin などのコマンド一覧が出れば設定できています。wp plugin の後で Tab を押してサブコマンドが出るか、wp plugin install -- の後で Tab を押してオプションが出るかも試しておくとよいでしょう。
SSH でログインしたときに読み込まれない場合は、ログインシェルが ~/.bash_profile だけを読んでいる可能性があります。その場合は ~/.bash_profile から ~/.bashrc を読み込むようにするか、同じ source 行を ~/.bash_profile に書きます。
zsh で補完を有効にする
macOS の標準シェルなど zsh を使っている場合も、同じ bash 用スクリプトを使えます。zsh には bash 形式の補完を読み込むための bashcompinit という仕組みがあり、これを先に有効にしてからスクリプトを読み込みます。
# ~/.zshrc
autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit
source ~/.wp-cli/wp-completion.bashcompinit を先に初期化しておかないと、環境によっては補完関数の登録でエラーになります。Oh My Zsh などのフレームワークを使っている場合は、フレームワーク側ですでに compinit が呼ばれていることが多いので、bashcompinit と source の2行をフレームワークの読み込みより後ろに書きます。
保存後に exec zsh でシェルを再起動し、bash と同じ方法で動作を確認します。
補完が効かないときの確認ポイント
補完関数が登録されているか
bash では、wp に補完関数が登録されているかを次のコマンドで確認できます。
complete -p wp何も表示されない、またはエラーになる場合は、スクリプトが読み込まれていません。source の行のパスの誤りや、.bashrc が読み込まれていない可能性を確認します。
エイリアスや別名で呼んでいないか
alias wp='php ~/wp-cli.phar' のようにエイリアスで WP-CLI を呼んでいる環境では、補完スクリプトの中から呼び出す wp がうまく解決されず、候補が出ないことがあります。エイリアスではなく、実行ファイルとして PATH 上に置く方法に切り替えると解消しやすくなります。
sudo や別ユーザーで実行していないか
sudo -u www-data wp plugin list のように別ユーザーで実行する形では、補完は sudo に対して働くため、wp 以降のサブコマンドは補完されません。補完を使いたい場合は、そのユーザーのシェルに入ってから操作するか、補完で確認したコマンドを組み立ててから sudo -u を付けて実行します。
コンテナや SSH 先で使う場合
Docker コンテナ内や SSH 接続先のサーバーで補完を使うには、その環境のシェル設定にも同じ手順で wp-completion.bash を読み込ませる必要があります。手元のPCで設定しても、接続先には反映されません。
候補の出方がおかしいとき
wp cli completions --line="wp " --point=100 を直接実行し、候補が返るかを確認します。ここでPHPのエラーが出る場合は、補完ではなく WP-CLI 本体や PHP の設定に問題があります。WordPress のディレクトリで実行したときだけエラーになる場合は、プラグインやテーマが読み込み時にエラーを出している可能性があるため、wp --skip-plugins --skip-themes cli version のように読み込みを止めて切り分けます。
補完と合わせて使うと便利な確認方法
補完でコマンド名を思い出せても、オプションの意味まではわかりません。オプションの詳細は wp help で確認する習慣をつけると、補完と合わせて効率よく操作できます。
wp help plugin install
wp help search-replace特に wp search-replace や wp db 系のように、データベースを書き換えるコマンドは、補完で素早く入力できるぶん打ち間違いにも気づきにくくなります。実行前に wp db export でバックアップを取り、まずステージング環境で試す流れは補完を使っていても変わりません。
まとめ
- WP-CLI の補完は、公式リポジトリの
wp-completion.bashを読み込むと有効になる。中身はwp cli completionsに候補を問い合わせる仕組み - bash は
~/.bashrcにsource行を追加。SSH ログインで効かないときは~/.bash_profileも確認する - zsh は
compinitとbashcompinitを有効にしてから同じスクリプトを読み込む - 効かないときは
complete -p wpで登録状況を、wp cli completionsで WP-CLI 側の応答を確認する - エイリアスや
sudo -u経由の実行では補完が働かないことがある