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

WP-CLI (WordPress Command Line Interface) to oficjalne narzędzie wiersza poleceń do zarządzania instalacją WordPressa bez korzystania z przeglądarki. Zamiast klikać w panelu wp-admin, wydajesz polecenia tekstowe w terminalu, a WP-CLI tłumaczy je na operacje na plikach i bazie danych.

Pod maską WP-CLI to aplikacja napisana w PHP, dystrybuowana jako pojedynczy plik wykonywalny `.phar`. Po uruchomieniu ładuje rdzeń WordPressa (te same pliki `wp-load.php` co przeglądarka), inicjuje połączenie z bazą danych zdefiniowane w `wp-config.php`, a następnie wykonuje żądaną komendę w kontekście Twojej witryny. Dzięki temu WP-CLI ma dostęp do tych samych funkcji, hooków i danych co motyw oraz wtyczki.

Kluczowa zależność: WP-CLI musi być uruchamiane z katalogu instalacji WordPressa (lub ze wskazaniem ścieżki przez flagę `--path`), bo potrzebuje pliku `wp-config.php`, by wiedzieć, do której bazy się połączyć. To nie jest zewnętrzny serwis ani API w chmurze – to lokalne narzędzie operujące bezpośrednio na Twoim serwerze.

Panel wp-admin jest świetny dla pojedynczych, okazjonalnych zmian. Problem zaczyna się przy operacjach masowych i powtarzalnych. Aktualizacja 30 wtyczek w panelu to 30 kliknięć, oczekiwanie na przeładowania strony i ryzyko timeoutu PHP. W WP-CLI to jedno polecenie `wp plugin update --all`, które kończy się w kilka sekund.

Kiedy terminal wygrywa zdecydowanie:

• Operacje na wielu witrynach – pętla bash przechodzi przez 10 instalacji i aktualizuje każdą bez logowania.
• Migracja domeny – `wp search-replace` poprawnie obsługuje dane serializowane, czego ręczna podmiana w bazie nie potrafi.
• Eksport i import bazy – `wp db export` jest szybszy i pewniejszy niż phpMyAdmin, który przy dużych bazach często się wywraca.
• Praca bez działającego panelu – gdy strona zwraca biały ekran, terminal wciąż działa i pozwala wyłączyć felerną wtyczkę.

Dla pojedynczego wpisu na bloga panel jest wygodniejszy. Ale gdy zarządzasz portfolio stron klientów, WP-CLI zamienia godziny klikania w sekundy. W naszej opiece nad stronami WordPress to właśnie WP-CLI stoi za szybkimi aktualizacjami i regularnym monitoringiem witryn klientów.

Instalacja sprowadza się do pobrania pliku `.phar`, nadania mu uprawnień i przeniesienia do katalogu w `PATH`.

Standardowa instalacja (Linux/macOS):

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

Potem zweryfikuj instalację poleceniem `wp --info` – pokaże wersję PHP, WP-CLI i ścieżkę konfiguracji.

Wymagania systemowe:

• PHP 7.4 lub nowszy (zalecane PHP 8.1+ w 2026).
• Dostęp SSH do serwera (na shared hostingu nie zawsze jest dostępny – sprawdź u dostawcy).
• Środowisko UNIX-owe (Linux, macOS, WSL na Windows).

Shared hosting: wielu dostawców (CyberFolks, LH.pl, Zenbox) udostępnia SSH i ma WP-CLI preinstalowane – wystarczy wpisać `wp --info`. Jeśli go nie ma, a masz dostęp SSH, możesz zainstalować `.phar` lokalnie w katalogu domowym i wywoływać go przez `php ~/wp-cli.phar`. Na hostingach bez SSH WP-CLI nie zadziała – to jeden z argumentów, by wybierać porządny hosting (unikaj nazwa.pl i home.pl).

macOS: najwygodniej przez Homebrew: `brew install wp-cli`.

Każde polecenie WP-CLI ma stałą strukturę: `wp [argumenty] [--flagi]`. Na przykład `wp plugin update akismet --dry-run` to komenda `plugin`, subkomenda `update`, argument `akismet` i flaga `--dry-run`.

Najważniejsze polecenia diagnostyczne i flagi:

• `wp --info` – informacje o środowisku (wersje PHP/WP-CLI).
• `wp core version` – wersja zainstalowanego WordPressa.
• `wp core check-update` – sprawdza dostępne aktualizacje rdzenia.
• `wp option get blogname` – odczytuje pojedynczą opcję z bazy.
• `--path=/sciezka/do/wp` – wskazuje katalog WordPressa, gdy nie jesteś w nim.
• `--allow-root` – pozwala uruchomić WP-CLI jako root (potrzebne na serwerach, gdzie komendy odpalasz z konta root).
• `--quiet` – wycisza komunikaty pomocnicze, przydatne w skryptach.

Warto zapamiętać tabelę najczęstszych obszarów: wp core (rdzeń), wp plugin (wtyczki), wp theme (motywy), wp user (użytkownicy), wp db (baza), wp post / wp media (treść), wp cron (zadania), wp search-replace (podmiana). Każdy obszar ma własny zestaw subkomend, a `wp help ` pokazuje pełną listę.

WP-CLI pozwala postawić WordPressa od zera w kilka poleceń – bez kreatora w przeglądarce.

wp core download --locale=pl_PL
wp config create --dbname=baza --dbuser=user --dbpass=haslo
wp db create
wp core install --url=example.pl --title="Moja strona" --admin_user=admin --admin_email=mail@example.pl

To zestaw, którego używamy przy wdrożeniach nowych witryn – cały proces instalacji zajmuje sekundy zamiast minut klikania.

Aktualizacje rdzenia:

• `wp core update` – aktualizuje WordPressa do najnowszej wersji.
• `wp core update-db` – migruje strukturę bazy po aktualizacji (krok często pomijany ręcznie).
• `wp core update --version=6.5.2 --force` – wymusza konkretną wersję (przydatne przy rollbacku).

Po każdej większej aktualizacji warto sprawdzić `wp core verify-checksums`, które porównuje pliki rdzenia z oficjalnymi sumami kontrolnymi i wykrywa ewentualne modyfikacje lub infekcje. To prosty sygnał wczesnego ostrzegania o włamaniu.

Obsługa wtyczek to najczęstsze zastosowanie WP-CLI w codziennej pracy.

• `wp plugin list` – lista wtyczek z ich statusem i dostępnymi aktualizacjami.
• `wp plugin install woocommerce --activate` – instaluje i od razu aktywuje wtyczkę.
• `wp plugin activate akismet` / `wp plugin deactivate akismet` – włącza/wyłącza.
• `wp plugin update --all` – aktualizuje wszystkie wtyczki naraz.
• `wp plugin delete hello` – usuwa wtyczkę z dysku.

Scenariusz ratunkowy: gdy strona się wykłada po aktualizacji wtyczki (biały ekran), nie masz dostępu do panelu, by ją wyłączyć. W terminalu `wp plugin deactivate problematyczna-wtyczka` przywraca stronę w sekundę. To jedna z sytuacji, w których WP-CLI ratuje produkcję.

Operacje masowe: `wp plugin update --all --dry-run` najpierw pokaże, co się zmieni, bez wprowadzania zmian. Dopiero po weryfikacji uruchamiasz bez `--dry-run`. Przy wielu witrynach taki audyt przed aktualizacją chroni przed niespodziankami. Świadomy dobór i bezpieczna aktualizacja wtyczek to fundament – więcej w naszej bazie o najlepszych wtyczkach WordPress.

Motywy obsługuje się analogicznie do wtyczek, przez komendę `wp theme`.

• `wp theme list` – lista zainstalowanych motywów ze statusem aktywności.
• `wp theme install twentytwentyfive --activate` – instaluje i aktywuje motyw z repozytorium WordPress.org.
• `wp theme activate astra` – przełącza aktywny motyw.
• `wp theme update --all` – aktualizuje wszystkie motywy.
• `wp theme delete twentytwentythree` – usuwa nieużywany motyw.

Dobra praktyka: na produkcji trzymaj tylko jeden aktywny motyw i ewentualnie jeden domyślny jako fallback. Każdy nieużywany motyw to potencjalna luka bezpieczeństwa, jeśli nie jest aktualizowany. WP-CLI pozwala szybko zrobić porządek: `wp theme list --status=inactive` pokaże kandydatów do usunięcia.

Przy testach nowego wyglądu możesz w skrypcie aktywować motyw, sprawdzić stronę i wrócić do poprzedniego jednym poleceniem – bez ryzyka, że klient zobaczy niedokończony layout w panelu.

To obszar, gdzie WP-CLI bywa wręcz niezastąpiony – zwłaszcza gdy stracisz dostęp do panelu.

• `wp user list` – lista użytkowników z rolami i adresami e-mail.
• `wp user create jan jan@example.pl --role=editor` – tworzy nowego użytkownika.
• `wp user update 1 --user_pass=NoweHaslo123` – reset hasła administratora bez dostępu do panelu (klasyczny ratunek po zgubieniu hasła).
• `wp user set-role 5 administrator` – zmienia rolę istniejącego użytkownika.
• `wp user delete 7 --reassign=1` – usuwa użytkownika i przypisuje jego treści innemu.

Role i uprawnienia (capabilities):

• `wp role list` – lista ról w systemie.
• `wp cap add editor manage_options` – nadaje konkretne uprawnienie roli.
• `wp cap remove author publish_posts` – odbiera uprawnienie.

Typowy scenariusz: klient dzwoni, że nie może się zalogować, a jedyny administrator jest niedostępny. Jedno polecenie `wp user update admin --user_pass=...` przywraca dostęp w kilka sekund, bez grzebania w bazie i ryzyka uszkodzenia tabel.

Baza danych to serce WordPressa, a WP-CLI daje nad nią pełną kontrolę.

• `wp db export backup.sql` – tworzy zrzut całej bazy (kopia przed każdą ryzykowną operacją).
• `wp db import backup.sql` – przywraca bazę ze zrzutu.
• `wp db optimize` – optymalizuje i defragmentuje tabele.
• `wp db query "SELECT COUNT(*) FROM wp_posts"` – uruchamia dowolne zapytanie SQL.

Migracja domeny – najważniejsze polecenie WP-CLI:

wp search-replace 'http://stara.pl' 'https://nowa.pl' --dry-run

Najpierw zawsze z `--dry-run`, by zobaczyć, ile rekordów zostanie zmienionych. Po weryfikacji uruchamiasz bez flagi.

Dlaczego nie da się tego zrobić zwykłym `sed` na pliku SQL? Bo WordPress przechowuje wiele danych (ustawienia motywu, widgety, konfiguracje wtyczek) w formacie serializowanym, gdzie zapisana jest długość każdego ciągu znaków. Ręczna podmiana psuje tę długość i serializowane dane przestają się odczytywać, co prowadzi do błędów. `wp search-replace` rozumie serializację i poprawnie aktualizuje długości – to różnica między działającą a zepsutą migracją.

WP-CLI sprawdza się też przy masowych operacjach na treści i plikach.

• `wp post list --post_type=post --field=ID` – lista ID wszystkich wpisów (bazowa do skryptów).
• `wp post generate --count=50` – generuje przykładowe wpisy (przydatne do testów wydajności i motywu).
• `wp post delete 123 --force` – trwale usuwa wpis.

Multimedia:

• `wp media import /sciezka/zdjecie.jpg --post_id=10 --featured_image` – importuje plik do biblioteki mediów i ustawia jako obrazek wyróżniający.
• `wp media regenerate` – regeneruje miniatury dla wszystkich obrazów. To kluczowe po zmianie motywu lub dodaniu nowych rozmiarów miniatur – bez tego stare zdjęcia wyświetlają się w złych wymiarach.
• `wp media regenerate --only-missing` – regeneruje tylko brakujące rozmiary, znacznie szybciej.

Regeneracja miniatur w panelu wymaga wtyczki i potrafi trwać godzinami z timeoutami przy dużych bibliotekach. W terminalu działa stabilnie, pokazuje pasek postępu i nie przerywa się przy setkach plików.

WordPress ma własny system zadań cyklicznych (WP-Cron), który WP-CLI pozwala kontrolować natywnie – nie myl go z systemowym crontab.

• `wp cron event list` – lista wszystkich zaplanowanych zadań z czasem wykonania.
• `wp cron event run --due-now` – uruchamia zadania, których termin minął.
• `wp cron event run nazwa_zadania` – wymusza konkretne zadanie.
• `wp cron test` – sprawdza, czy WP-Cron w ogóle działa.

Dlaczego to ważne: domyślny WP-Cron uruchamia się dopiero przy odwiedzinach strony. Na witrynach z małym ruchem zaplanowane publikacje czy backupy mogą się opóźniać. Profesjonalne rozwiązanie to wyłączenie WP-Cron (`define('DISABLE_WP_CRON', true);` w `wp-config.php`) i wywoływanie go regularnie przez systemowy crontab:

*/15 * * * * cd /sciezka/do/wp && wp cron event run --due-now --quiet

Dzięki temu zadania wykonują się punktualnie co 15 minut, niezależnie od ruchu. To jeden z elementów stabilnego utrzymania witryny, którym zajmujemy się w ramach opieki.

Prawdziwa moc WP-CLI ujawnia się w skryptach bash, które łączą wiele komend w powtarzalny proces.

Skrypt konserwacyjny dla jednej witryny:

#!/bin/bash
cd /home/klient/htdocs/strona.pl
wp db export backups/db-$(date +%F).sql --allow-root
wp plugin update --all --allow-root
wp theme update --all --allow-root
wp core update --allow-root
wp cache flush --allow-root

Masowa aktualizacja wielu witryn (pętla):

for site in /home/*/htdocs/*; do
  echo "Aktualizuję: $site"
  wp plugin update --all --path="$site" --allow-root --quiet
done

Taka pętla aktualizuje całe portfolio stron w jednym przebiegu. To dokładnie ten mechanizm, który pozwala nam utrzymywać dziesiątki witryn klientów bez logowania do każdego panelu z osobna.

Kluczowa zasada bezpieczeństwa: każdy skrypt automatyzujący powinien najpierw robić backup bazy (`wp db export`), zanim cokolwiek zaktualizuje. Wtedy nawet feralna aktualizacja da się cofnąć przez `wp db import`.

Dla programistów WP-CLI to pełnoprawne środowisko developerskie.

• `wp scaffold plugin moj-plugin` – generuje szkielet nowej wtyczki z plikami startowymi.
• `wp scaffold child-theme moj-motyw --parent_theme=astra` – tworzy motyw potomny.
• `wp eval 'echo home_url();'` – wykonuje dowolny kod PHP w kontekście WordPressa.
• `wp eval-file skrypt.php` – uruchamia plik PHP z dostępem do funkcji WP.
• `wp shell` – interaktywna konsola PHP/WP (REPL), idealna do debugowania.
• `wp transient delete --all` – czyści wszystkie transienty (częsty fix problemów z cache).
• `wp profile stage` / `wp profile hook` – profilowanie wydajności ładowania (wymaga pakietu profile).

`wp shell` jest szczególnie niedoceniany: pozwala interaktywnie testować zapytania `WP_Query`, sprawdzać wartości opcji czy wywoływać funkcje wtyczek bez pisania kodu testowego. Dla dewelopera to szybsza pętla iteracji niż jakikolwiek panel czy `var_dump` wstawiany do plików.

WP-CLI jest rozszerzalne – możesz dopisać własne komendy dopasowane do swoich procesów.

Najprostsza rejestracja w pliku wtyczki lub `functions.php`:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'moja-komenda', function( $args ) {
        WP_CLI::success( 'Działa: ' . $args[0] );
    });
}

Po tym `wp moja-komenda test` wypisze komunikat. W praktyce buduje się tak komendy do migracji danych, czyszczenia bazy według własnych reguł czy generowania raportów.

Pakiety (packages): społeczność udostępnia gotowe rozszerzenia instalowane przez `wp package install`. Popularne to `wp-cli/profile-command` (profilowanie), `wp-cli/doctor-command` (diagnostyka zdrowia witryny) czy `wp-cli/dist-archive-command` (pakowanie wtyczek do dystrybucji).

Możliwość pisania własnych komend to mocny sygnał dojrzałości narzędzia – agencja, która tworzy własne komendy WP-CLI, automatyzuje procesy, których konkurencja wciąż klika ręcznie. To realna przewaga przy obsłudze wielu klientów.

W profesjonalnym workflow WP-CLI łączy się z narzędziami DevOps.

CI/CD (np. GitHub Actions): w pipeline po wdrożeniu kodu automatycznie wywołujesz WP-CLI, by zaktualizować bazę i wyczyścić cache:

- name: Deploy WordPress
  run: |
    wp core update-db --path=/var/www/html
    wp cache flush --path=/var/www/html
    wp rewrite flush --path=/var/www/html

Dzięki temu każde wdrożenie jest powtarzalne i bez ręcznych kroków – nikt nie zapomni zmigrować bazy po update.

Docker: oficjalny obraz `wordpress:cli` pozwala uruchamiać komendy w izolowanym kontenerze. W `docker-compose.yml` definiujesz serwis CLI obok WordPressa i bazy, co daje identyczne środowisko deweloperskie u każdego w zespole.

Wiele instalacji – plik `wp-cli.yml`: w katalogu projektu możesz zdefiniować aliasy (`@produkcja`, `@staging`) wskazujące różne serwery przez SSH. Wtedy `wp @produkcja plugin list` wykonuje komendę zdalnie. To pozwala zarządzać całą flotą witryn z jednego terminala – kluczowe przy obsłudze agencyjnej.

WP-CLI to potężne narzędzie, a z mocą idzie ryzyko. Najgroźniejsze komendy działają natychmiast i nieodwracalnie.

Żelazne zasady bezpieczeństwa:

• Zawsze backup przed operacją – `wp db export` zajmuje sekundy i ratuje przy każdej pomyłce.
• Używaj `--dry-run` wszędzie, gdzie jest dostępne (`search-replace`, `plugin update`) – najpierw zobacz, co się stanie.
• Sprawdzaj `--path` przy wielu witrynach – uruchomienie komendy na złej instalacji to klasyczny wypadek.
• `wp db reset` i `wp post delete --force` są nieodwracalne – nie ma kosza, dane znikają z dysku.

Czy da się cofnąć operacje WP-CLI? Pojedynczej komendy nie ma jak "undo". Jedyny sposób to przywrócenie kopii (`wp db import backup.sql` dla bazy, kopia plików dla treści). Dlatego backup nie jest opcją, tylko obowiązkiem.

Kto nie powinien używać WP-CLI? Osoby bez podstaw obsługi terminala i bez nawyku robienia backupów – ryzyko nieodwracalnej szkody jest realne. Jeśli nie czujesz się pewnie, lepiej zlecić utrzymanie specjaliście. Zajmiemy się tym za Ciebie – w ramach opieki nad WordPress od 299 zł/mc robimy aktualizacje, backupy i monitoring bezpieczeństwa przez WP-CLI, byś Ty nie musiał dotykać terminala.