Skip to main content

Installation & Setup

info
  • Target Audience: Developers, System Administrators
  • Difficulty: Beginner
  • Prerequisites: PHP 5.6+, MySQL/MariaDB

This guide outlines the practical steps to install, configure, and verify WP-CLI on your system. WP-CLI is the command-line interface for WordPress, allowing you to manage WordPress installations without using a web browser.

1. Prepare your Environment​

Before installing, ensure your server or local machine meets the minimum requirements.

Check Prerequisites​

Run the following commands in your terminal to verify your php and download tools:

# Check PHP version (Must be 5.6 or later)
php -v

# Check for cURL or wget (You need at least one)
curl --version
wget --version
PHP Requirement

WP-CLI requires PHP 5.6 or later. Most modern WordPress sites run on PHP 7.4 or 8.x, which is recommended.

2. Install WP-CLI​

We recommend the Phar method as it is platform-agnostic, self-contained, and easiest to maintain.

  1. Download the Phar file: Use curl or wget to download the specific archive.

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

  2. Verify the file: Check that the extracted PHP Archive works before installing it system-wide.

    php wp-cli.phar --info

  3. Make it Executable & Move it: Add execution permissions and move it to a directory in your $PATH.

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

  4. Confirm Installation: Now you can run wp from anywhere.

    wp --info

Option B: Composer Installation​

If you are managing a project with composer, you can require WP-CLI as a dependency.

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

Note: Ensure your global composer binary directory is in your $PATH.

Option C: Homebrew (macOS)​

For macOS users preferring Homebrew:

brew install wp-cli

3. Configure Shell Completion​

Tab completion allows you to auto-complete commands (like wp plug... to wp plugin), drastically speeding up your workflow.

  1. Download the completion script:

    curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/v2.11.0/utils/wp-completion.bash

  2. Setup the directory: We recommend storing this in a hidden configuration folder in your home directory.

    mkdir -p ~/.wp-cli
    mv wp-completion.bash ~/.wp-cli/

  3. Update your Profile: Add the source command to your shell configuration (~/.bashrc, ~/.zshrc, or ~/.profile).

    # Open your config file
    nano ~/.bashrc

    # Add this line to the bottom
    source ~/.wp-cli/wp-completion.bash

  4. Apply Changes:

    source ~/.bashrc

4. Verify Installation​

Run the main diagnostic command to check your version and configuration paths.

wp --info

Expected Output:

OS:     Linux 5.4.0-x generic
Shell:  /bin/bash
PHP binary:     /usr/bin/php8.1
PHP version:    8.1.2
WP-CLI root dir:        /usr/local/bin/wp
WP-CLI global config:
WP-CLI project config:
WP-CLI version: 2.11.0

5. Update WP-CLI​

WP-CLI has a built-in self-update mechanism (only works for Phar installations).

# Check for updates
wp cli check-update

# Perform update
sudo wp cli update

6. Troubleshoot Common Issues​

IssueCauseSolution
command not found: wpwp file is not in a $PATH directory.Move it to /usr/local/bin/ or check your $PATH.
Permission deniedFile is not executable.Run chmod +x /usr/local/bin/wp.
PHP Notice: Undefined indexPHP configuration issue.Ensure php-cli is installed and updated.
Success

If wp --info returns valid output, you are ready to start managing WordPress sites. Proceed to the next section to learn basic commands.