Config Edit

WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is 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;'

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
$ 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 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 SSHSSH Secure SHell - a protocol for securely connecting to a remote system in addition to or in place of a password..

Default value: null
--ssh=[<user>@]<host>[:<port>][<path>] ssh: [<user>@]<host>[:<port>][<path>]
Perform operation against a remote WordPress install over HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands..

Default value: null
--http=<http> http: <http>
Pretend request came from given URLURL A specific web address of a website or web page on the Internet, such as a website’s URL In multisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core., 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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. 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 ApacheApache Apache is the most widely used web server software. Developed and maintained by Apache Software Foundation. Apache is an Open Source software available for free. Modules that are to be reported as loaded.

Default value: []
Not available as a flag apache_modules: <list>

Top ↑

Config files 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
user: admin
color: false
  - db drop
  - plugin install
  - path-to/command.php

# Subcommand defaults (e.g. `wp config create`)
config create:
    dbuser: root
    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'
    user: wpcli
    path: /srv/www/
    user: wpcli
    path: /srv/www/

# Aliases can reference other aliases to create alias groups
# Alias groups can be nested
 - @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

Top ↑

Environment variables 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

Last updated: