config.md

Config

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;'
[email protected]

For repeated usage, WP-CLI can also read options from a YAML configuration file (e.g. wp-cli.yml). WP-CLI automatically discovers configuration files on the filesystem based on rules defined below. 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).

</tbody>

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, or a subset specified as comma-separated values. Default value: false	--prompt[=<assoc>]	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 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

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_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.

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