WordPress WP-CLI Komutları: Güvenli Yönetim Rehberi

WordPress WP-CLI komutları, yönetim panelinde tek tek yapılacak bakım işlerini terminal üzerinden tekrarlanabilir ve denetlenebilir hale getirir. Eklenti güncellemek, veri tabanı yedeği almak, URL değiştirmek veya geçici önbelleği temizlemek birkaç komutla yapılabilir. Aynı güç, yanlış dizinde ya da yanlış sitede çalıştırılan bir komutun etkisini de büyütür.

Bu rehber bir “ezberlenecek komutlar listesi” değildir. Önce hedef WordPress kurulumunu doğrulamayı, sonra yedek ve kuru çalıştırma adımlarını, en son değişiklik yapan komutları ele alır. Örnek alan adları ve yollar temsilidir; gerçek sunucu kimlik bilgisi veya doğrulanmamış başarı iddiası içermez.

WP-CLI nedir ve hangi işlerde kullanılmalı?

WP-CLI, WordPress yönetim ve geliştirme görevlerini komut satırından çalıştıran resmi bir araçtır. Tarayıcı oturumuna ihtiyaç duymadan core, eklenti, tema, kullanıcı, içerik, seçenek, cron, cache ve veri tabanı işlemlerini yönetebilir. Özellikle aynı kontrolün staging ve production ortamlarında tekrarlanması, bakım komutlarının deployment akışına eklenmesi ve panelin açılmadığı hata anları için değerlidir.

Komutun çalıştığı bağlam neden önemlidir?

wp komutu bulunduğunuz dizindeki WordPress kurulumunu yüklemeye çalışır. Aynı sunucuda birden fazla site varsa yanlış dizinde çalıştırılan plugin update --all başka bir siteyi değiştirebilir. Multisite yapısında --url, farklı PHP binary’sinde WP_CLI_PHP, uzak sunucuda ise --ssh veya alias seçimi sonucu doğrudan etkiler.

WP-CLI kurulumu ve ilk doğrulamalar

Paylaşımlı hosting sağlayıcınız WP-CLI’yi hazır sunuyorsa önce mevcut kurulumu kullanın. Kendi Linux ortamınızda resmi öneri, Phar dosyasını indirip çalıştırılabilir hale getirmek ve PATH üzerindeki bir konuma taşımaktır. İndirme kaynağını ve güncel kurulum ayrıntılarını resmi WP-CLI kurulum rehberinden doğrulayın; rastgele bir üçüncü taraf binary kullanmayın.

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info

Üretim sunucusunda wp --info çıktısındaki PHP binary, PHP sürümü, WP-CLI sürümü ve config yolunu kontrol edin. Ardından WordPress kök dizininde aşağıdaki salt okunur komutlarla hedefi doğrulayın.

pwd
wp core is-installed
wp core version
wp option get home
wp option get siteurl
wp cli version

home ve siteurl beklediğiniz alan adını göstermiyorsa değişiklik yapan komutlara geçmeyin. Error: This does not seem to be a WordPress installation mesajı genellikle yanlış dizini gösterir; --path=/var/www/example/public gibi gerçek kurulum yolunu açıkça belirtin.

Değişiklikten önce güvenlik ve yedek kontrolü

WP-CLI komutları WordPress yetki ekranını atlamaz; fakat terminal kullanıcısının dosya ve veri tabanı izinleriyle güçlü değişiklikler yapabilir. Production üzerinde önce bakım penceresini, geri dönüş yöntemini ve yedeğin nerede tutulacağını belirleyin. Veri tabanı yedeğini web kök dizininin dışında saklayın; indirilebilir bir .sql dosyası kişisel veri ve parola hash’leri içerebilir.

mkdir -p /home/deploy/backups
wp db export /home/deploy/backups/site-before-maintenance.sql
wp db check

Dosya ve veri tabanını birlikte geri yükleme sürecini önceden görmek için cPanel yedekleme ve geri yükleme rehberini kullanabilirsiniz. Yedeğin oluşması tek başına yeterli kanıt değildir; dosya boyutunu, erişim izinlerini ve mümkünse staging ortamında geri dönüşü doğrulayın.

Root kullanıcısıyla çalıştırma uyarısı

WP-CLI’yi web dosyalarının sahibi olan sınırlı sistem kullanıcısıyla çalıştırmak daha güvenlidir. --allow-root uyarıyı susturur ama yanlış dosya sahipliği ve geniş yetki riskini çözmez. Container gibi root kullanımının tasarım gereği olduğu ortamlarda bile hedef volume, secret aktarımı ve komutun etkisi ayrıca sınırlandırılmalıdır.

Core, eklenti ve tema durumunu yönetme

Önce mevcut durumu listeleyin, sonra güncellenecek bileşeni seçin. --all hızlıdır; ancak kritik bir e-ticaret veya üyelik sitesinde tüm eklentileri tek işlemde değiştirmek kök nedeni ayırmayı zorlaştırabilir. Staging testi, changelog incelemesi ve geri dönüş planı olmadan toplu güncelleme yapmayın.

wp core check-update
wp plugin list --update=available
wp theme list --update=available

wp plugin update akismet
wp theme update twentytwentysix
wp core update
wp core update-db

Core dosyalarının resmi checksum ile eşleşmesini wp core verify-checksums komutuyla kontrol edebilirsiniz. WordPress.org deposundaki eklentiler için wp plugin verify-checksums --all yardımcı bir bütünlük sinyalidir; premium veya özel eklentilerde checksum bulunmaması tek başına zararlı dosya kanıtı değildir.

wp core verify-checksums
wp plugin verify-checksums --all

Güncellemeleri otomatik yayın akışına bağlıyorsanız bakım komutlarını test ve geri dönüş adımlarıyla birlikte tasarlayın. Genel CI/CD yapısı için GitHub Actions ile otomatik deploy rehberini inceleyebilirsiniz.

Veri tabanı export, import ve search-replace işlemleri

wp db export ve wp db import, wp-config.php içindeki veri tabanı bilgilerini kullanır. Import mevcut tabloları etkileyebileceği için hedef veritabanını ve yedek dosyasını iki kez doğrulayın. Shell geçmişine parola yazmayın; parolayı komut satırı argümanı olarak taşımak süreç listelerinde veya loglarda görünebilir.

wp db export /home/deploy/backups/site.sql
wp db import /home/deploy/backups/site.sql
wp db optimize

Alan adı değişikliğinde önce dry-run

wp search-replace, PHP serialized verisini doğru biçimde ele alır ve varsayılan olarak primary key değerlerini değiştirmez. Alan adı taşımasında önce --dry-run ile etkilenecek satırları görün. Sonuç beklenen kapsama sahipse gerçek komutu çalıştırın. guid sütununu değiştirmek çoğu taşıma senaryosunda istenmez.

wp search-replace 'https://old.example' 'https://new.example' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --dry-run

wp search-replace 'https://old.example' 'https://new.example' \
  --all-tables-with-prefix \
  --skip-columns=guid

Resmi seçenek ve sınırlar için WP-CLI search-replace komut belgesini kullanın. Multisite, farklı tablo prefix’i veya harici uygulama tabloları olan kurulumlarda kapsamı varsaymayın; hangi tabloların değişeceğini dry-run çıktısıyla doğrulayın.

Option, kullanıcı ve içerik komutlarını kontrollü kullanma

Site seçeneklerini terminalden okumak teşhis için yararlıdır. Yazma işlemlerinde option adını ve veri türünü doğrulayın; serialize edilmiş veya JSON içeren değerleri körlemesine değiştirmeyin. Kullanıcı oluştururken parolayı komuta düz metinle eklemek shell geçmişinde kalabilir. Daha güvenli bir yöntem, parolayı etkileşimli veya kontrollü bir secret mekanizmasıyla sağlamaktır.

wp option get blogname
wp option get permalink_structure
wp option update blogdescription 'Teknik rehberler'

wp user list --fields=ID,user_login,user_email,roles
wp post list --post_type=post --post_status=draft --format=table
wp comment list --status=hold --format=count

Toplu içerik silme, kullanıcı rolü değiştirme veya yorum temizleme komutlarından önce ID listesini salt okunur sorguyla dışarı alın. Komut çıktısını --format=json veya --format=csv ile otomasyona aktarırken dosyanın kişisel veri içerebileceğini hesaba katın.

Cache, transient, rewrite ve cron kontrolleri

Her performans sorununda bütün cache’i silmek kalıcı çözüm değildir. Önce hangi cache katmanının kullanıldığını belirleyin. wp cache flush WordPress object cache’i hedefler; CDN, LiteSpeed sayfa cache’i veya sunucu proxy cache’i ayrı olabilir. Paylaşılan Redis veritabanında flush komutunun başka siteleri etkileyip etkilemediğini sağlayıcı yapılandırmasına göre doğrulayın.

wp cache flush
wp transient delete --expired
wp rewrite flush
wp cron event list
wp cron event run --due-now

wp rewrite flush --hard web sunucusu rewrite kurallarını da değiştirmeye çalışabilir; her sunucuda desteklenmez ve gereksiz yere çalıştırılmamalıdır. Kategori ve etiket arşivlerinin URL yapısını değiştiriyorsanız teknik etkileri WordPress kategori ve etiket SEO rehberiyle birlikte değerlendirin.

SSH, alias ve birden fazla ortam yönetimi

WP-CLI’nin --ssh global parametresi, komutu SSH veya desteklenen container bağlantısı üzerinden uzak WordPress kurulumunda çalıştırabilir. Tekrarlanan host, path ve user değerleri wp-cli.yml ya da kullanıcı config dosyasında alias olarak tanımlanabilir. Production ve staging için açıkça farklı adlar kullanmak yanlış hedef riskini azaltır.

@staging:
  ssh: deploy@staging.example
  path: /var/www/staging/public

@production:
  ssh: deploy@production.example
  path: /var/www/production/public

wp @staging core version
wp @production plugin list --update=available
wp @production db export /home/deploy/backups/pre-update.sql

Alias yalnızca kullanım kolaylığı sağlar; kimlik doğrulama ve en az yetki ilkesinin yerini almaz. SSH anahtarını parola ile koruyun, production kullanıcısının yalnızca gerekli dizin ve komutlara erişmesini sağlayın. Ayrıntılı sözdizimi için resmi uzak komut çalıştırma rehberini kullanın.

Yaygın WP-CLI hataları ve teşhis adımları

Error establishing a database connection

Önce aynı wp-config.php dosyasının yüklendiğini, veri tabanı host’unun terminal ortamından erişilebilir olduğunu ve PHP’nin gerekli MySQL uzantısına sahip olduğunu kontrol edin. wp config path, wp db check ve gerekirse wp --debug teşhisi daraltır. Debug çıktısı yollar veya ortam ayrıntıları içerebileceğinden herkese açık alanda paylaşılmamalıdır.

Plugin veya tema fatal error oluşturuyor

Komut WordPress bootstrap aşamasında hata veriyorsa --skip-plugins, belirli eklenti listesi veya --skip-themes ile sorunun kaynağını ayırabilirsiniz. Mu-plugin’ler --skip-plugins ile otomatik atlanmaz. Hatalı bileşeni körlemesine silmek yerine önce dosya ve veri tabanı yedeği alın, sonra devre dışı bırakma ya da sürüm geri dönüşünü planlayın.

wp plugin list --skip-plugins --skip-themes
wp plugin deactivate problem-plugin --skip-plugins --skip-themes
wp --debug core version

Görsel yeniden üretme gibi komutlar çalıştıracaksanız önce orijinal medya dosyalarını yedekleyin. Boyut ve kırpma sorunlarının kök nedenleri için WordPress görsellerinin bulanık çıkması rehberini inceleyin; wp media regenerate tek başına yanlış tema boyutunu düzeltmez.

WP-CLI bakım kontrol listesi

• pwd, wp option get home ve siteurl ile hedef site doğrulandı mı?
• Komut staging üzerinde denendi mi?
• Dosya ve veri tabanı yedeği web kökü dışında alındı mı?
• Search-replace için --dry-run sonucu incelendi mi?
• Root yerine sınırlı sistem kullanıcısı kullanılıyor mu?
• Shell geçmişine parola, token veya özel anahtar yazılmadı mı?
• Toplu güncelleme yerine değişiklik kapsamı belirlendi mi?
• Komut sonrasında site, cron, log ve kritik kullanıcı akışları kontrol edildi mi?
• Geri dönüş komutu ve yedek yolu ekip tarafından biliniyor mu?

Mevcut tüm komutlar ve global parametreler için resmi WP-CLI komut dizinini referans alın. Komut belgesi her sürümde yeniden üretildiği için internetteki eski örnek yerine kurulu sürümünüzde wp help komut çıktısını da kontrol edin.

Sonuç

WP-CLI, WordPress bakımını hızlandırırken asıl değerini güvenli bir çalışma sırası kurduğunda gösterir: doğru hedefi doğrula, yedek al, önce salt okunur veya dry-run komutunu çalıştır, kapsamı sınırla, sonucu ölç ve geri dönüş yolunu hazır tut. Bu düzen, tek seferlik terminal kullanımını tekrarlanabilir bir operasyon sürecine dönüştürür.

Sık Sorulan Sorular

WP-CLI paylaşımlı hosting üzerinde çalışır mı?

Hosting sağlayıcısı SSH erişimi ve WP-CLI binary’si sunuyorsa çalışabilir. Kullanılabilir PHP binary’si, dosya izinleri ve izin verilen komutlar pakete göre değişir. Önce wp --info ve salt okunur komutlarla ortamı doğrulayın.

WP-CLI komutları geri alınabilir mi?

Her komut otomatik geri alma sağlamaz. Veri tabanı import, search-replace, kullanıcı silme ve toplu güncelleme gibi işlemler için geri dönüş yolu önceden alınan dosya/veri tabanı yedeği veya sürüm kontrollü deploy olmalıdır.

WP-CLI ile tüm eklentiler tek komutta güncellenmeli mi?

wp plugin update --all mümkündür; ancak üretimde uyumluluk testi ve kök neden takibini zorlaştırabilir. Önce bekleyen güncellemeleri listeleyin, staging üzerinde test edin ve kritik eklentileri kontrollü gruplar halinde güncelleyin.

WP-CLI search-replace serialized veriyi bozar mı?

Resmi wp search-replace komutu PHP serialized veriyi akıllı biçimde işler. Yine de yanlış eski/yeni değer veya fazla geniş tablo kapsamı veri kaybına yol açabilir. Yedek alın ve önce --dry-run çalıştırın.

WP-CLI komutları cron ile otomatik çalıştırılabilir mi?

Evet, fakat cron ortamındaki PATH, PHP binary’si, çalışma dizini ve sistem kullanıcısı interaktif SSH oturumundan farklı olabilir. Mutlak yollar kullanın, çıktıyı güvenli bir loga yönlendirin ve değişiklik yapan komutlara kilit ile hata bildirimi ekleyin.