Global Options

Global options (parameters, arguments) can be applied to any command. These parameters behave the same for any command. They affect how WP-CLI interacts with WordPress in General.

List of global options

--path={path}
Path to the WordPress files.
--url={url}
Pretend request came from given URL. In multisite, this argument is how the target site is specified.
--ssh=[{scheme}:][{user}@]{host|container}[:{port}][{path}]
Perform operation against a remote server over SSH (or a container using scheme of “docker”, “docker-compose”, “vagrant”).
--http={http}
Perform operation against a remote WordPress install over HTTP.
--user={id|login|email}
Set the WordPress user.
--skip-plugins[={plugins}]
Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded.
--skip-themes[={themes}]
Skip loading all themes, or a comma-separated list of themes.
--skip-packages
Skip loading all installed packages.
--require={path}
Load PHP file before running the command (may be used more than once).
--[no-]color
Whether to colorize the output.
--debug[={group}]
Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help.
--prompt[={assoc}]
Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values.
--quiet
Suppress informational messages.
--context

allows users to select the WordPress context in which WP-CLI is supposed to execute its command(s).

  • cli: The context which has been the default before introduction of this flag. This is something in-between a frontend and an admin request, to get around some of the quirks of WordPress when running on the console.

  • admin: A context that simulates running a command as if it would be executed in the administration backend. This is meant to be used to get around issues with plugins that limit functionality behind an is_admin() check.

  • auto: Switches between cli and admin depending on which command is being used. For this initial release, all wp plugin * and wp theme * commands will use admin, while all other commands will use cli.

  • frontend: [WIP] This does nothing yet.

Where

  • [] - you can specify or you can omit.
  • {} - the values in braces are the variable values of the parameter.
  • | - this symbol indicates that you can specify either one or the other value.
Examples

Let's get all the Metafields of post 18 for the network site woman.example.com:

wp post meta list 18 --url=woman.example.com

Run the command from any directory, you need to specify WP path in this case (where the file wp-settings.php is located):

wp post meta list 1 --path=/home/kama/sites/wp-kama.dev/public_html/core/

Execute the PHP file before running the command:

wp post meta list 1 --require=/path/to/file.php

Config files

WP-CLI can automatically discover and 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 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: [email protected]
	user: wpcli
	path: /srv/www/staging.wp-cli.org
@production:
	ssh: [email protected]: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

Note the disabled_commands config it allows you to specify a list of commands that cannot be run.

Environment variables

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

  • WP_CLI_CACHE_DIR – Directory to store the WP-CLI file cache. Default is ~/.wp-cli/cache/.
  • WP_CLI_CONFIG_PATH – Path to the global config.yml file. Default is ~/.wp-cli/config.yml.
  • WP_CLI_CUSTOM_SHELL – Allows the user to override the default /bin/bash shell used.
  • WP_CLI_DISABLE_AUTO_CHECK_UPDATE – Disable WP-CLI automatic checks for updates.
  • WP_CLI_PACKAGES_DIR – Directory to store packages installed through WP-CLI’s package management. Default is ~/.wp-cli/packages/.
  • WP_CLI_PHP – PHP binary path to use when overriding the system default (only works for non-Phar installation).
  • WP_CLI_PHP_ARGS – Arguments to pass to the PHP binary when invoking WP-CLI (only works for non-Phar installation).
  • WP_CLI_SSH_PRE_CMD – When using --ssh=<ssh>, perform a command before WP-CLI calls WP-CLI on the remote server.
  • WP_CLI_STRICT_ARGS_MODE – Avoid ambiguity by telling WP-CLI to treat any arguments before the command as global, and after the command as local.
  • WP_CLI_SUPPRESS_GLOBAL_PARAMS – Set to true to skip showing the global parameters at the end of the help screen. This saves screen estate for advanced users.

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