WP-CLI

https://make.wordpress.org/cli/handbook/
Admin
WP-CLI is a command-line interface for WordPress that enables users to manage WordPress...
Tokens:162,977
Snippets:1,460
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Usage of Given a WP installation in step

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-a-wp-installation-in

Examples showing how to use the step to install WordPress in a directory, with or without a specific version.

```gherkin
Scenario: My example scenario
  Given a WP installation in 'foo'
  ...

Scenario: My other scenario
  Given a WP install in 'bar'
  ...

Scenario: My version-specific scenario
  Given a WP 6.4.2 installation in 'subdir'
  ...
```

--------------------------------

### Example package installation output

Source: https://make.wordpress.org/cli/handbook/bug-reports

This block shows the expected output when installing a package via WP-CLI, which can be used as a reference for reporting installation-related bugs.

```bash
$ wp package install wp-cli/scaffold-package-command:@stable
Installing package wp-cli/scaffold-package-command (@stable)
Updating /root/.wp-cli/packages/composer.json to require the package...
Using Composer to install the package...
---
Loading composer repositories with package information
Updating dependencies
Resolving dependencies through SAT
Dependency resolution completed in 0.001 seconds
Analyzed 421 packages to resolve dependencies
Analyzed 96 rules to resolve dependencies
Package operations: 1 install, 0 updates, 0 removals
Installs: wp-cli/scaffold-package-command:1.2.0
 - Installing wp-cli/scaffold-package-command (1.2.0)
Writing lock file
Generating autoload files
---
Success: Package installed.
```

--------------------------------

### Clone and setup the entire WP-CLI project

Source: https://make.wordpress.org/cli/handbook/contributions/pull-requests

Commands to clone the main WP-CLI repository, install dependencies, alias the command, and verify the installation.

```bash
git clone git@github.com:wp-cli/wp-cli.git ~/wp-cli
cd ~/wp-cli
hub fork
composer install --prefer-source
alias wp='~/wp-cli/bin/wp'
wp --info
```

--------------------------------

### Usage of Given a WP installation in :subdir

Source: https://make.wordpress.org/cli/handbook/references/behat-steps/given-a-wp-installation-in-subdir

Examples showing how to use the step in a Behat scenario to install WordPress in a specific directory.

```gherkin
Scenario: My example scenario
  Given a WP installation in 'foo'
  ...

Scenario: My other scenario
  Given a WP install in 'bar'
  ...
```

--------------------------------

### WP-CLI Info Output

Source: https://make.wordpress.org/cli/handbook/guides/installing

Example output when running 'wp --info' after a successful installation.

```text
OS:  Linux 4.10.0-42-generic #46~16.04.1-Ubuntu SMP Mon Dec 4 15:57:59 UTC 2017 x86_64
Shell:   /usr/bin/zsh
PHP binary:    /usr/bin/php
PHP version:     7.1.12-1+ubuntu16.04.1+deb.sury.org+1
php.ini used:   /etc/php/7.1/cli/php.ini
MySQL binary:
MySQL version:
SQL modes:
WP-CLI root dir:        /home/wp-cli/.wp-cli
WP-CLI packages dir:    /home/wp-cli/.wp-cli/packages/
WP-CLI global config:   /home/wp-cli/.wp-cli/config.yml
WP-CLI project config:
WP-CLI version: 1.5.0
```

--------------------------------

### Install globally as a project

Source: https://make.wordpress.org/cli/handbook/installing

Specify a custom installation path and symlink the binary.

```bash
composer create-project wp-cli/wp-cli-bundle /usr/share/wp-cli --no-dev
```

```bash
sudo ln -s /usr/share/wp-cli-bundle/vendor/wp-cli/wp-cli/bin /usr/bin/wp
```

--------------------------------

### Usage of Given a WP installation

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-a-wp-installation

Examples of how to use the step in a Behat scenario file, including standard, shorthand, and version-specific syntax.

```gherkin
Scenario: My example scenario
  Given a WP installation
  ...

Scenario: My other scenario
  Given a WP install
  ...

Scenario: My version-specific scenario
  Given a WP 6.4.2 installation
  ...
```

--------------------------------

### Install and activate a plugin

Source: https://make.wordpress.org/cli/handbook/guides/common-tasks

Installs and activates the specified plugin in a single command.

```bash
wp plugin install contact-form-7 --activate
```

--------------------------------

### Install a plugin with wp plugin install

Source: https://make.wordpress.org/cli/handbook/guides/quick-start

Demonstrates installing the Akismet plugin via the command line.

```bash
$ wp plugin install akismet
Installing Akismet (3.1.8)
Downloading install package from https://downloads.wordpress.org/plugin/akismet.3.1.8.zip...
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
```

--------------------------------

### Usage of I launch in the background step

Source: https://make.wordpress.org/cli/handbook/behat-steps/when-i-launch-in-the-background

Example of how to use the background launch step within a Behat scenario to start a server.

```gherkin
Scenario: My example scenario
  Given a WP install
  And I launch in the background `wp server --host=localhost --port=8181`
  ...
```

--------------------------------

### Install WordPress with wp core install

Source: https://make.wordpress.org/cli/handbook/guides/quick-start

Completes the WordPress installation with the provided site details and admin credentials.

```bash
$ wp core install --url=wpclidemo.dev --title="WP-CLI" --admin_user=wpcli --admin_password=wpcli --admin_email=info@wp-cli.org
Success: WordPress installed successfully.
```

--------------------------------

### Usage of Given a WP installation with Composer

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-a-wp-installation-with-composer

Examples of how to use the step in a Behat feature file.

```gherkin
Scenario: My example scenario
  Given a WP installation with Composer
  ...

Scenario: My other scenario
  Given a WP install with Composer
  ...
```

--------------------------------

### Select WordPress installation from a menu

Source: https://make.wordpress.org/cli/handbook/references/shell-friends

Uses whiptail to create an interactive menu for selecting and changing into a WordPress installation directory.

```bash
#!/bin/bash

WP_TOP_PATH="/home/"
MENU_TEXT="Choose an installation"
GAUGE_TEXT="Searching for WordPress"

declare -a MENU
WPS="$(wp --allow-root find "$WP_TOP_PATH" --field=version_path)"
WP_TOTAL="$(wc -l <<< "$WPS")"
WP_COUNT="0"

while read -r WP; do
    WP_LOCAL="${WP%wp-includes/version.php}"

    NAME="$(cd "$WP_LOCAL"; sudo -u "$(stat . -c %U)" -- wp --no-debug --quiet option get blogname)"
    if [ -z "$NAME" ]; then
        NAME="(unknown)"
    fi
    MENU+=( "$WP_LOCAL" "$NAME" )

    echo "$((++WP_COUNT * 100 / WP_TOTAL))".
done <<< "$WPS" > >(whiptail --gauge "$GAUGE_TEXT" 7 74 0)

WP_LOCAL="$(whiptail --title "WordPress" --menu "$MENU_TEXT"  $((${#MENU[*]} / 2 + 7)) 74 10 "${MENU[@]}" 3>&1 1>&2 2>&3)"

if [ $? -ne 0 ] || [ ! -d "$WP_LOCAL" ]; then
    echo "Cannot find '${WP_LOCAL}'" 1>&2
    exit 100
fi

echo "cd ${WP_LOCAL}"
```

--------------------------------

### Install a theme

Source: https://make.wordpress.org/cli/handbook/guides/common-tasks

Installs the specified theme from the WordPress theme directory.

```bash
wp theme install twentytwentyfour
```

--------------------------------

### Install via Homebrew

Source: https://make.wordpress.org/cli/handbook/guides/installing

Install WP-CLI using the Homebrew package manager.

```bash
brew install wp-cli
```

--------------------------------

### Install the wp profile package

Source: https://make.wordpress.org/cli/handbook/figure-out-why-wordpress-is-slow

Install the necessary WP-CLI package to begin profiling WordPress performance.

```bash
$ wp package install wp-cli/profile-command
```

--------------------------------

### Usage of WP multisite installation step

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-a-wp-multisite-subdirectory-subdomaininstall-installation

Demonstrates how to use the step in a Behat scenario for both subdomain and subdirectory multisite installations.

```gherkin
Scenario: My example scenario
  Given a WP multisite subdomain installation
  ...

Scenario: My other scenario
  Given a WP subdirectory install
  ...
```

--------------------------------

### Install wp-cli-dev development environment

Source: https://make.wordpress.org/cli/handbook/contributions/contributor-day

Commands to clone the development environment repository and install dependencies using Composer.

```bash
git clone https://github.com/wp-cli/wp-cli-dev
cd wp-cli-dev
composer install
```

--------------------------------

### Install php-process extension

Source: https://make.wordpress.org/cli/handbook/common-issues

Resolve the undefined function cli\posix_isatty() error by installing the required php-process extension.

```bash
yum install php-process
```

--------------------------------

### Initialize the local testing environment

Source: https://make.wordpress.org/cli/handbook/how-to/plugin-unit-tests

Run the installation script to set up a test database and download WordPress core files for testing. Ensure you have wget installed before running this command.

```bash
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
```

--------------------------------

### Clone and setup a specific WP-CLI command

Source: https://make.wordpress.org/cli/handbook/contributions/pull-requests

Commands to clone a specific command repository, install dependencies, and verify the installation.

```bash
hub clone wp-cli/core-command
cd core-command
composer install
vendor/bin/wp --info
```

--------------------------------

### WP-CLI Command Syntax Examples

Source: https://make.wordpress.org/cli/handbook/references/argument-syntax

Practical examples demonstrating required arguments, boolean flags, negated flags, associative arguments, and field formatting.

```bash
# Required arguments (no brackets)
wp config create --dbname=mydb --dbuser=root

# Optional arguments with defaults
wp config create --dbname=mydb --dbuser=root --dbhost=localhost

# Boolean flags
wp plugin install hello-dolly --activate --force

# Negated boolean flags
wp plugin list --no-color

# Associative arguments
wp cron event schedule my_hook --foo=bar --baz=qux

# Multiple values
wp plugin install plugin1 plugin2 plugin3

# Optional fields with specific format options
wp post list --format=json --fields=ID,post_title,post_date
```

--------------------------------

### Examples of WP-CLI package version constraints

Source: https://make.wordpress.org/cli/handbook/guides/installing-packages

Common examples of using Composer version constraints to install specific versions, allow updates, or target development branches.

```bash
# Install a specific version
wp package install wp-cli/server-command:2.0.0

# Install with caret operator (allows non-breaking updates)
wp package install wp-cli/server-command:^1.0

# Install with tilde operator (allows patch-level updates)
wp package install wp-cli/server-command:~1.2

# Install the latest stable release
wp package install wp-cli/server-command:@stable

# Install from a development branch
wp package install wp-cli/server-command:dev-main
```

--------------------------------

### Install WP-CLI packages using various sources

Source: https://make.wordpress.org/cli/handbook/guides/installing-packages

Demonstrates the different ways to specify a package source, including Composer names, Git URLs, local directories, and zip files.

```bash
# Install a package by name
wp package install wp-cli/server-command

# Install from a Git URL
wp package install https://github.com/wp-cli/server-command.git

# Install from a local directory
wp package install /path/to/package

# Install from a .zip file
wp package install package.zip
```

--------------------------------

### Background Sections for Common Setup

Source: https://make.wordpress.org/cli/handbook/guides/behat-tests

Uses a Background section to run common setup (WP install and post creation) for all scenarios, then tests update and delete operations.

```gherkin
Feature: Post management

  Background:
    Given a WP install
    And I run `wp post create --post_title='Test'`

  Scenario: Update post title
    When I run `wp post update 1 --post_title='Updated'`
    Then STDOUT should contain:
      """
      Success
      """

  Scenario: Delete post
    When I run `wp post delete 1`
    Then STDOUT should contain:
      """
      Success
      """

```

--------------------------------

### Given download: usage example

Source: https://make.wordpress.org/cli/handbook/references/behat-steps/given-download

Downloads multiple files into the given destinations. The step takes a table with 'path' and 'url' columns, where each row specifies a destination path and the source URL. The example uses {CACHE_DIR} as a placeholder for the cache directory.

```gherkin
Scenario: My example scenario
  Given download:
    | path                | url                                   |
    | {CACHE_DIR}/foo.jpg | https://example.com/foo.jpg           |
    | {CACHE_DIR}/bar.png | https://example.com/another-image.png |

```

--------------------------------

### Install WP-CLI binary to ~/bin

Source: https://make.wordpress.org/cli/handbook/guides/running-commands-remotely

Commands to create a local bin directory, download the WP-CLI phar, and make it executable.

```bash
mkdir -p ~/bin
cd ~/bin
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
mv wp-cli.phar wp
```

--------------------------------

### Define configuration in wp-cli.yml

Source: https://make.wordpress.org/cli/handbook/config

Shows an example of a wp-cli.yml file used to set the path parameter for a WordPress installation.

```bash
# WordPress develop includes a `wp-cli.yml` to enable easy use of WP-CLI
$ pwd
/srv/www/wordpress-develop.dev
$ cat wp-cli.yml
path: src/
```

--------------------------------

### Annotated wp-cli.yml configuration example

Source: https://make.wordpress.org/cli/handbook/config

This example demonstrates setting global defaults, subcommand-specific options, environment aliases, and alias groups. The '_' key is used to control configuration merging and inheritance behavior.

```yaml
# Global parameter defaults
path: wp-core
url: http://example.com
user: admin
color: false
disabled_commands:
  - db drop
  - plugin install
require:
  - path-to/command.php

# Subcommand defaults (e.g. `wp config create`)
config create:
    dbuser: root
    dbpass: 
    extra-php: |
        define( 'WP_DEBUG', true );
        define( 'WP_POST_REVISIONS', 50 );

# Aliases to other WordPress installs (e.g. `wp @staging rewrite flush`)
# An alias can include 'user', 'url', 'path', 'ssh', or 'http'
@staging:
    ssh: wpcli@staging.wp-cli.org
    user: wpcli
    path: /srv/www/staging.wp-cli.org
@production:
    ssh: wpcli@wp-cli.org:2222
    user: wpcli
    path: /srv/www/wp-cli.org

# Aliases can reference other aliases to create alias groups
# Alias groups can be nested
@both:
 - @staging
 - @production

# '_' is a special value denoting configuration options for this wp-cli.yml
_:
    # Merge subcommand defaults from the upstream config.yml, instead of overriding
    merge: true
    # Inherit configuration from an arbitrary YAML file
    inherit: prod.yml
```

--------------------------------

### Behat scenario using 'Then STDERR should be empty'

Source: https://make.wordpress.org/cli/handbook/references/behat-steps/then-stdout-stderr-should-be-empty

Example Behat scenario that runs 'wp plugin install akismet' and then asserts that STDERR is empty.

```gherkin
Scenario: My other scenario
  Given a WP install
  When I run `wp plugin install akismet`
  Then STDERR should be empty

```

--------------------------------

### Usage of Given a WP installation with Composer and a custom vendor directory

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-a-wp-installation-with-composer-and-a-custom-vendor-directory-vendor-directory

Examples showing how to use the step in a Behat scenario to specify a custom vendor directory named 'vendor-custom'.

```gherkin
Scenario: My example scenario
  Given a WP installation with Composer and a custom vendor directory 'vendor-custom'
  ...

Scenario: My other scenario
  Given a WP install with Composer with Composer and a custom vendor directory 'vendor-custom'
  ...
```

--------------------------------

### Start the web server with custom host and port

Source: https://make.wordpress.org/cli/handbook/how-to/how-to-start-webserver

Uses the --port and --host flags to specify a custom address and port for the web server.

```bash
    $ wp server --port=9090 --host=192.168.0.4
```

--------------------------------

### Example WP-CLI Command Class

Source: https://make.wordpress.org/cli/handbook/commands-cookbook

A complete example of a WP-CLI command class structure, including PHPDoc annotations for options and examples, and the registration call.

```php
<?php
/**
 * Implements example command.
 */
class Example_Command {

    /**
     * Prints a greeting.
     *
     * ## OPTIONS
     *
     * <name>
     * : The name of the person to greet.
     *
     * [--type=<type>]
     * : Whether or not to greet the person with success or error.
     * ---
     * default: success
     * options:
     *   - success
     *   - error
     * ---
     *
     * ## EXAMPLES
     *
     *     wp example hello Newman
     *
     * @when after_wp_load
     */
    function hello( $args, $assoc_args ) {
        list( $name ) = $args;

        // Print the message with type
        $type = $assoc_args['type'];
        WP_CLI::$type( "Hello, $name!" );
    }
}

WP_CLI::add_command( 'example', 'Example_Command' );
```

--------------------------------

### Start the web server with default settings

Source: https://make.wordpress.org/cli/handbook/how-to/how-to-start-webserver

Launches the PHP development server on localhost at port 8080. The output displays the server status and the document root.

```bash
    $ wp server
    PHP 7.2.24-0ubuntu0.18.04.4 Development Server started at Thu Jun  4 17:40:13 2020
    Listening on http://localhost:8080
    Document root is ../wpdemo.test
    Press Ctrl-C to quit.
```

--------------------------------

### List installed themes

Source: https://make.wordpress.org/cli/handbook/guides/common-tasks

Displays a list of all installed themes.

```bash
wp theme list
```

--------------------------------

### Install WP-CLI on CentOS

Source: https://make.wordpress.org/cli/handbook/guides/installing

Use yum to install WP-CLI on CentOS.

```bash
su -c 'yum install wp-cli'
```

--------------------------------

### Create project via Composer

Source: https://make.wordpress.org/cli/handbook/guides/installing

Install WP-CLI as a project using Composer.

```bash
composer create-project wp-cli/wp-cli-bundle --prefer-source
```

--------------------------------

### Create a wp-cli.yml file

Source: https://make.wordpress.org/cli/handbook/behat-steps/given-an-file-cache-file

Example of using the step to create a wp-cli.yml configuration file with specific YAML content.

```gherkin
Scenario: My example scenario
  Given a wp-cli.yml file:
    """
    @foo:
      path: foo
      user: admin
    """
```

--------------------------------

### Symlink custom install binary

Source: https://make.wordpress.org/cli/handbook/guides/installing

Symlink the binary after a custom installation.

```bash
sudo ln -s /usr/share/wp-cli-bundle/vendor/wp-cli/wp-cli/bin /usr/bin/wp
```

--------------------------------

### Example: Verifying a download hash

Source: https://make.wordpress.org/cli/handbook/internal-api/wp-cli-utils-http-request

An example showing how to use http_request() to fetch an MD5 hash file and verify the response status code.

```php
# `wp core download` verifies the hash for a downloaded WordPress archive

$md5_response = Utils\http_request( 'GET', $download_url . '.md5' );
if ( 20 != substr( $md5_response->status_code, 0, 2 ) ) {
     WP_CLI::error( "Couldn't access md5 hash for release (HTTP code {$response->status_code})" );
}
```

--------------------------------

### Global Composer installation

Source: https://make.wordpress.org/cli/handbook/guides/installing

Install WP-CLI globally using Composer.

```bash
composer global require wp-cli/wp-cli-bundle
```
Tokens:
Raw