Jak używać WP-CLI

WP-CLI to narzędzie wiersza poleceń pozwalające zarządzać instalacjami WordPress szybciej niż przez panel. Przyspiesza prace zespołów, automatyzuje rutynę i daje pełną kontrolę w terminalu. W tym poradniku krok po kroku nauczysz się instalować, konfigurować i skutecznie używać WP-CLI w różnych scenariuszach: od pierwszego uruchomienia, przez administrację treścią i użytkownikami, po aktualizacje, optymalizację i tworzenie własnych skryptów, które oszczędzają czas i minimalizują błędy.

Instalacja i przygotowanie środowiska

Wymagania wstępne

WP-CLI działa w środowiskach wspierających PHP oraz mających dostęp do powłoki systemowej. Aby zacząć, upewnij się, że:

• Masz zainstalowane PHP (rekomendowane co najmniej 7.4, a najlepiej 8.x) i rozszerzenia takie jak curl, mbstring, zip.
• System ma dostęp do narzędzia less lub pagera (dla czytelnej pomocy), oraz do narzędzi sieciowych jak wget lub curl.
• Twoje konto ma uprawnienia do zapisu w katalogu instalacji WordPress oraz do uruchamiania procesów.
• Jeśli pracujesz zdalnie, masz SSH do serwera i konto użytkownika zgodne z polityką projektu.

Instalacja na macOS i Linux

Najprościej pobrać phar i dodać go do ścieżki:

• curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
• php wp-cli.phar –info (sprawdzenie działania)
• chmod +x wp-cli.phar
• sudo mv wp-cli.phar /usr/local/bin/wp
• wp –version (powinien zwrócić wersję narzędzia)

Jeśli używasz menedżera pakietów (np. Homebrew), możesz zainstalować wp-cli za jego pomocą, jednak wersja phar jest najbardziej uniwersalna i łatwa do aktualizacji.

Instalacja na Windows (WSL lub lokalnie)

Najwygodniej skorzystać z WSL (Ubuntu/Debian). Postępuj jak na Linuxie, a plik umieść w /usr/local/bin/wp. W środowisku lokalnym bez WSL możesz uruchamiać komendy przez php wp-cli.phar w katalogu, w którym znajduje się plik, lub dodać skrypt wsadowy wp.bat wskazujący na interpreter PHP i phar.

Autouzupełnianie i aliasy

Autouzupełnianie argumentów przyspiesza pracę. Zainstaluj skrypt autocompletion dostępny w repozytorium WP-CLI i załaduj go w ~/.bashrc lub ~/.zshrc. Dodatkowo skonfiguruj aliasy, np. alias wpp=”wp –path=/var/www/projekt” lub alias wps=”wp –ssh=user@host:/ścieżka”, aby oszczędzać czas przy przełączaniu się między projektami.

Struktura poleceń i kontekst pracy

Każda komenda ma postać: wp grupa:podgrupa:akcja [argumenty] [–opcja=wartość]. WP-CLI wykrywa instalację WordPress na podstawie bieżącego katalogu. Jeśli pracujesz poza katalogiem projektu, użyj –path=/ścieżka/do/wordpress. Dla multisite dodawaj –url=example.com, aby wskazać konkretną stronę w sieci. Przykłady w dalszych sekcjach pokażą praktyczne zastosowania tej konwencji.

Pierwsze kroki i najważniejsze komendy

Sprawdzanie środowiska i pomoc

Podstawowe rozpoznanie:

• wp –info — wersja PHP, WP-CLI, system, ścieżki.
• wp cli info — podobne informacje o samym narzędziu.
• wp help lub wp help grupa:komenda — pełna pomoc i przykłady.

Używaj pagera: wp help post | less. Dzięki temu szybciej dotrzesz do właściwej sekcji dokumentacji w terminalu.

Instalacja i aktualizacja rdzenia

Tworzenie świeżej instalacji:

• wp core download — pobiera pliki WordPress.
• wp config create –dbname=DB –dbuser=USER –dbpass=PASS –dbhost=localhost — generuje wp-config.php.
• wp db create — tworzy bazę, jeśli użytkownik ma uprawnienia.
• wp core install –url=https://example.com –title=Tytuł –admin_user=admin –admin_password=hasło –admin_email=email@example.com

Aktualizacja rdzenia i plików językowych:

• wp core update
• wp core update-db
• wp language core install pl_PL && wp language core activate pl_PL

Praca z konfiguracją i trybem serwisowym

Najczęściej używane operacje:

• wp config set WP_DEBUG true –raw
• wp config set WP_MEMORY_LIMIT 256M
• wp config delete WP_ALLOW_REPAIR
• wp maintenance-mode activate / deactivate / status

Tryb serwisowy chroni odwiedzających przed błędami podczas aktualizacji i migracji. Z kolei wp config pozwala szybko edytować stałe bez ręcznej ingerencji w pliki.

Nawigacja po komendach i ich łączenie

Łącz funkcje i filtruj wyniki. Przykład masowego pobierania listy postów i ich eksportu do CSV: wp post list –post_type=post –fields=ID,post_title,post_date –format=csv > posts.csv. Z kolei wyszukiwanie i sortowanie: wp plugin list –status=active –field=name | sort pozwala sprawnie przeglądać środowisko. Dzięki temu jedna linia często zastępuje wiele kliknięć w panelu i długie przeładowania.

Zasady tworzenia skutecznych skryptów

Aby twoje komendy były powtarzalne i bezpieczne, dodawaj sprawdzanie statusu wyjścia (set -e w Bash), waliduj wejście (np. czy katalog istnieje), a także loguj wyniki do plików. Komendy destrukcyjne (np. usuwanie) poprzedzaj opcją –dry-run, jeśli jest dostępna, lub wykonuj je najpierw na kopii środowiska.

Zarządzanie treścią, mediami i użytkownikami

Posty, strony, taksonomie

Najważniejsze operacje na wpisach i stronach:

• wp post create –post_type=post –post_title=”Nowy artykuł” –post_status=draft
• wp post update 123 –post_status=publish
• wp post delete 123 –force
• wp post list –post_type=page –format=table

Taksonomie i terminy:

• wp term create category „Poradniki” –description=”Artykuły instruktażowe”
• wp term list category –fields=term_id,name,count –format=table
• wp term meta update 7 klucz wartość

Masowe przypisywanie kategorii do postów: wp post list –post_type=post –field=ID | xargs -I % wp term set post_tag „tutorial” %. To podejście wyeliminuje konieczność ręcznego klikania w panelu przy większych migracjach treści.

Media i generowanie miniaturek

Operacje na plikach:

• wp media import ./obrazy/*.jpg –post_id=55 –featured_image
• wp media regenerate — przebudowuje miniatury po zmianie motywu lub rozmiarów.
• wp media fix-orientation — koryguje EXIF (gdy pakiet jest dostępny).

Warto łączyć import i przypisanie treści: wp media import katalog/*.png –post_id=$(wp post create –post_type=post –post_title=”Grafika” –porcelain). Dzięki opcji –porcelain uzyskasz surowy wynik (ID), idealny do komponowania skryptów.

Komentarze i moderacja

Masowa moderacja:

• wp comment list –status=hold –fields=comment_ID,comment_author,comment_date
• wp comment approve $(wp comment list –status=hold –field=comment_ID)
• wp comment delete $(wp comment list –status=spam –field=comment_ID) –force

Stosuj selekcję po autorze lub dacie, a przy dużych wolumenach użyj pętli i limitów (np. –number=100) dla kontroli obciążenia serwera.

Użytkownicy, role, uprawnienia

Tworzenie i zarządzanie:

• wp user create user@example.com user –role=editor –user_pass=hasło
• wp user update user –display_name=”Jan Redaktor”
• wp user delete 33 –reassign=1
• wp user list –role=author –fields=ID,user_login,user_email

Zmiany ról i możliwości:

• wp role list
• wp cap add editor manage_options (przykład rozszerzenia możliwości roli)
• wp cap remove author publish_pages

Dla klastrów redaktorów twórz automatyzacje: import CSV z użytkownikami i pętle tworzące konta z odpowiednimi profilami. Taki proces zapewnia spójność i skraca onboardowanie zespołu.

Wtyczki, motywy i optymalizacja

Instalowanie i zarządzanie rozszerzeniami

Instalacja i aktualizacja wtyczki:

• wp plugin install classic-editor –activate
• wp plugin update –all
• wp plugin deactivate contact-form-7 && wp plugin delete contact-form-7
• wp plugin status — przegląd aktywnych, nieaktywnych i must-use.

W środowiskach z ograną listą rozszerzeń utrzymuj plik manifestu i skrypt uruchamiający pętlę instalacji oraz aktywacji. Ułatwi to stawianie nowych instancji i przywracanie środowisk.

Motywy i dostosowanie wyglądu

Zarządzanie motywymi:

• wp theme install generatepress –activate
• wp theme update –all
• wp theme delete twentyseventeen
• wp theme mod set background_color ffffff (modyfikator Customizera)

Jeśli rozwijasz motyw potomny, używaj wp scaffold child-theme nazwa –parent_theme=parent, aby szybko wygenerować strukturę. Pamiętaj o wersjonowaniu i synchronizacji zmian między środowiskami.

Optymalizacja bazy i czyszczenie danych

Przykładowe praktyki:

• wp transient delete –all — usuwa przeterminowane transienty.
• wp option list –search=”%” –format=table — audyt opcji.
• wp db optimize — optymalizacja tabel (w silniku MySQL/MariaDB).
• wp post delete $(wp post list –post_status=trash –field=ID) –force — opróżnia kosz.
• wp comment delete $(wp comment list –status=trash –field=comment_ID) –force

Regularne porządki skracają zapytania i obniżają zużycie pamięci. W połączeniu z indeksowaniem w bazie (poza zakresem WP-CLI) uzyskasz wymierne zyski dla dużych portali.

Cache, cron i przepisywanie adresów

Zarządzanie pamięcią podręczną i harmonogramem:

• wp cache flush — czyści wbudowany cache obiektów.
• wp cron event list — lista zaplanowanych zdarzeń.
• wp cron event run –due-now — uruchamia zaległe zadania.
• wp rewrite flush –hard — odświeża reguły przepisywania adresów.

Jeśli stosujesz zewnętrzny cache (Redis/Memcached), połącz WP-CLI z komendami systemowymi, aby spójnie czyścić warstwy buforowania po wdrożeniach.

Audyt i kontrola jakości

Testuj środowisko przed publikacją: wp doctor check (pakiet rozszerzający) wykryje typowe problemy. Dodatkowo, skrypty CI uruchamiające wp core verify-checksums oraz wp plugin verify-checksums pomogą wykryć zmodyfikowane pliki. To ważne zwłaszcza po ręcznych zmianach lub podejrzanych aktualizacjach.

Kopie zapasowe, migracje i automatyzacja

Eksport i import bazy danych

Podstawowy backup bazy wykonasz poleceniem: wp db export backup.sql. Przywracanie: wp db import backup.sql. Warto łączyć to z datą w nazwie pliku, np. backup-$(date +%F-%H%M).sql, aby utrzymać prostą historię kopii. Pamiętaj, by skompresować duże dumpy (gzip) i przechowywać je poza serwerem produkcyjnym.

Wyszukiwanie i zamiana danych (URL, ścieżki, serializacje)

Zmiana domeny lub katalogu wymaga ostrożności, bo WordPress przechowuje zserializowane dane. Używaj: wp search-replace stara-domena.pl nowa-domena.pl –all-tables –precise –recurse-objects. Flaga –precise zwiększa bezpieczeństwo serializacji kosztem wydajności. Dodaj –dry-run, by zobaczyć podsumowanie przed właściwą operacją.

Migracja plików i środowisk

Najprostsza migracja obejmuje trzy kroki: eksport bazy, synchronizację wp-content (rsync/scp) oraz search-replace domen/ścieżek. Przykład:

• wp db export prod.sql && gzip prod.sql
• rsync -avz –delete user@prod:/var/www/site/wp-content/ ./wp-content/
• wp db import prod.sql.gz (z użyciem zcat | wp db import -) na docelowym środowisku
• wp search-replace https://prod.example.com https://stage.example.com –all-tables

W sieci multisite dodaj parametry –network i/lub –url, aby ograniczyć operacje do właściwej strony. Po migracji zregeneruj miniatury i wyczyść cache, by uniknąć błędów 404 oraz nieaktualnych zasobów.

Automatyzacja w Bash, CI/CD i cronie

Twórz skrypty wdrożeniowe łączące WP-CLI z Git i rsync. Przykładowy schemat: pobranie kodu, composer install, wp core update-db, wp plugin update –all, czyszczenie cache, warm-up (curl do kluczowych podstron), testy kontrolne (wp core verify-checksums). W CI/CD (np. GitHub Actions, GitLab CI) uruchamiaj komendy na etapie build i deploy, przechowując sekrety w zmiennych środowiskowych.

Pakiety WP-CLI i rozszerzenia

Ekosystem rozszerzeń ułatwia czynności specjalistyczne. Sprawdź: wp package browse oraz instaluj: wp package install autor/pakiet. Popularne kategorie: testy zdrowia, biblioteki do pracy z mediami, narzędzia skanowania luk i weryfikacji integralności. Zawsze weryfikuj reputację pakietu i utrzymuj jego wersję w lockfile projektu.

Monitorowanie i diagnostyka

Dołącz logowanie i wskaźniki. Użyj wp option get home i wp option get siteurl do szybkich kontroli konfiguracji. Narzędzia: wp cron event list (opóźnione zadania), wp media regenerate (uszkodzone miniatury), wp theme status i wp plugin status (niespójności wersji). Integruj z zewnętrznymi loggerami, a wyniki komend przekierowuj do plików, np. wp plugin update –all | tee -a logs/updates.log.

Praktyczne scenariusze i dobre praktyki

Stawianie środowiska deweloperskiego

Skrypt inicjalizacyjny: pobranie rdzenia, stworzenie bazy, instalacja motywu bazowego i zestawu rozszerzeń, dodanie użytkowników testowych, import przykładowych treści (wp import plik.xml –authors=create), aktywacja trybu debug i logów. Dzięki temu każdy członek zespołu uruchomi projekt w minutach, a różnice środowisk będą minimalne.

Aktualizacje bez przestojów

Procedura bezpiecznej aktualizacji: maintenance-mode on, backup bazy i plików, aktualizacja rdzenia, języków, wtyczek i motywów, weryfikacja checksums, migracje bazy (core update-db oraz skrypty pluginów), smoke testy (status strony, logi błędów), maintenance-mode off. Zautomatyzuj to jednym skryptem, który zatrzyma się na błędzie i wycofa zmiany w razie problemu.

Optymalizacja i monitoring wydajności

Regularne przeglądy: usuwaj nieużywane wtyczki i motywy, czyść transienty, ogranicz rewizje (wp config set WP_POST_REVISIONS 10), zwiększ limity pamięci, włącz persistent object cache, indeksuj newralgiczne kolumny bazy (poza WP-CLI). Ustal wskaźniki (czas TTFB, obciążenie CPU, RAM) i mierz je po każdej zmianie, aby potwierdzić realne zyski dla wydajnośći.

Bezpieczeństwo i zgodność

Dobre praktyki obejmują: minimalne uprawnienia dla kont, regularne aktualizacje, weryfikację integralności (verify-checksums), szyfrowanie połączeń, rotację haseł i kluczy w wp-config (wp config shuffle-salts). Audytuj logi, blokuj edycję plików z panelu (wp config set DISALLOW_FILE_EDIT true), a w razie incydentu wykonaj szybkie skany i przywrócenie z kopii. Pamiętaj, że bezpieczeństwo to proces, nie jednorazowe działanie.

Standardy zespołowe i dokumentacja

Ustal wspólne aliasy, konwencje nazw środowisk, schematy wywołań oraz strukturę katalogów. Dokumentuj komendy o istotnym wpływie na dane. Dodaj pre-commit hooki uruchamiające testy, linting i krótką kontrolę WP-CLI (np. brak aktywnych wtyczek testowych na produkcji). Dobra dokumentacja minimalizuje czas wdrożenia nowych osób i zmniejsza ryzyko błędów.

Checklisty i szablony

Stwórz checklisty dla: nowych wdrożeń, aktualizacji, migracji, przywracania z kopii, czyszczenia danych oraz audytu. Szablony skryptów przechowuj w repozytorium i parametryzuj zmiennymi środowiskowymi (ENV). To podejście zapewnia powtarzalność niezależnie od członka zespołu czy dnia tygodnia.

Najczęstsze problemy i jak je rozwiązać

Typowe usterki: brak pamięci przy dużych operacjach (zwiększ limit i używaj batchy z –number, –offset), blokady tabel (uruchamiaj operacje poza szczytem), różne prefiksy tabel (sprawdź table_prefix w wp-config i dodaj –all-tables), brak uprawnień DB (zweryfikuj użytkownika i hosta), konflikt wersji PHP/rozszerzeń (sprawdź wp –info). W razie wątpliwości uruchamiaj komendy z –debug i analizuj szczegóły przebiegu.

Kultura pracy z CLI

Dbaj o spójność i prostotę. Jedna rzecz na raz, małe kroki, czytelne logi, komentarze w skryptach. Testuj na kopii, używaj –dry-run, kiedy to możliwe, a operacje destrukcyjne poprzedzaj snapshotem. Dziel się wiedzą w zespole: przykładowe skrypty, wzorce, dobre praktyki. Stosuj wersjonowanie i ciągłe doskonalenie procesów.

Łączenie z narzędziami zewnętrznymi

WP-CLI dobrze współpracuje z narzędziami systemowymi: jq do pracy z JSON, awk/sed/grep do selekcji, rsync do synchronizacji, openssl do szyfrowania. Komponując pipeline’y, przekształcisz pojedyncze polecenia w potężne procesy, które możesz uruchamiać cyklicznie lub zdarzeniowo w zależności od potrzeb projektu.

Na koniec pamiętaj: nie wszystko musi być zautomatyzowane od razu. Zaczynaj od najczęstszych zadań, zamieniaj je w skrypty, dokumentuj i stopniowo rozszerzaj zakres. W efekcie twoje procesy będą szybsze, stabilniejsze i łatwiejsze do utrzymania — zarówno teraz, jak i przy kolejnych iteracjach projektu.