آموزش WP-CLI: ۳۰ دستور کاربردی برای مدیریت، مهاجرت و عیب‌یابی وردپرس

WP-CLI رابط خط فرمان رسمی وردپرس است. هر کاری که از پیشخوان انجام می‌دهید، از نصب افزونه تا ریست رمز مدیر و جابه‌جایی کامل سایت، با یک دستور و در کسری از زمان انجام می‌شود و قابل اسکریپت‌نویسی است. این راهنما ۳۰ دستوری را که در کار روزمره‌ی توسعه و نگهداری وردپرس بیشترین استفاده را دارند با مثال واقعی توضیح می‌دهد، یک مهاجرت کامل را قدم‌به‌قدم انجام می‌دهد و در پایان دستورهای جدید نسخه‌ی ۳ برای وردپرس ۷ را معرفی می‌کند.

آنچه در این آموزش یاد می‌گیرید

• نصب WP-CLI روی سرور، هاست اشتراکی و ویندوز و تأیید نصب

• دستورهای هسته، افزونه، قالب و کاربر که جای چندین کلیک در پیشخوان را می‌گیرند

• پشتیبان‌گیری، بازگردانی و بهینه‌سازی دیتابیس بدون phpMyAdmin

• جست‌وجو و جایگزینی امن دامنه در دیتابیس و مهاجرت کامل سایت با پنج دستور

• عیب‌یابی وقتی پیشخوان در دسترس نیست: صفحه‌ی سفید، هک، کرون و پیوندهای یکتا

• پرچم‌های سراسری، خروجی JSON، alias برای چند سرور و اسکریپت پشتیبان خودکار

• دستورهای جدید نسخه‌ی ۳: wp block، wp ability و wp ai برای وردپرس ۷

WP-CLI چیست و چرا هر توسعه‌دهنده‌ای به آن نیاز دارد؟

WP-CLI یک برنامه‌ی PHP است که وردپرس شما را بدون مرورگر بارگذاری می‌کند و به همه‌ی توابع آن دسترسی دارد. وقتی می‌نویسید wp plugin update --all، همان کدی اجرا می‌شود که پیشخوان اجرا می‌کند، فقط بدون رابط گرافیکی، بدون محدودیت زمان اجرای PHP در مرورگر و با قابلیت تکرار در اسکریپت و کران‌جاب. سه مزیت عملی آن برای کار روزمره: سرعت (آپدیت بیست افزونه در چند ثانیه)، دسترسی در شرایط بحرانی (وقتی پیشخوان صفحه‌ی سفید می‌دهد) و خودکارسازی (پشتیبان شبانه، استقرار، مدیریت ده‌ها سایت از یک جا).

نسخه‌ی پایدار فعلی ۲.۱۲ است که از PHP ۸.۴ پشتیبانی می‌کند. نسخه‌ی ۳ در حال توسعه است و دستورهای جدیدی برای بلاک‌ها، Abilities API و AI Client وردپرس ۷ می‌آورد که در بخش پایانی به آن‌ها می‌رسیم.

نصب WP-CLI

نصب سه قدم بیشتر نیست. WP-CLI یک فایل Phar است و به چیزی جز PHP نیاز ندارد.

سرور لینوکسی با دسترسی sudo

# ۱) دانلود
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

# ۲) تست قبل از نصب
php wp-cli.phar --info

# ۳) اجرایی کردن و انتقال به PATH
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

# ۴) بررسی و به‌روزرسانی
wp --info
wp cli update

خروجی wp --info نسخه‌ی PHP، مسیر php.ini و نسخه‌ی WP-CLI را نشان می‌دهد. اگر PHP خط فرمان با PHP وب‌سرور فرق دارد (مثلاً ۷.۴ در مقابل ۸.۳)، ابتدا این را درست کنید؛ بسیاری از خطاهای عجیب WP-CLI از همین اختلاف نسخه می‌آید.

هاست اشتراکی بدون sudo

بیشتر هاست‌های ایرانی که دسترسی SSH می‌دهند WP-CLI را از قبل نصب کرده‌اند؛ با wp --info امتحان کنید. اگر نبود، نصب در پوشه‌ی خانگی کافی است:

# در هاست اشتراکی بدون دسترسی sudo: نصب در پوشه‌ی خانگی
mkdir -p ~/bin && mv wp-cli.phar ~/bin/wp && chmod +x ~/bin/wp
echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
wp --info

ویندوز و محیط لوکال

در ویندوز ساده‌ترین راه WSL است و همان دستورهای لینوکس کار می‌کند. Laragon و LocalWP هم WP-CLI را همراه خود دارند. اگر با داکر کار می‌کنید ایمیج رسمی wordpress:cli را کنار کانتینر وردپرس بالا بیاورید و در wp-env (ابزار رسمی توسعه‌ی بلاک) با npx wp-env run cli wp ... دستورها را اجرا کنید.

دستورهای پایه: هسته، افزونه، قالب و کاربر

الگوی همه‌ی دستورها یکی است. با wp help و wp help <گروه> مستندات کامل را همان‌جا در ترمینال می‌خوانید.

نصب و به‌روزرسانی هسته

# دانلود وردپرس فارسی، ساخت wp-config و نصب در یک نفس
wp core download --locale=fa_IR
wp config create --dbname=wpkala --dbuser=wpkala --dbpass='رمز-قوی' --dbhost=localhost --dbcharset=utf8mb4
wp core install --url=https://example.ir --title="وردپرس کالا" --admin_user=modir --admin_password='رمز-قوی' --admin_email=info@example.ir

# نسخه و به‌روزرسانی
wp core version --extra
wp core check-update
wp core update && wp core update-db

# سلامت فایل‌های هسته
wp core verify-checksums

دستور wp core verify-checksums هر فایل هسته را با نسخه‌ی رسمی مقایسه می‌کند و فایل‌های تغییریافته یا اضافه را فهرست می‌کند. این سریع‌ترین راه برای تشخیص آلودگی هسته بعد از هک است. همین کار را برای افزونه‌های مخزن با wp plugin verify-checksums --all انجام دهید.

افزونه و قالب

# نصب و فعال‌سازی چند افزونه با هم
wp plugin install wordpress-seo contact-form-7 --activate

# کدام افزونه‌ها آپدیت دارند؟
wp plugin list --update=available --format=table

# به‌روزرسانی همه به جز یکی
wp plugin update --all --exclude=woocommerce

# غیرفعال کردن همه برای عیب‌یابی و برگرداندن بعدش
wp plugin deactivate --all
wp plugin activate --all

# نصب از آدرس یا فایل زیپ
wp plugin install https://example.ir/files/my-plugin.zip --activate
wp plugin install ./wpkala-blocks.zip --activate

# قالب
wp theme list --status=active
wp theme activate twentytwentyfive
wp theme delete --all --force   # همه به جز قالب فعال

کاربران

# ساخت کاربر با نقش
wp user create ali ali@example.ir --role=editor --display_name="علی رضایی" --user_pass='رمز-قوی'

# ریست رمز مدیر وقتی ایمیل بازیابی کار نمی‌کند
wp user update modir --user_pass='رمز-جدید-قوی'

# خروج از همه‌ی نشست‌های یک کاربر (بعد از نشت رمز)
wp user session destroy modir --all

# فهرست مدیران با تاریخ ثبت‌نام
wp user list --role=administrator --fields=ID,user_login,user_email,user_registered

# حذف کاربر و انتقال نوشته‌هایش به کاربر دیگر
wp user delete 15 --reassign=2

ریست رمز با WP-CLI برای مواقعی است که ایمیل بازیابی به دست کاربر نمی‌رسد یا مهاجم ایمیل حساب را عوض کرده. بعد از هر تغییر رمز، نشست‌های فعال را هم با wp user session destroy ببندید وگرنه کسی که وارد شده وارد می‌ماند.

پایگاه داده: پشتیبان، بازگردانی و بهینه‌سازی

# پشتیبان‌گیری فشرده با تاریخ در نام فایل
wp db export - | gzip > backup-$(date +%F).sql.gz

# بازگردانی
gunzip -c backup-1405-07-20.sql.gz | wp db import -

# بررسی و بهینه‌سازی جدول‌ها
wp db check
wp db optimize

# حجم هر جدول
wp db size --tables --human-readable

# اجرای مستقیم SQL
wp db query "SELECT option_name, LENGTH(option_value) AS size FROM wp_options WHERE autoload='yes' ORDER BY size DESC LIMIT 10"

خروجی wp db export با mysqldump ساخته می‌شود و با هر ابزار استانداردی سازگار است. نوشتن به خروجی استاندارد (خط تیره به جای نام فایل) اجازه می‌دهد همان لحظه فشرده کنید و فضای دیسک را هدر ندهید. آخرین دستور، ده گزینه‌ی سنگینی را که در هر بار بارگذاری سایت خوانده می‌شوند نشان می‌دهد؛ معمولاً مقصر کندی سایت‌های قدیمی همین‌جاست.

جست‌وجو و جایگزینی امن در دیتابیس

تغییر دامنه یا انتقال از http به https یعنی هزاران آدرس در جدول‌های مختلف باید عوض شوند. مشکل این‌جاست که وردپرس بخشی از داده‌ها را به صورت سریالایزشده (با طول رشته) ذخیره می‌کند و جایگزینی ساده در فایل SQL آن‌ها را خراب می‌کند. دستور wp search-replace این داده‌ها را می‌شناسد، طول‌ها را دوباره محاسبه می‌کند و تنها راه مطمئن برای این کار است.

# اول همیشه تمرین خشک: فقط می‌شمارد، چیزی تغییر نمی‌دهد
wp search-replace 'http://old.ir' 'https://new.ir' --all-tables --dry-run

# اجرای واقعی با حفظ guid
wp search-replace 'http://old.ir' 'https://new.ir' --all-tables --skip-columns=guid

# گزارش دقیق تغییرات هر جدول
wp search-replace 'old.ir' 'new.ir' --all-tables --report-changed-only

# فقط در جدول‌های مشخص
wp search-replace '/old/path' '/new/path' wp_posts wp_postmeta

• همیشه با --dry-run شروع کنید. تعداد تغییرات هر جدول را می‌بینید و اگر عدد عجیبی دیدید (مثلاً تغییر در جدول users) قبل از خرابی متوجه می‌شوید.

• guid را رد کنید. ستون guid شناسه‌ی یکتای هر نوشته برای فیدخوان‌هاست و وردپرس توصیه می‌کند هرگز تغییر نکند.

• --all-tables را فراموش نکنید. بدون آن فقط جدول‌های با پیشوند فعلی جست‌وجو می‌شوند و جدول‌های افزونه‌هایی با پیشوند متفاوت جا می‌مانند.

مهاجرت کامل سایت با پنج دستور

کل فرآیند مهاجرت. بدون محدودیت حجم، بدون فایل موقت چند گیگابایتی و قابل تکرار برای استقرارهای بعدی.

این سناریو یک سایت را از سرور قدیم به سرور جدید با دامنه‌ی جدید منتقل می‌کند. فرض بر این است که روی هر دو سرور SSH و WP-CLI دارید و روی سرور جدید دیتابیس خالی ساخته شده است:

# روی سرور قدیم
wp maintenance-mode activate
wp db export site.sql
rsync -az --exclude=wp-content/cache ./ user@new-server:/var/www/site/

# روی سرور جدید (داخل پوشه‌ی سایت)
wp config set DB_NAME new_db
wp config set DB_USER new_user
wp config set DB_PASSWORD 'رمز-جدید'
wp db import site.sql
wp search-replace 'https://old.ir' 'https://new.ir' --all-tables --skip-columns=guid
wp cache flush
wp rewrite flush --hard
wp maintenance-mode deactivate
wp core verify-checksums

1. حالت تعمیر را فعال می‌کنیم تا در لحظه‌ی خروجی گرفتن سفارش یا دیدگاه جدیدی ثبت نشود.

2. دیتابیس را خروجی می‌گیریم و فایل‌ها را با rsync منتقل می‌کنیم. پوشه‌ی کش را رد می‌کنیم چون روی سرور جدید دوباره ساخته می‌شود.

3. اطلاعات اتصال دیتابیس را با wp config set تغییر می‌دهیم؛ نیازی به ویرایش دستی wp-config.php نیست.

4. دیتابیس را وارد و دامنه را جایگزین می‌کنیم. اگر پروتکل هم عوض شده (http به https) آدرس کامل را بدهید تا هر دو یک‌جا اصلاح شود.

5. کش و قوانین پیوند یکتا را بازسازی می‌کنیم و در پایان سلامت فایل‌های هسته را تأیید می‌کنیم.

محتوا، رسانه و دسته‌بندی

# فهرست نوشته‌ها با فیلتر و خروجی JSON
wp post list --post_type=post --post_status=publish --fields=ID,post_title,post_date --format=json

# ساخت نوشته از فایل متنی
wp post create ./article.html --post_type=post --post_status=draft --post_title="عنوان مقاله" --post_author=1

# حذف همه‌ی بازبینی‌ها
wp post delete $(wp post list --post_type=revision --format=ids) --force

# بازسازی اندازه‌های تصویر بعد از تغییر قالب
wp media regenerate --yes

# فقط تصاویر یک نوشته
wp media regenerate --image_size=large --yes 123

# وارد کردن تصویر و اتصال به نوشته
wp media import ./cover.webp --post_id=123 --featured_image --alt="متن جایگزین"

# دسته‌ها و برچسب‌ها
wp term list category --fields=term_id,name,slug,count
wp term create category "هوش مصنوعی" --slug=ai

حذف بازبینی‌ها (revisions) در سایت‌های قدیمی گاهی نصف حجم جدول posts را آزاد می‌کند. ترکیب --format=ids با دستور دیگر الگویی است که در WP-CLI زیاد تکرار می‌شود: یک دستور فهرست شناسه‌ها را می‌دهد و دستور دوم روی همه‌ی آن‌ها کار می‌کند.

کش، کرون، تنظیمات و wp-config

# کش آبجکت و transient ها
wp cache flush
wp transient delete --expired
wp transient delete --all

# کرون
wp cron event list
wp cron event run --due-now
wp cron event run wp_version_check

# تنظیمات (option)
wp option get siteurl
wp option update blogdescription "فروشگاه قالب و افزونه‌ی وردپرس"
wp option patch update woocommerce_currency_pos right_space

# تنظیمات wp-config
wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_MEMORY_LIMIT 256M
wp config list

کرون وردپرس به بازدید کاربر وابسته است و در سایت‌های کم‌بازدید عقب می‌افتد. راه حرفه‌ای این است که در wp-config مقدار DISABLE_WP_CRON را true کنید و یک کران‌جاب واقعی هر پنج دقیقه wp cron event run --due-now را اجرا کند. زمان‌بندی انتشار نوشته‌ها، پشتیبان افزونه‌ها و ایمیل‌های ووکامرس دیگر دیر نمی‌شوند.

پرچم‌های سراسری و خروجی قابل پردازش

# اجرا از پوشه‌ی دیگر
wp --path=/var/www/site plugin list

# در شبکه‌ی چندسایته: کدام سایت؟
wp --url=shop.example.ir option get blogname

# بدون بارگذاری افزونه‌ها و قالب (برای وقتی یکی خطا می‌دهد)
wp --skip-plugins --skip-themes plugin deactivate broken-plugin

# خروجی قابل پردازش
wp plugin list --format=json | jq '.[] | select(.update=="available") | .name'
wp user list --format=csv > users.csv
wp post list --format=ids

# اجرای یک تکه PHP در محیط وردپرس
wp eval 'echo get_option("home");'
wp eval-file ./scripts/fix-meta.php

مدیریت چند سرور با alias

اگر چند سایت یا محیط staging و production دارید، فایل wp-cli.yml در ریشه‌ی پروژه اجازه می‌دهد از لپ‌تاپ خودتان روی سرورها دستور اجرا کنید. WP-CLI از طریق SSH وصل می‌شود و لازم نیست روی سرور لاگین کنید:

# wp-cli.yml در ریشه‌ی پروژه
@prod:
  ssh: deploy@203.0.113.10/var/www/site
@staging:
  ssh: deploy@203.0.113.11/var/www/staging
@all:
  - @prod
  - @staging

wp @prod plugin list --update=available
wp @staging db export staging.sql
wp @all core version

اسکریپت پشتیبان خودکار

ترکیب چند دستور در یک اسکریپت bash و اجرای آن با cron، پشتیبان روزانه‌ای می‌سازد که به هیچ افزونه‌ای وابسته نیست:

#!/usr/bin/env bash
# backup.sh: پشتیبان روزانه با نگهداری ۱۴ نسخه
set -euo pipefail
SITE=/var/www/site
DEST=/backups/site
mkdir -p "$DEST"
cd "$SITE"
wp db export - --skip-themes --skip-plugins | gzip > "$DEST/db-$(date +%F).sql.gz"
tar -czf "$DEST/uploads-$(date +%F).tar.gz" wp-content/uploads
find "$DEST" -type f -mtime +14 -delete

این فایل را با chmod +x backup.sh اجرایی کنید و در crontab خطی مثل 0 3 * * * /var/www/backup.sh بگذارید تا هر شب ساعت سه اجرا شود. برای سایت‌های بزرگ پوشه‌ی uploads را هفتگی و دیتابیس را روزانه بگیرید.

عیب‌یابی وقتی پیشخوان در دسترس نیست

شش مشکل رایج و دستوری که معمولاً بدون نیاز به FTP یا phpMyAdmin کار را تمام می‌کند.

WP-CLI نسخه‌ی ۳ و وردپرس ۷: دستورهای جدید

سه بسته‌ی جدید که با نسخه‌ی ۳ رسمی می‌شوند و از امروز در نسخه‌ی شبانه قابل تست‌اند.

تیم WP-CLI همزمان با وردپرس ۷ سه بسته‌ی دستوری تازه ساخته است. بسته‌ی block-command بلاک‌ها، الگوها، استایل‌ها و قالب‌های سایت را فهرست می‌کند و قالب‌های ویرایشگر سایت را به فایل خروجی می‌دهد؛ برای تیم‌هایی که قالب بلاکی می‌سازند یعنی نسخه‌بندی قالب‌ها در گیت. بسته‌ی ability-command قابلیت‌های ثبت‌شده با Abilities API را فهرست، اعتبارسنجی و اجرا می‌کند؛ همان قابلیت‌هایی که عامل‌های هوش مصنوعی از طریق MCP می‌بینند. و بسته‌ی ai-command مستقیم با AI Client وردپرس ۷ صحبت می‌کند: وضعیت اتصال‌ها، تولید متن و تصویر از خط فرمان.

# نسخه‌ی شبانه برای تست دستورهای جدید
wp cli update --nightly

# یا نصب جداگانه‌ی بسته‌ها روی ۲.۱۲
wp package install wp-cli/block-command:dev-main
wp package install wp-cli/ability-command:dev-main

# بلاک‌ها و قالب‌های سایت
wp block type list --namespace=core --format=table
wp block pattern list --category=buttons
wp block template export twentytwentyfive//single --stdout

# Abilities API (وردپرس ۶.۹ به بالا)
wp ability list --public
wp ability run core/get-site-info --user=modir --format=json

# AI Client وردپرس ۷ (بسته‌ی wp-cli/ai-command)
wp ai status
wp connectors list
wp ai generate text 'سه عنوان کوتاه برای مقاله‌ی آموزش WP-CLI پیشنهاد بده'

این بسته‌ها به WP-CLI نسخه‌ی ۳ نیاز دارند که هنوز به صورت پایدار منتشر نشده است. برای تست از نسخه‌ی شبانه استفاده کنید و در سرور واقعی روی ۲.۱۲ بمانید. اگر مقاله‌ی اتصال وردپرس به هوش مصنوعی را خوانده‌اید، wp ai status همان بررسی is_supported_for_text_generation() است، فقط از ترمینال.

۳۰ دستور در یک نگاه

خطاهای رایج WP-CLI