WP-CLI

A command line interface for WordPress

Configuration

Quick links: Overview | Global parameters | Config files | Environment variables

Overview

WP-CLI has a series of global parameters (e.g. --path=<path> and --user=<user>) which work with all commands. They are called global parameters because they affect how WP-CLI interacts with WordPress, and have the same behavior across all commands.

# `--user=<user>` sets request to a specific WordPress user
$ wp --user=wpcli eval 'echo wp_get_current_user()->user_email;'
wpcli@example.com

For repeated usage, WP-CLI can also read options from a YAML configuration file (e.g. wp-cli.yml). These configuration files enable specifying default values for both global parameters and subcommand-specific arguments.

# 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/

Arguments are interpreted following an order of precedence, from highest priority to lowest:

  1. Command-line arguments.
  2. wp-cli.local.yml file inside the current working directory (or upwards).
  3. wp-cli.yml file inside the current working directory (or upwards).
  4. ~/.wp-cli/config.yml file (path can be changed by setting the WP_CLI_CONFIG_PATH environment variable).
  5. WP-CLI defaults.

Global parameters

The table below lists the available arguments (specified on the command-line) and options (specified in the configuration file).

Description Argument Option
Path to the WordPress files.
Default value: null
--path=<path> path: <path>
Perform operation against a remote server over SSH.
Default value: null
--ssh=[<user>@]<host>[:<port>][<path>] ssh: [<user>@]<host>[:<port>][<path>]
Perform operation against a remote WordPress install over HTTP.
Default value: null
--http=<http> http: <http>
Pretend request came from given URL. In multisite, this argument is how the target site is specified.
Default value: null
--url=<url> url: <url>
Set the WordPress user.
Default value: null
--user=<id|login|email> user: <id|login|email>
Skip loading all or some plugins. Note: mu-plugins are still loaded.
Default value: ""
--skip-plugins[=<plugin>] skip-plugins: <list>
Skip loading all or some themes.
Default value: ""
--skip-themes[=<theme>] skip-themes: <list>
Skip loading all installed packages.
Default value: false
--skip-packages skip-packages: <bool>
Load PHP file before running the command (may be used more than once).
Default value: []
--require=<path> require: <path>
(Sub)commands to disable.
Default value: []
Not available as a flag disabled_commands: <list>
Whether to colorize the output.
Default value: "auto"
--[no-]color color: <bool>
Show all PHP errors; add verbosity to WP-CLI bootstrap.
Default value: false
--debug[=<group>] debug: <group>
Prompt the user to enter values for all command arguments.
Default value: false
--prompt Not available as an option
Suppress informational messages.
Default value: false
--quiet quiet: <bool>
List of Apache Modules that are to be reported as loaded.
Default value: []
Not available as a flag apache_modules: <list>

Config files

WP-CLI can read options from a few configuration file types (when present):

  1. wp-cli.local.yml file inside the current working directory (or upwards).
  2. wp-cli.yml file inside the current working directory (or upwards).
  3. ~/.wp-cli/config.yml file (path can be changed by setting the WP_CLI_CONFIG_PATH environment variable).

Besides the global parameters described above, configuration files can also contain defaults for any subcommand, as well as aliases to one or more WordPress installs.

Here’s an annotated example wp-cli.yml file:

# 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 core config`)
core config:
	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

# '_' 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

Environment variables

WP-CLI’s behavior can be changed at runtime through the use of environment variables:

To set an environment variable on demand, simply place the environment variable definition before the WP-CLI command you mean to run.

# Use vim to edit a post
$ EDITOR=vim wp post edit 1

To set the same environment variable value for every shell session, you’ll need to include the environment variable definition in your ~/.bashrc or ~/.zshrc file

# Always use vim to edit a post
export EDITOR=vim