WP-CLI - zarządzanie WordPress z linii poleceń

WP-CLI to narzędzie wiersza poleceń do zarządzania WordPress. Zamiast obsługiwać panel wp-admin, wybierasz komendę wykonującą określoną operację na aplikacji, plikach albo bazie. Terminal pozwala zapisać powtarzalną procedurę i sprawdzić jej wynik, ale nie zastępuje testu funkcji strony.

Program jest napisany w PHP i może być dystrybuowany jako plik PHAR. Sposób uruchomienia zależy od środowiska. Wiele komend ładuje WordPress i kod jego rozszerzeń, aby korzystać z właściwych funkcji oraz danych. Inne, na przykład pobranie rdzenia, działają przed pełną instalacją aplikacji.

Dla poleceń dotyczących istniejącej witryny pracuj w jej katalogu lub podaj --path. Konfiguracja określa między innymi połączenie z bazą, więc pomylenie katalogu może oznaczać pracę na innej stronie. W sieci Multisite znaczenie ma również kontekst --url. Nawet odczyt warto wykonywać świadomie: bootstrap może uruchamiać kod wtyczek, dlatego nazwa list nie stanowi absolutnej gwarancji braku działań wykonywanych przez rozszerzenia.

Panel jest wygodny do redagowania pojedynczego wpisu. Terminal pomaga wtedy, gdy potrzebujesz zestawienia, operacji na wielu rekordach albo powtarzalnej procedury. Nie ma uniwersalnej przewagi czasu: eksport dużej bazy i regeneracja obrazów nadal zależą od zasobów serwera oraz ilości danych.

Przydatne zastosowania to:

• inwentaryzacja wersji i dostępnych aktualizacji;
• eksport bazy przed zaplanowaną zmianą;
• migracja adresów z obsługą danych serializowanych;
• diagnostyka niedostępnego panelu;
• raportowanie stanu kilku jawnie wskazanych instalacji.

WP-CLI nie omija wszystkich błędów WordPress. Jeżeli przy uruchomieniu ładowana wtyczka powoduje awarię, komenda również może się zatrzymać. Dlatego procedura ratunkowa musi uwzględniać kontekst i możliwość pominięcia konkretnego komponentu.

Przy wielu stronach najpierw automatyzuj odczyt oraz raport, a dopiero potem zatwierdzone operacje. Dobrze opisany wynik audytu jest bardziej użyteczny niż pętla aktualizująca wszystkie znalezione katalogi bez wiedzy, do kogo należą. O szerszych zasadach utrzymania przeczytasz w poradniku aktualizacji WordPress.

Najpierw sprawdź, czy dostawca środowiska udostępnił już WP-CLI: wp --info pokaże wersję narzędzia, interpreter PHP i konfigurację. Nie nadpisuj zarządzanej instalacji bez ustalenia, kto ją utrzymuje.

Oficjalna instrukcja instalacji podaje minimum PHP 7.2.24+. To wymaganie programu, nie rekomendacja bezpieczeństwa dla produkcji. Dobierz także wspieraną wersję PHP zgodną z używanym WordPress i rozszerzeniami.

Przykład pobrania PHAR w Linux lub macOS:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info

Przed uruchomieniem pobranego programu sprawdź pochodzenie i zweryfikuj integralność według instrukcji wydania, w tym dostępny podpis. Następnie możesz nadać plikowi prawa wykonania i umieścić go w zaufanym katalogu PATH użytkownika. Instalacja globalna wymaga odpowiednich uprawnień i nie jest obowiązkowa; lokalnie można wywoływać PHAR przez interpreter PHP.

SSH jest sposobem dostępu do zdalnej powłoki, nie bezwzględnym warunkiem WP-CLI. Narzędzie działa również lokalnie. Na Windows dobierz obsługiwany sposób uruchomienia, na przykład środowisko WSL; samo otwarcie terminala nie instaluje PHP ani WordPress. Przygotowanie aplikacji testowej opisuje poradnik WordPress na localhost.

Struktura polecenia to wp <komenda> <subkomenda> [argumenty] [--flagi]. Przykład wp plugin update akismet --dry-run wybiera aktualizację wskazanej wtyczki w trybie podglądu.

wp --info
wp core version --path=/srv/www/example
wp core check-update --path=/srv/www/example
wp option get blogname --path=/srv/www/example
wp help plugin update

Nazwy ścieżek w poradniku są przykładami. Przed wykonaniem sprawdź katalog, domenę i bazę używaną przez aplikację. Przy sieci witryn dodaj właściwe --url, gdy komenda wymaga kontekstu konkretnej strony.

Używaj konta systemowego przeznaczonego do danej witryny, z uprawnieniami potrzebnymi do operacji. Flaga --allow-root wyłącza zabezpieczenie przed uruchomieniem jako root; nie jest rutynowym rozwiązaniem problemów z dostępem. Najpierw popraw właściciela plików albo wybierz odpowiednie konto.

Flaga --quiet ogranicza komunikaty informacyjne. W automatyzacji nie zastępuje sprawdzenia kodu zakończenia i zachowania błędów w prywatnym logu. Dla nowej komendy odczytaj wp help, ponieważ nie wszystkie podkomendy mają te same opcje ani obsługują dry-run.

Komendy instalacyjne uruchamiaj w przygotowanym katalogu nowego środowiska, po ustaleniu bazy oraz użytkownika. Hasła podawaj przez mechanizm interaktywny, zamiast wpisywać je w argumentach zapisywanych w historii powłoki.

wp core download --locale=pl_PL
wp config create --dbname=baza_testowa --dbuser=uzytkownik_testowy --prompt=dbpass
wp db create
wp core install --url=https://example.test --title="Strona testowa" --admin_user=opiekun --admin_email=admin@example.test --prompt=admin_password --skip-email

Przykład dotyczy nowej instalacji testowej. Parametry połączenia, adres i konto muszą odpowiadać przygotowanemu środowisku. Nie używaj tej sekwencji w katalogu działającej strony.

Aktualizacja istniejącego rdzenia to osobna operacja: wp core update zmienia pliki, a wp core update-db wykonuje wymaganą aktualizację bazy. O potrzebie migracji decyduje konkretna zmiana. Nie cofaj rdzenia do przypadkowej starej wersji przez --force jako uniwersalnej naprawy.

Polecenie wp core verify-checksums porównuje pliki objęte kontrolą z oficjalnymi sumami. Odchylenie wymaga wyjaśnienia, ale sam zgodny wynik nie jest pełnym audytem bezpieczeństwa wszystkich wtyczek, bazy i kont. Po aktualizacji sprawdź funkcje witryny, a nie tylko wersję programu.

Dokumentacja config create potwierdza interaktywne dbpass, a core install opisuje admin_password i --skip-email. Sprawdź te opcje dla używanego wydania narzędzia.

Obsługa wtyczek obejmuje odczyt, instalację, zmianę aktywności i aktualizację. Zacznij od listy, aby potwierdzić slug oraz stan komponentu.

wp plugin list
wp plugin update --all --dry-run
wp plugin update akismet --dry-run

Dokumentacja plugin update potwierdza obsługę --dry-run. Podgląd wskazuje plan aktualizacji, lecz nie wykonuje testu zgodności nowego kodu. Akceptacja listy nie zastępuje stagingu, kopii i kontroli funkcji.

Pozostałe przykłady zmieniają witrynę: wp plugin install woocommerce --activate instaluje oraz aktywuje komponent, wp plugin activate akismet go włącza, wp plugin deactivate akismet wyłącza, a wp plugin delete hello usuwa pliki wskazanej wtyczki. Każdą operację dobieraj osobno. Wyłączenie płatności czy formularza może bezpośrednio przerwać proces klienta.

Przy awarii związanej z ładowaniem wtyczki sprawdź możliwość --skip-plugins z właściwym zakresem. Mu-plugins nadal mogą zostać załadowane. Dezaktywacja podejrzanego komponentu może pomóc w diagnozie, ale nie gwarantuje przywrócenia strony ani odwrócenia zmian w danych.

Motywy mają osobny zestaw poleceń. Lista pomaga ustalić aktywny szablon oraz jego zależności:

wp theme list
wp theme list --status=inactive

Przykłady zmieniające stan to wp theme install twentytwentyfive --activate, wp theme activate astra, wp theme update --all oraz wp theme delete twentytwentythree. Nie traktuj ich jako kolejnych kroków jednej procedury. Aktywacja motywu zmienia wygląd publicznej strony, dlatego testuj ją na kopii.

Nie usuwaj automatycznie każdego nieaktywnego motywu. Motyw nadrzędny może być wymagany przez aktywny motyw potomny, mimo że sam nie jest oznaczony jako aktywny. Zachowaj potrzebne zależności i ustaloną konfigurację awaryjną, a zbędne składniki usuń dopiero po sprawdzeniu.

Powrót do poprzedniego motywu nie musi cofać ustawień zapisanych przez nowy komponent. Po przełączeniu sprawdź menu, widgety, szablony wpisów i elementy sklepu. Pliki z własnymi modyfikacjami wymagają oddzielnej kopii; aktualizacja motywu nadrzędnego może je zastąpić.

Najpierw odczytaj konta oraz role. Wyniki mogą zawierać adresy e-mail, więc nie publikuj pełnego raportu z produkcji.

wp user list
wp role list
wp cap list editor
wp user update 1 --prompt=user_pass

Ostatnia komenda zmienia hasło wskazanego użytkownika po interaktywnym podaniu wartości. Sprawdź ID przed wykonaniem. Dokumentacja user update opisuje user_pass oraz globalne --prompt dla wybranych argumentów. Unikasz wpisania sekretu w samej komendzie, ale nadal zadbaj o prywatny terminal i brak nagrywania sesji. Nie zakładaj ochrony przed każdym mechanizmem logowania.

Tworzenie konta przez wp user create wymaga wskazania właściwej roli. Polecenie wp user set-role 5 administrator nadaje szerokie uprawnienia i powinno wynikać z potwierdzonej potrzeby. Nie nadawaj roli administratora jako automatycznego sposobu naprawy problemu z dostępem.

Usunięcie konta przez wp user delete 7 --reassign=1 wymaga kontroli treści i relacji danych. Samo przepisanie wpisów nie rozstrzyga wszystkich powiązań rozszerzeń. Hasło w bazie przechowywane jest jako hasz, nie odwracalnie zaszyfrowany tekst do odzyskania. Reset ustanawia nowy sekret.

Eksport bazy wykonuj do chronionego miejsca poza publicznym katalogiem WWW. Zweryfikuj dostępne miejsce, uprawnienia i możliwość odtworzenia. Sam fakt utworzenia pliku nie jest testem kompletności kopii.

wp db export /srv/backups/example-before-change.sql
wp db prefix
wp search-replace 'http://example.test' 'https://example.com' --skip-columns=guid --dry-run

Search-replace obsługuje dane serializowane i podgląd podmiany. Zwykła zamiana znaków w zrzucie może uszkodzić długości zapisane w serializacji. Przejrzyj zakres tabel, kolumn i liczbę zmian. Pominięcie GUID w przykładzie służy zachowaniu identyfikatorów wpisów; konkretna migracja wymaga oceny własnego modelu danych.

Po akceptacji planu można wykonać zatwierdzoną podmianę bez dry-run. To nadal nie pełna migracja: domena wymaga poprawnej konfiguracji serwera, HTTPS, przekierowań i testów treści.

wp db import odtwarza dane ze zrzutu i może zastąpić nowsze informacje. wp db query wykonuje SQL, więc zapytanie musi używać faktycznego prefiksu tabel. wp db optimize nie jest uniwersalnym lekarstwem na wolną stronę i może obciążyć bazę. Każdą z tych operacji traktuj jako osobno zaplanowaną zmianę.

WP-CLI pozwala przygotować listę wpisów lub wykonać operację na wskazanych identyfikatorach. Najpierw sprawdź zakres listy:

wp post list --post_type=post --field=ID
wp media regenerate --only-missing

Druga komenda już zapisuje pliki: regeneruje brakujące rozmiary obrazów. Dobierz zakres i czas wykonania do biblioteki oraz zasobów hostingu. Terminal nie daje gwarancji braku przerwania procesu ani nie usuwa limitów pamięci i miejsca na dysku.

wp post generate --count=50 tworzy przykładowe wpisy wyłącznie na przygotowanym środowisku testowym. wp post delete 123 --force trwale usuwa wskazany wpis z pominięciem kosza. Nie łącz listy wszystkich ID z usuwaniem bez osobnego przeglądu wyniku i kopii.

Import obrazu może wyglądać tak: wp media import /srv/import/zdjecie.jpg --post_id=10 --featured_image. Sprawdź prawa do materiału, docelowy wpis i format pliku. Po regeneracji skontroluj faktyczne użycie rozmiarów przez motyw, obraz wyróżniający i galerię produktu. Poprawne zakończenie polecenia nie potwierdza jeszcze poprawnego wyglądu strony.

WP-Cron jest mechanizmem zadań aplikacji, a systemowy cron harmonogramem systemu operacyjnego. Można je połączyć, lecz nie należy mylić ich odpowiedzialności.

wp cron event list
wp cron test
wp cron event run --due-now

Pierwsze polecenie pokazuje harmonogram, ostatnie uruchamia zadania, których termin nadszedł. Hook może wysłać wiadomość, zaktualizować dane albo wykonać integrację, więc ręczne uruchomienie jest operacją z możliwymi skutkami biznesowymi. Na stagingu odłącz rzeczywiste kanały wysyłki.

Przykład systemowego harmonogramu:

*/15 * * * * /usr/local/bin/wp cron event run --due-now --path=/srv/www/example

Interwał w przykładzie nie gwarantuje punktualności. Zadanie może czekać do kolejnego wywołania, wykonywać się długo lub zakończyć błędem. Dobierz częstotliwość do potrzeb, zapewnij kontrolę nakładania uruchomień i prywatne logowanie wyników.

Jeżeli wyłączasz wyzwalanie WP-Cron przez ruch ustawieniem DISABLE_WP_CRON, najpierw potwierdź działanie zastępczego harmonogramu. Sprawdź użytkownika systemowego, ścieżkę PHP i uprawnienia. Brak odwiedzin przestaje być wtedy wyzwalaczem problemu, ale serwerowy harmonogram nadal wymaga monitorowania.

Zacznij od raportu, nie od masowego zapisu. Poniższy przykład sprawdza jawnie wskazane katalogi i pokazuje dostępne aktualizacje wtyczek. Uruchamiaj go jako użytkownik mający uprawnienia do tych instalacji.

#!/usr/bin/env bash
set -euo pipefail
sites=("/srv/www/site-a" "/srv/www/site-b")
for site in "${sites[@]}"; do
  printf 'Witryna: %s\n' "$site"
  wp core version --path="$site"
  wp plugin update --all --dry-run --path="$site"
done

Jawna lista ogranicza przypadkowe objęcie cudzych instalacji lub archiwów. Ustawienie zatrzymywania po błędzie pomaga wykryć problem, ale nie cofa już wykonanych komend. Dla zapisu potrzebujesz osobnego planu akceptacji, kopii i kontroli po każdej witrynie.

Nie dopisuj rutynowego --allow-root do wszystkich wierszy. Konta, własność plików i środowisko PHP powinny być zgodne z wdrożeniem. Sprawdź też, gdzie trafia log i czy nie zawiera danych klientów.

Eksport bazy przed aktualizacją nie zapewnia pełnego rollbacku. Kopia powinna obejmować potrzebne pliki i konfigurację, a przy działającym sklepie plan musi chronić zamówienia przyjęte już po jej wykonaniu. Automatyzacja nie znosi tej odpowiedzialności.

WP-CLI może wspierać tworzenie i diagnostykę rozszerzeń. Przydatne przykłady to:

• wp scaffold plugin moj-plugin: szkielet wtyczki;
• wp scaffold child-theme moj-motyw --parent_theme=astra: motyw potomny;
• wp eval 'echo home_url();': wykonanie podanego PHP w kontekście aplikacji;
• wp eval-file skrypt.php: uruchomienie lokalnego pliku PHP;
• wp shell: interaktywna konsola;
• wp profile stage i wp profile hook: profilowanie po dodaniu odpowiedniego pakietu.

Scaffold zapisuje pliki, a eval i eval-file wykonują kod z uprawnieniami procesu. Przejrzyj skrypt przed uruchomieniem; obecność komendy w poradniku nie potwierdza, że dowolny pobrany plik jest właściwy dla produkcji.

Czyszczenie transientów przez wp transient delete --all zmienia stan cache i może zwiększyć obciążenie odbudową danych. Nie jest uniwersalną naprawą problemów wydajnościowych. Najpierw ustal warstwę i przyczynę.

W diagnostyce zachowaj zanonimizowany błąd i konkretny kontekst. Procedura debugowania WordPress pomaga powiązać wynik polecenia z objawem strony, zamiast wykonywać przypadkowe czyszczenie i ponawiać test bez hipotezy.

Własna komenda ma sens, gdy proces wymaga logiki niedostępnej w gotowych podkomendach. Umieść ją w kontrolowanym rozszerzeniu projektu, aby nie znikała przy zmianie motywu. Minimalny przykład sprawdza obecność argumentu:

if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('moja-komenda', function ($args) {
        if (empty($args[0])) {
            WP_CLI::error('Podaj argument tekstowy.');
        }
        WP_CLI::success('Argument: ' . $args[0]);
    });
}

wp moja-komenda test wypisze komunikat. Przy komendzie zmieniającej dane dodaj walidację zakresu, kontrolę uprawnień, raport wyniku i tryb próby, jeżeli można go rzetelnie zaimplementować. Własne --dry-run musi faktycznie pomijać zapis, a nie tylko zmieniać treść komunikatu.

Pakiety rozszerzają narzędzie, na przykład o profilowanie. Instaluj zaufane wydania i zapisz wersję oraz zależności. Nie dodawaj nowego pakietu globalnie do środowiska wielu klientów bez sprawdzenia wpływu. Komenda administracyjna jest częścią kodu wymagającego utrzymania, dokumentacji i testu na reprezentatywnych danych.

W pipeline określ, jakie działania wynikają z wdrażanej zmiany. Migracja bazy, czyszczenie cache i odświeżenie reguł adresów nie muszą być potrzebne przy każdym deployu. Nie wykonuj ich automatycznie tylko dlatego, że pojawiają się w przykładowym skrypcie.

Przydatny etap odczytu stanu wygląda następująco:

wp core version --path=/srv/www/example
wp plugin list --format=json --path=/srv/www/example

Zapisz wynik w chronionym artefakcie wdrożenia i porównaj z planem. Dopiero osobny zatwierdzony etap wykonuje potrzebną migrację oraz kontrolę działania. Kod zakończenia polecenia powinien wpływać na wynik pipeline, a błąd nie może zostać ukryty przez kolejne udane polecenie.

Obraz wordpress:cli może dostarczyć narzędzie w kontenerze. Zgodność środowiska wymaga jednak dobrania wersji PHP, konfiguracji, wolumenów i użytkownika procesu. Sama nazwa obrazu nie zapewnia identyczności z kontenerem obsługującym WWW.

Aliasy w wp-cli.yml pozwalają wskazywać środowiska i korzystać z połączenia SSH. Nazwy produkcja i staging powinny być jednoznaczne. Przed mutacją potwierdź cel niezależnym odczytem, a sekretów nie zapisuj w wersjonowanym pliku konfiguracji.

WP-CLI nie ma uniwersalnego przycisku cofania. Niektóre zmiany można odwrócić konfiguracją, inne wymagają spójnej kopii, a jeszcze inne wywołują skutki poza WordPress. Import bazy nie cofnie wysłanej wiadomości ani operacji wykonanej w zewnętrznym systemie.

Przed zapisem sprawdź:

1. Właściwy katalog, domenę, użytkownika i zakres rekordów.
2. Dostępność oraz semantykę trybu próby.
3. Kopię plików, bazy i konfiguracji odpowiednią do zadania.
4. Sposób ochrony nowych danych przy ewentualnym odtwarzaniu.
5. Test funkcji oraz warunek zakończenia lub przerwania operacji.

Polecenie wp db reset usuwa tabele bazy, a wp post delete z --force usuwa wpis z pominięciem kosza. Nie wykonuj ich jako kroku diagnostycznego. Przywrócenie kopii może pomóc odtworzyć stan, lecz wymaga sprawdzonej procedury i zgodności wersji kodu z bazą.

Jeżeli potrzebujesz przygotowania takiej procedury, opisz zakres witryn i wykonywanych zadań. Dalszą opiekę można oprzeć na indywidualnie ustalonym pakiecie godzinowym. Zakres, reakcję i warunki SLA uzgadnia się osobno; obecność WP-CLI nie stanowi gwarancji czasu naprawy.