diff --git a/bin/handbook-manifest.json b/bin/handbook-manifest.json index 70cc71d6..c09877fa 100644 --- a/bin/handbook-manifest.json +++ b/bin/handbook-manifest.json @@ -5,6 +5,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/argument-syntax.md", "parent": "references" }, + "beginners-guide": { + "title": "Beginner's Guide", + "slug": "beginners-guide", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/beginners-guide.md", + "parent": "guides" + }, "behat-steps": { "title": "Behat Steps", "slug": "behat-steps", @@ -23,6 +29,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/contributions\/bug-reports.md", "parent": "contributions" }, + "cli-contributor-badge": { + "title": "WP-CLI Contributor Badge", + "slug": "cli-contributor-badge", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/contributions\/cli-contributor-badge.md", + "parent": "contributions" + }, "code-review": { "title": "Code Review", "slug": "code-review", @@ -47,6 +59,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/common-issues.md", "parent": "guides" }, + "common-tasks": { + "title": "Common Tasks with WP-CLI", + "slug": "common-tasks", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/common-tasks.md", + "parent": "guides" + }, "config": { "title": "Config", "slug": "config", @@ -131,6 +149,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/external-resources.md", "parent": "guides" }, + "figure-out-why-wordpress-is-slow": { + "title": "Figure out why WordPress is slow", + "slug": "figure-out-why-wordpress-is-slow", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/figure-out-why-wordpress-is-slow.md", + "parent": "how-to" + }, "force-output-specific-locale": { "title": "Force output to a specific locale", "slug": "force-output-specific-locale", @@ -347,12 +371,6 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/how-to-start-webserver.md", "parent": "how-to" }, - "figure-out-why-wordpress-is-slow": { - "title": "Figure out why WordPress is slow", - "slug": "figure-out-why-wordpress-is-slow", - "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/figure-out-why-wordpress-is-slow.md", - "parent": "how-to" - }, "identify-plugin-theme-conflict": { "title": "Identify a Plugin or Theme Conflict", "slug": "identify-plugin-theme-conflict", @@ -377,6 +395,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/installing.md", "parent": "guides" }, + "installing-packages": { + "title": "Installing WP-CLI Packages", + "slug": "installing-packages", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/installing-packages.md", + "parent": "guides" + }, "internal-api": { "title": "Internal API", "slug": "internal-api", @@ -850,11 +874,5 @@ "slug": "wp-cli-warning", "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/internal-api\/wp-cli-warning.md", "parent": "internal-api" - }, - "cli-contributor-badge": { - "title": "WP-CLI Contributor Badge", - "slug": "cli-contributor-badge", - "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/contributions\/cli-contributor-badge.md", - "parent": "contributions" } } \ No newline at end of file diff --git a/guides/beginners-guide.md b/guides/beginners-guide.md new file mode 100644 index 00000000..87dfadf6 --- /dev/null +++ b/guides/beginners-guide.md @@ -0,0 +1,175 @@ +# Beginner's Guide + +So you've heard about WP-CLI and want to try it out, but you're not sure where to start? This guide is for you. No programming experience required! + +This guide is designed to be read from start to finish. Each section builds on the previous one, taking you from opening a terminal for the first time all the way to running your first WP-CLI commands and getting help when you need it. + +## What Is the Command Line? + +When you use your computer, you normally interact with it by clicking on things — icons, buttons, menus. This is called a **graphical user interface (GUI)**. + +The **command line** (also called the terminal, shell, or console) is a different way to interact with your computer. Instead of clicking, you type text commands and press **Enter** to run them. It might look intimidating at first, but it's really just another way to tell your computer what to do. + +### Opening the Terminal + +**On macOS:** + +1. Press **Command (⌘) + Space** to open Spotlight Search. +2. Type `Terminal` and press **Enter**. +3. A window with a black or white background and a blinking cursor will appear. That's the terminal! + +**On Windows:** + +1. Press **Windows key + R** to open the Run dialog. +2. Type `cmd` and press **Enter**. +3. Alternatively, search for "Command Prompt" or "PowerShell" in the Start menu. + +> **Tip for Windows users:** WP-CLI works best with Git Bash or Windows Subsystem for Linux (WSL). You can download Git Bash from [git-scm.com](https://git-scm.com/downloads). + +**On Linux:** + +1. Look for "Terminal" in your applications menu, or press **Ctrl + Alt + T** on many distributions. + +### Basic Terminal Navigation + +Once the terminal is open, here are a few essential commands to know: + +| Command | What it does | +|---------|-------------| +| `pwd` | Shows the folder you are currently in | +| `ls` (macOS/Linux) or `dir` (Windows) | Lists files and folders in the current folder | +| `cd folder-name` | Moves into a folder named `folder-name` | +| `cd ..` | Goes up one folder level | +| `clear` | Clears the terminal screen | + +Don't worry — you don't need to memorize all of these right now. You can come back to this table whenever you need a reminder. + +## What Is WP-CLI? + +WP-CLI is a **command line interface for WordPress**. It lets you manage your WordPress website by typing commands in the terminal, instead of clicking through the WordPress admin dashboard. + +Think of it this way: anything you can do in the WordPress admin (installing plugins, creating users, updating settings), you can also do with WP-CLI — and usually much faster. + +### Why Should I Use WP-CLI? + +Here are a few reasons why even non-technical WordPress users find WP-CLI useful: + +- **Speed:** Update all your plugins with a single command instead of clicking through each one. +- **Automation:** Repeat the same tasks easily without navigating the admin every time. +- **Bulk actions:** Do things to many posts, users, or options all at once. +- **Remote management:** Manage a website on a remote server without opening a browser. +- **Reliability:** Less clicking means fewer mistakes. + +## Installing WP-CLI + +For step-by-step installation instructions on macOS, Linux, and Windows, see the [Installing](https://make.wordpress.org/cli/handbook/guides/installing/) guide. It covers system requirements, the recommended Phar download method, and alternative installation options such as Composer and Homebrew. + +## Running WP-CLI: Inside vs. Outside the WordPress Folder + +WP-CLI needs to know which WordPress installation to work with. By default, it looks for WordPress in your **current directory** (the folder your terminal is currently in). + +This means you generally need to `cd` into your WordPress site's folder before running WP-CLI commands. For example: + +``` +cd /var/www/mysite +wp plugin list +``` + +If you run `wp plugin list` from a folder that doesn't contain a WordPress installation, you'll get an error like: + +``` +Error: This does not seem to be a WordPress installation. +``` + +**Where is my WordPress folder?** + +- On a typical shared host, it's often something like `/home/username/public_html` or `/var/www/html`. +- If you use a local development tool like Local, MAMP, or XAMPP, each tool has its own folder structure — check its documentation. +- On managed WordPress hosts, WP-CLI may be pre-configured to work without needing to `cd` first. + +## Running Your First WP-CLI Command + +Navigate in your terminal to your WordPress folder (see [above](#running-wp-cli-inside-vs-outside-the-wordpress-folder)). For example: + +``` +cd /var/www/mysite +``` + +Then try this command: + +``` +wp --info +``` + +This displays information about your WP-CLI installation. If it works, you're ready to go! + +To see the version of WordPress you have installed: + +``` +wp core version +``` + +To list the plugins on your site: + +``` +wp plugin list +``` + +## Reading WP-CLI Output + +When you run a WP-CLI command, it prints a response in the terminal. Here's what the common messages mean: + +- **`Success:`** — The command worked as expected. +- **`Warning:`** — The command ran, but there's something you should know about. +- **`Error:`** — Something went wrong. Read the message to find out what. + +## Getting Help + +### Built-in help + +WP-CLI has built-in documentation for every command. If you get stuck, run `wp help` to see a list of all available commands: + +``` +wp help +``` + +To get help on a specific command, add the command name after `help`. For example: + +``` +wp help plugin +wp help plugin install +``` + +### Community support + +If the built-in help isn't enough, these resources can help: + +- **[WP-CLI Handbook](https://make.wordpress.org/cli/handbook/)** — The full reference documentation. +- **[GitHub Issues](https://github.com/wp-cli/wp-cli/issues)** — Report bugs or search for known problems. +- **[WordPress.org Support Forums](https://wordpress.org/support/)** — General WordPress help from the community. + +## Using WP-CLI on a Remote Server (SSH) + +If your WordPress site is hosted on a remote server (most live websites are), you can still use WP-CLI. There are two common approaches: + +1. **SSH into the server and run WP-CLI there.** Most hosts provide SSH access. Connect with a command like: + + ``` + ssh username@yoursite.com + ``` + + Then navigate to your WordPress folder and use WP-CLI normally. + +2. **Use WP-CLI's built-in SSH support.** WP-CLI can run commands on a remote server directly from your local machine. See the [Running Commands Remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/) guide for details. + +## Learning More + +Now that you've got the basics, here are some great next steps: + +- **[Common Tasks with WP-CLI](https://make.wordpress.org/cli/handbook/guides/common-tasks/)** — Practical examples for everyday WordPress management. +- **[Quick Start Guide](https://make.wordpress.org/cli/handbook/guides/quick-start/)** — A short walkthrough of WP-CLI with more examples. +- **[Running Commands Remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/)** — Manage your live site's server over SSH. +- **[All WP-CLI Commands](https://developer.wordpress.org/cli/commands/)** — The full list of commands available. +- **[External Resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** — Blog posts, slides, and videos from WP-CLI users. + +You don't need to learn everything at once. Start with a task you want to speed up, find the right command, and go from there! diff --git a/guides/common-tasks.md b/guides/common-tasks.md new file mode 100644 index 00000000..fd6bde06 --- /dev/null +++ b/guides/common-tasks.md @@ -0,0 +1,313 @@ +# Common Tasks with WP-CLI + +Not sure what you can do with WP-CLI? This page showcases practical, everyday WordPress management tasks you can accomplish from the command line — with examples you can use right away. + +> **New to the command line?** Start with the [Beginner's Guide](https://make.wordpress.org/cli/handbook/guides/beginners-guide/) first. + +## Plugins + +### Install a plugin + +``` +wp plugin install contact-form-7 +``` + +### Install and activate a plugin in one step + +``` +wp plugin install contact-form-7 --activate +``` + +### Activate an already-installed plugin + +``` +wp plugin activate contact-form-7 +``` + +### Deactivate a plugin + +``` +wp plugin deactivate contact-form-7 +``` + +### Update a specific plugin + +``` +wp plugin update akismet +``` + +### Update all plugins at once + +``` +wp plugin update --all +``` + +### List all installed plugins and their status + +``` +wp plugin list +``` + +### Delete a plugin + +``` +wp plugin delete hello +``` + +## Themes + +### Install a theme + +``` +wp theme install twentytwentyfour +``` + +### Activate a theme + +``` +wp theme activate twentytwentyfour +``` + +### Update all themes + +``` +wp theme update --all +``` + +### List all installed themes + +``` +wp theme list +``` + +## WordPress Core + +### Check which version of WordPress is installed + +``` +wp core version +``` + +### Check if a WordPress update is available + +``` +wp core check-update +``` + +### Update WordPress to the latest version + +``` +wp core update +``` + +### Update the WordPress database after an update + +``` +wp core update-db +``` + +## Users + +### List all users + +``` +wp user list +``` + +### Create a new user + +``` +wp user create jane jane@example.com --role=editor +``` + +### Change a user's password + +``` +wp user update jane --user_pass=newpassword +``` + +### Delete a user + +``` +wp user delete jane --reassign=1 +``` + +> **Tip:** The `--reassign=1` option moves the deleted user's posts to the user with ID 1 (usually the site admin). Replace `1` with the ID of the user you want to reassign posts to. + +### Add an administrator role to an existing user + +``` +wp user set-role jane administrator +``` + +## Posts and Pages + +### Create a new post + +``` +wp post create --post_title="My First Post" --post_status=publish --post_type=post +``` + +### Create a new page + +``` +wp post create --post_title="About Us" --post_status=publish --post_type=page +``` + +### List all published posts + +``` +wp post list --post_status=publish +``` + +### Delete a post (sends it to trash) + +``` +wp post delete 42 +``` + +### Permanently delete a post + +``` +wp post delete 42 --force +``` + +## Comments + +### List all comments awaiting moderation + +``` +wp comment list --status=hold +``` + +### Approve a comment + +``` +wp comment approve 5 +``` + +### Delete spam comments + +``` +wp comment delete $(wp comment list --status=spam --format=ids) +``` + +> **Note:** The `$(...)` syntax works in bash (macOS, Linux, Git Bash, or WSL on Windows). It does not work in Windows Command Prompt. Windows users should use Git Bash, WSL, or PowerShell to run this command. + +## Options and Settings + +### Get the site URL + +``` +wp option get siteurl +``` + +### Get the site title + +``` +wp option get blogname +``` + +### Change the site title + +``` +wp option update blogname "My New Site Title" +``` + +### Discourage search engines from indexing the site + +``` +wp option update blog_public 0 +``` + +### Re-enable search engine indexing + +``` +wp option update blog_public 1 +``` + +## Search and Replace + +### Preview what would change when moving a site to a new domain + +``` +wp search-replace 'http://oldsite.com' 'http://newsite.com' --dry-run +``` + +### Replace URLs when moving to a new domain + +``` +wp search-replace 'http://oldsite.com' 'http://newsite.com' +``` + +## Media + +### Regenerate all thumbnail sizes + +Useful after changing your theme or adding a new image size: + +``` +wp media regenerate --yes +``` + +## Caching + +### Flush the object cache + +``` +wp cache flush +``` + +### Flush rewrite rules (useful after adding a new plugin or changing permalink settings) + +``` +wp rewrite flush +``` + +## Database + +### Export the database to a file + +``` +wp db export backup.sql +``` + +### Import a database from a file + +``` +wp db import backup.sql +``` + +### Open an interactive database console + +``` +wp db cli +``` + +## WP-CLI Itself + +### Check the installed version of WP-CLI + +``` +wp cli version +``` + +### Update WP-CLI to the latest version + +``` +wp cli update +``` + +### Get system information useful for troubleshooting + +``` +wp --info +``` + +## Going Further + +These examples only scratch the surface. WP-CLI has commands for nearly every part of WordPress. To explore more: + +- Browse the [full list of built-in commands](https://developer.wordpress.org/cli/commands/). +- Read the [Quick Start Guide](https://make.wordpress.org/cli/handbook/guides/quick-start/) for a more detailed walkthrough. +- Check out [External Resources](https://make.wordpress.org/cli/handbook/guides/external-resources/) for tutorials, blog posts, and videos. diff --git a/guides/installing.md b/guides/installing.md index 1fef9151..ad2d5771 100644 --- a/guides/installing.md +++ b/guides/installing.md @@ -1,5 +1,15 @@ # Installing +## Requirements + +WP-CLI requires **PHP 7.2.24 or later**. To check the version of PHP available on your system, run: + +``` +php --version +``` + +WP-CLI has no additional requirements beyond those of WordPress itself. + ## Recommended installation The recommended way to install WP-CLI is by downloading the Phar build (archives similar to Java JAR files, [see this article for more detail](http://php.net/manual/en/phar.using.intro.php)), marking it executable, and placing it on your PATH. diff --git a/index.md b/index.md index 8b2a6885..c419e0ff 100644 --- a/index.md +++ b/index.md @@ -6,17 +6,24 @@ Can’t find what you’re looking for? [Open an issue](https://github.com/wp-cl ## Guides +### For users + +* **[Beginner's guide](https://make.wordpress.org/cli/handbook/guides/beginners-guide/)** - New to the command line? Start here for a beginner-friendly introduction to WP-CLI. +* **[Common tasks](https://make.wordpress.org/cli/handbook/guides/common-tasks/)** - A practical showcase of everyday WordPress management tasks you can do with WP-CLI. * **[Installing](https://make.wordpress.org/cli/handbook/guides/installing/)** - Recommended and alternative installation mechanisms. * **[Quick start](https://make.wordpress.org/cli/handbook/guides/quick-start/)** - Where to begin after you've installed WP-CLI for the first time. -* **[Running commands remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/)** - Learn how to remotely control multiple servers at once. -* **[Commands cookbook](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/)** - The full 101 how commands work, writing your own, and sharing them with the world. -* **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)** - How to write and run Behat tests for WP-CLI commands and packages. +* **[Running commands remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/)** - Learn how to remotely control multiple servers at once. * **[Common issues and their fixes](https://make.wordpress.org/cli/handbook/guides/common-issues/)** - In case of fire, break glass. * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users. +* **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Get help troubleshooting common WP-CLI issues. + +### For developers + +* **[Commands cookbook](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/)** - The full 101 how commands work, writing your own, and sharing them with the world. +* **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)** - How to write and run Behat tests for WP-CLI commands and packages. * **[Force output to a specific locale](https://make.wordpress.org/cli/handbook/guides/force-output-specific-locale/)** - Localisation issue -* **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advise +* **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advice * **[Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/)** - Some words about your environment -* **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Some help to troubleshoot ## References