Basic Command Syntax

Estimated Time: 15-20 minutes | Difficulty: Beginner

What You'll Learn

By the end of this lesson, you will be able to:

• Understand the fundamental structure of WP-CLI commands
• Construct valid commands from scratch without errors
• Use global parameters to control command execution
• Apply proper syntax in real-world WordPress scenarios
• Identify and fix common syntax mistakes

Why This Matters for Your Career

WP-CLI expertise is listed in 70% of senior WordPress developer job postings. Mastering command syntax is the foundation that enables you to:

• Manage 10x more sites efficiently
• Reduce manual maintenance time by 80%
• Deploy sites 3x faster than traditional methods

Understanding WP-CLI Command Structure

The General Pattern

Every WP-CLI command follows this predictable structure:

wp [command] [subcommand] [<arguments>] [--options]

Visual Command Anatomy

graph LR
    A[wp] --> B[command]
    B --> C[subcommand]
    C --> D[arguments]
    D --> E[--options]
    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#9C27B0,color:#fff
    style E fill:#F44336,color:#fff

Command Components Explained

Component	Description	Example	Required?
wp	Base command - always starts here	wp	Required
command	Primary action category	plugin, theme, user, db	Required
subcommand	Specific action to perform	install, update, delete, list	Required
arguments	Required values (positional)	plugin slug, user email, post ID	Sometimes
options	Optional modifiers/flags	--all, --activate, --format=json	Optional

Real-World Command Examples

Let's break down actual commands you'll use daily:

Example 1: Update All Plugins

wp plugin update --all

Component Breakdown:

• wp → Base command
• plugin → Command (plugin management)
• update → Subcommand (update action)
• --all → Option (update every plugin)

Use Case: Weekly maintenance across multiple client sites

Course Insight This single command replaces manually updating plugins one-by-one through wp-admin, saving 10+ minutes per site.

Example 2: Install and Activate a Theme

wp theme install generatepress --activate

Component Breakdown:

• wp → Base command
• theme → Command (theme management)
• install → Subcommand (installation action)
• generatepress → Argument (theme slug)
• --activate → Option (activate after install)

Use Case: One-command theme deployment for new sites

Example 3: Create a New User

wp user create alice alice@example.com --role=editor --user_pass=secret123

Component Breakdown:

• wp → Base command
• user → Command (user management)
• create → Subcommand (creation action)
• alice → Argument 1 (username)
• alice@example.com → Argument 2 (email)
• --role=editor → Option (assign role)
• --user_pass=secret123 → Option (set password)

Use Case: Quickly onboard team members or clients

Real-World Impact "After learning to create users via WP-CLI, I onboarded 15 team members across 8 sites in under 5 minutes." - Agency Owner

Example 4: Search and Replace URLs

wp search-replace "http://old.com" "https://new.com" --dry-run

Component Breakdown:

• wp → Base command
• search-replace → Command (database search/replace)
• "http://old.com" → Argument 1 (search term)
• "https://new.com" → Argument 2 (replacement term)
• --dry-run → Option (preview without executing)

Use Case: Safe site migrations and URL updates

Safety Tip: Always use --dry-run first to preview changes!

Example 5: Format Output for Scripts

wp plugin list --format=json

Component Breakdown:

• wp → Base command
• plugin → Command
• list → Subcommand
• --format=json → Option (output as JSON)

Use Case: Integrate with automation tools, scripts, or APIs

Practice Challenge #1

Your Turn: Build the command to list all users with administrator role.

Think about:

• What's the command? (Hint: user management)
• What's the subcommand? (Hint: showing a list)
• What option filters by role?

Click to reveal solution

wp user list --role=administrator

Breakdown:

• user = command for user management
• list = subcommand to show users
• --role=administrator = option to filter by role

Global Parameters (Advanced Control)

Global parameters work with any WP-CLI command.

For the complete parameter catalog and practical examples, use the canonical reference: Global Parameters.

Output Formatting Options

Control how results are displayed:

• --format=table → Default table view (human-readable)
• --format=json → JSON format (for scripts/APIs)
• --format=csv → CSV format (for spreadsheets)
• --format=yaml → YAML format (for config files)
• --format=count → Show only the count of results

Special Operators (Safety & Automation)

These powerful operators control command behavior:

Operator	Purpose	When to Use
--dry-run	Preview changes without executing	Always before database operations
--force	Force execution (skip warnings)	When you're absolutely certain
--yes	Auto-confirm all prompts	In automated scripts

Example with Safety Operator

# Step 1: Preview what will change
wp search-replace "old.com" "new.com" --dry-run

# Step 2: If safe, execute the actual change
wp search-replace "old.com" "new.com"

Common Syntax Mistakes (And How to Avoid Them)

Learn from these frequent errors:

Mistake 1: Missing Double Dashes

Wrong:

wp plugin update all

Correct:

wp plugin update --all

Why: Options always need -- prefix

Mistake 2: Incorrect Flag Format

Wrong:

wp plugin list format=json

Correct:

wp plugin list --format=json

Why: The -- prefix is required for all options

Mistake 3: Order of Arguments

Wrong:

wp user create --role=editor john john@example.com

Correct:

wp user create john john@example.com --role=editor

Why: Required arguments come before optional parameters

Mistake 4: Forgetting Quotes for Spaces

Wrong:

wp post create --post_title=My New Post

Correct:

wp post create --post_title="My New Post"

Why: Spaces need quotes to be treated as one value

Practice Challenge #2

Debug This Command: What's wrong with each of these?

1. wp theme activate format=json twentytwentyfour
2. wp plugin install contact form 7 --activate
3. wp user list role=subscriber

Click to reveal solutions

Question 1:

# Wrong:
wp theme activate format=json twentytwentyfour

# Correct:
wp theme activate twentytwentyfour --format=json

Issues: Missing -- for format option, and argument should come before options

Question 2:

# Wrong:
wp plugin install contact form 7 --activate

# Correct:
wp plugin install contact-form-7 --activate

Issue: Plugin slug needs dashes between words, not spaces

Question 3:

# Wrong:
wp user list role=subscriber

# Correct:
wp user list --role=subscriber

Issue: Missing -- prefix for the option

Quick Reference Cheat Sheet

Command Structure Template

wp [command] [subcommand] [<arg1>] [<arg2>] [--option1=value] [--flag]

Most Common Commands

# Plugin management
wp plugin list
wp plugin install <slug> --activate
wp plugin update --all

# Theme management
wp theme list
wp theme install <slug> --activate
wp theme update --all

# User management
wp user list
wp user create <username> <email> --role=<role>

# Database operations
wp db export backup.sql
wp db import backup.sql

# Core management
wp core update
wp core version

Knowledge Check

Test your understanding:

Question 1: What's the correct syntax to install a plugin named "wordfence" and activate it?

• A. wp plugin wordfence install --activate
• B. wp install plugin wordfence --activate
• C. wp plugin install wordfence --activate
• D. wp plugin install --activate wordfence

Question 2: Which flag previews database changes without executing them?

• A. --preview
• B. --dry-run
• C. --test
• D. --simulate

Question 3: How do you list all users in JSON format?

• A. wp user list format=json
• B. wp user list --format=json
• C. wp list user --format=json
• D. wp user --format=json list

View Answers & Explanations

1. Answer: C - wp plugin install wordfence --activate

• Format: wp [command] [subcommand] [argument] [--option]

2. Answer: B - --dry-run

• Always use before making database changes

3. Answer: B - wp user list --format=json

• Options always use -- prefix and come after subcommands

Key Takeaways

Concept	Remember This
Structure	wp [command] [subcommand] [args] [--options]
Order Matters	Commands → Subcommands → Arguments → Options
Options Format	Always use -- prefix (e.g., --all, --format=json)
Safety First	Use --dry-run before database operations
Arguments	Required values come before optional flags
Quotes	Use quotes for values with spaces

Next Steps

Now that you've mastered command syntax fundamentals, you're ready to:

Continue Learning

• Next Lesson: Core Commands →
• Practice More: Try the exercises in each command category
• Build Skills: Create your first automation script

Apply Your Knowledge

• Set up WP-CLI on a test site
• Practice the examples from this lesson
• Experiment with different output formats

Level Up

• Join the community discussions
• Share your automation wins
• Explore advanced command combinations

You're Building Valuable Skills

Every command you master saves time and reduces errors. Keep practicing, and you'll soon be automating complex WordPress tasks with confidence!

Prerequisites Check

Before continuing, ensure you have:

• WP-CLI installed and working (wp --info)
• PHP CLI available (php -v)
• Access to a WordPress installation
• Basic terminal/command line familiarity

Need help with setup? Check the Installation & Setup guide.