gh-emdashcodes-wp-ability-toolkit-claude-code-plugins-wordpress-plugin-scaffold/skills/wordpress-plugin-scaffold/references/wp-cli-installation.md

WP-CLI Installation Guide

This reference provides comprehensive installation instructions for WP-CLI across different platforms and methods.

Quick Check

Verify if WP-CLI is already installed:

wp --version

If installed, you'll see the version number. If not, follow the installation method below that best suits your environment.

Recommended Installation (Phar Method)

The recommended way to install WP-CLI is by downloading the Phar build, marking it executable, and placing it on your PATH.

Step 1: Download WP-CLI

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Step 2: Verify It Works

php wp-cli.phar --info

Step 3: Make It Executable and Move to PATH

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Step 4: Test the Installation

wp --info

You should see output showing OS, PHP version, WP-CLI version, etc.

Updating WP-CLI

If you installed using the Phar method:

wp cli update

Or with sudo if WP-CLI is owned by root:

sudo wp cli update

For nightly builds (bleeding edge):

wp cli update --nightly

Platform-Specific Installation

macOS (Homebrew)

brew install wp-cli

Windows

1. Ensure PHP is installed and in your PATH

2. Download wp-cli.phar to c:\wp-cli

3. Create wp.bat in c:\wp-cli:

   @ECHO OFF
   php "c:/wp-cli/wp-cli.phar" %*
   

4. Add c:\wp-cli to your PATH:

   setx path "%path%;c:\wp-cli"
   

Debian/Ubuntu (.deb package)

Download and install from: https://github.com/wp-cli/builds/tree/gh-pages/deb

Fedora 30+

su -c 'dnf install wp-cli'

CentOS

su -c 'yum install wp-cli'

Alternative Installation Methods

Via Composer (Global)

If you have Composer and ~/.composer/vendor/bin in your PATH:

composer global require wp-cli/wp-cli-bundle

Update all global packages:

composer global update

Via Composer (Project)

Add to your project's composer.json:

"require": {
    "wp-cli/wp-cli-bundle": "*"
}

Via Docker

Use the official WordPress CLI image:

image: wordpress:cli

See WordPress Docker images for more details.

Specific Version

Install a specific version via Composer:

composer create-project wp-cli/wp-cli-bundle:2.1.0 --no-dev

Bleeding Edge (dev-main)

composer create-project wp-cli/wp-cli-bundle:dev-main --no-dev

Shell Completion

Bash & Zsh

Download the completion script:

curl -O https://github.com/wp-cli/wp-cli/raw/main/utils/wp-completion.bash

Add to ~/.bash_profile or ~/.zshrc:

source /FULL/PATH/TO/wp-completion.bash

Reload your profile:

source ~/.bash_profile  # or source ~/.zshrc

Oh My Zsh

Enable the built-in wp-cli plugin in ~/.zshrc:

plugins=(wp-cli git [...])

Then reload:

source ~/.zshrc

Fish

Download and install completion:

curl -O https://github.com/wp-cli/wp-cli/raw/main/utils/wp.fish
mv wp.fish ~/.config/fish/completions/wp.fish

Custom PHP Binary (MAMP, etc.)

If you need to use a custom PHP binary (e.g., MAMP):

Latest MAMP PHP Version

Add to ~/.bash_profile or ~/.zshrc:

PHP_VERSION=$(ls /Applications/MAMP/bin/php/ | sort -n | tail -1)
export PATH=/Applications/MAMP/bin/php/${PHP_VERSION}/bin:$PATH

Specific MAMP PHP Version

Add to ~/.bash_profile or ~/.zshrc:

export PATH=/Applications/MAMP/bin/php/php5.5.26/bin:$PATH

Reload profile:

source ~/.bash_profile  # or source ~/.zshrc

Verify:

wp --info

Using WP_CLI_PHP Environment Variable

For Composer and Git-based installations:

export WP_CLI_PHP=/path/to/custom/php

Troubleshooting

Command Not Found

If wp command is not found after installation:

1. Check that /usr/local/bin is in your PATH:

   echo $PATH
   

2. Verify the file exists and is executable:

   ls -la /usr/local/bin/wp
   

3. Try using the full path:

   /usr/local/bin/wp --info
   

Permission Denied

If you get permission errors:

sudo chmod +x /usr/local/bin/wp

PHP Version Issues

WP-CLI requires PHP 7.4 or later. Check your PHP version:

php --version

If your PHP version is too old, you'll need to upgrade PHP or use a custom PHP binary (see above).

Additional Resources

• Official WP-CLI Installation Guide
• Official WP-CLI Documentation
• WP-CLI Commands Reference
• WP-CLI GitHub Repository
• Quick Start Guide