DOCSEARCHbyAlgolia
Submit Docs

WP-CLI Handbook

repository·main·Indexed 42 days ago

https://github.com/wp-cli/handbook

Documentation and command reference for WP-CLI, the command-line interface for WordPress. Includes detailed guides and manifests for command groups such as core, db, plugin, post, option, and package, as well as instructions for generating handbook documentation locally using the wp handbook command series.

Tokens
276.1K
Snippets
1.2K
Records
1.4K
Agent score
51%

What's inside WP-CLI

  1. Manage WordPress themes with wp theme

    main
    The wp theme command allows you to manage WordPress themes, including installing, activating, updating, and retrieving information about installed themes. For deep architectural details on how themes function, refer to the WordPress Theme Handbook.

  2. Use wp i18n to manage internationalization

    main
    The wp i18n command group provides tools for managing internationalization (i18n) in WordPress projects. By default, these commands execute on the before_wp_load hook, meaning they run before the full WordPress environment is loaded, unless specifically overridden.

  3. Manage WordPress installation aliases with wp cli alias

    main
    Aliases are shorthand references to WordPress installations (e.g., @dev or @prod). Use the wp cli alias command to retrieve, set, and update these references. By default, these commands run on the before_wp_load hook, meaning they execute before the WordPress environment is fully loaded.

  5. Understand WP-CLI core concepts: Commands, Synopsis, and Arguments

    main

    To use WP-CLI effectively, you should understand its basic structural components:

    • Command: An atomic unit of functionality (e.g., wp plugin install). Commands are registered via WP_CLI::add_command().
    • Synopsis: The definition of how a command is structured, showing which arguments it accepts.
    • Positional Arguments: Arguments defined by their position in the command string (e.g., <plugin|zip|url>...).
    • Associative Arguments: Arguments defined by a flag/key (e.g., --version=<version>). In a synopsis, square brackets [] indicate that an argument is optional.
    • Global Arguments: Arguments that work with all commands, such as --debug, which displays PHP errors and adds verbosity to the bootstrap process.

  6. Design principles for WP-CLI commands

    main

    WP-CLI is designed to be the fastest and canonical way to manage WordPress. When developing or using commands, follow these core principles:

    • Simplicity and Scope: Commands should solve one unique problem and interact directly with WordPress. If a command implements existing WordPress functionality (e.g., wp export), it should mirror existing WordPress behavior. If it adds new functionality (e.g., wp search-replace), it should address a specific user need that has prior art in the ecosystem.
    • Consistency: Commands should emulate one another using consistent usage behavior, argument names, and documentation.
    • Decisions over Options: Avoid overwhelming users with technical choices. Prioritize improving default behavior. Add options sparingly; a command with more than six options becomes difficult to understand.
    • Composability and Orthogonality: Commands should be designed to work in pipelines (the output of one command should be pipe-able to another). Commands should be orthogonal, meaning they have no overlapping functionality (with specific exceptions like wp plugin install --activate).
    • Readability: Parameter names should be self-documenting, as most commands are used non-interactively.
    • Zero Assumptions: Bundled commands must work on any valid WordPress installation regardless of configuration or data volume. They must not assume the presence of specific plugins or themes.

  7. Querying databases in a WordPress Multisite environment

    main

    The global --url parameter has no effect on wp db query. To query data for a specific site in a multisite installation, you must manually specify the table prefix that includes the site's ID (e.g., wp_2_options for site ID 2).

    You can find the correct blog_id for your target site by running wp site list --fields=blog_id,url.

    # Get the home option for the second site (blog_id 2)
$ wp db query 'SELECT option_value FROM wp_2_options WHERE option_name="home"' --skip-column-names

# Confirm site IDs
$ wp site list --fields=blog_id,url

  8. Understand WP-CLI exit codes

    main

    WP-CLI follows standard Unix exit code conventions to signal the outcome of a command. This allows scripts to programmatically determine if a command succeeded or failed.

    • 0: Success. The command completed as expected.
    • 1: Failure. This can represent an operational error (e.g., invalid arguments, WordPress not found, fatal error) or an expected negative result for boolean-result commands.

    When developing commands:

    • Use WP_CLI::error() to report a failure and exit with code 1.
    • Use WP_CLI::halt() to exit with a specific non-zero code to communicate a particular outcome to a calling script.
    | Exit code | Meaning |
|:----------|:--------|
| `0` | Command completed successfully. The requested operation was performed as expected. |
| `1` | Command failed. WP-CLI could not perform the operation as expected (e.g. invalid arguments, WordPress not found, a fatal error was encountered). |

  9. Use Associative, Repeatable, and Variadic arguments

    main

    WP-CLI supports advanced argument types for complex commands:

    • Associative Arguments: Accepts arbitrary key-value pairs using --key=value (e.g., --foo=bar --baz=qux).
    • Repeatable Arguments: Options that can be provided multiple times (e.g., --require=/path/one.php --require=/path/two.php).
    • Variadic Arguments: Arguments that accept multiple values, indicated by an ellipsis ... (e.g., <file>...).
    # Associative arguments
wp cron event schedule my_hook --foo=bar --baz=qux

# Repeatable arguments
wp plugin install --require=/path/one.php --require=/path/two.php

# Variadic arguments (multiple values)
wp plugin install plugin1 plugin2 plugin3

  10. How WP-CLI bootstraps WordPress

    main

    WP-CLI follows a bootstrapping process similar to a web request but with key differences to ensure compatibility and isolation.

    1. Parsing wp-config.php: Instead of executing the file directly, WP-CLI parses wp-config.php to extract the require_once ABSPATH . 'wp-settings.php'; statement and loads constants into scope using eval(). This is maintained for backwards compatibility.
    2. Isolated Loading: WordPress is loaded via the WP_CLI::get_runner()->load_wordpress() method.

    Important for Plugin/Theme Developers: Because WordPress is loaded inside a function, plugins and themes are not loaded in the global scope. If your code relies on global variables, you must explicitly declare them as global within your functions to access them.

  11. Using Milestones and Labels for organization

    main

    Milestones and labels are used to track progress and organize the issue tracker across all WP-CLI packages.

    Milestones

    • Purpose: Open milestones typically represent the next upcoming release.
    • Usage: Both issues and pull requests (PRs) must be assigned to the upcoming milestone to ensure they are included in the generated release notes.

    Label Groups

    Labels are categorized into semantic groups using specific prefixes:

    Command Labels (command:)

    Defines the specific command the issue/PR applies to.

    • Example: command:cli-update or command:core.

    Scope Labels (scope:)

    Defines the area of the ecosystem affected:

    • scope:bootstrap: The bootstrap process (loading WP-CLI and WordPress Core).
    • scope:distribution: The distribution process (Phar building and releases).
    • scope:documentation: Handbook, command reference, or inline help.
    • scope:framework: The WP-CLI architecture, API, and helper functions.
    • scope:testing: Unit or functional tests.
    • scope:website: Infrastructure on wp-cli.org or make.wordpress.org.

    State Labels (state:)

    Defines the current status of the issue:

    • state:unconfirmed: The bug could not be replicated or is environment-specific.
    • state:unsupported: The issue is outside the scope of GitHub support (redirect to official support channels).

    Required Labels

    These labels are mandatory across all official packages:

    • bug: A confirmed bug where code does not produce expected results (unexpected behavior of existing functionality).
    • upstream-bug: A bug in upstream software (e.g., WordPress core, PHP) that will not be fixed in WP-CLI.
    • good-first-issue: Small-scope issues suitable for new contributors.

  12. Run WP-CLI commands within a WordPress installation

    main

    WP-CLI identifies which WordPress installation to manage by looking at your current directory. You must use the cd command to navigate into your WordPress site's root folder before running commands.

    If you run a command from a directory that does not contain a WordPress installation, you will receive the following error: Error: This does not seem to be a WordPress installation.

    cd /var/www/mysite
wp plugin list