WP-CLI essentials: de commando's die je echt gebruikt

Hoe je deze referentie gebruikt

Dit artikel behandelt de WP-CLI commando's waar ik dagelijks of wekelijks mee werk bij het beheren van WordPress-sites. Het is niet de volledige commandolijst (die staat in de officiële commandoreferentie en telt meer dan 46 top-level commando's). Het is wel de subset die 90% van het echte operationele werk afdekt: updates, pluginbeheer, gebruikersacties, database-exports, URL-vervangingen, cron, cache en healthchecks.

Versiebereik. Alle commando's zijn geverifieerd tegen WP-CLI 2.12.0 (uitgebracht op 7 mei 2025), met minimaal PHP 7.2.24 en ondersteuning voor PHP 8.4. Waar een vlag of subcommando in een specifieke versie is toegevoegd, staat het versienummer erbij.

Inhoud:

• WP-CLI installeren
• Globale vlaggen die je moet kennen
• Core-beheer
• Pluginbeheer
• Themabeheer
• Gebruikersbeheer
• Database-operaties
• Zoeken en vervangen
• Configuratiebeheer
• Cronbeheer
• Cache en transients
• Healthchecks met wp doctor
• WP-CLI in Docker draaien
• Handige aliassen en shellscripts
• Veelvoorkomende misverstanden

WP-CLI installeren

De aanbevolen methode is het Phar-archief. Downloaden, uitvoerbaar maken, verplaatsen naar een map in je $PATH:

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
wp --info

Dat laatste commando print de WP-CLI-versie, PHP-versie, het pad naar de PHP-binary en het pad naar wp-config.php (als je het draait in een WordPress-root). Werkt wp --info? Dan is de installatie in orde.

Updaten is een enkel commando: wp cli update. Het haalt de nieuwste stabiele Phar op en overschrijft de bestaande binary.

Alternatieven: Composer (composer global require wp-cli/wp-cli-bundle), Homebrew op macOS (brew install wp-cli) en OS-pakketten. In Docker levert de officiële wordpress:cli-image een kant-en-klare WP-CLI binary (zie WP-CLI in Docker draaien).

Globale vlaggen die je moet kennen

Elk WP-CLI commando accepteert deze vlaggen. Ze zijn niet specifiek voor een subcommando, maar lossen problemen op die bij scripting, debugging en multisite regelmatig opduiken:

Bron: WP-CLI configuratiereferentie.

Core-beheer

# Controleer of er een nieuwere WordPress-versie beschikbaar is.
wp core check-update

# Download en installeer de update.
wp core update

# Draai de database-upgrade routine (hetzelfde als /wp-admin/upgrade.php bezoeken).
wp core update-db

# Controleer of corebestanden zijn gewijzigd.
# De snelste eerste stap als je een compromis vermoedt.
wp core verify-checksums

wp core verify-checksums vergelijkt elk corebestand met de checksums die WordPress.org publiceert. Elk gewijzigd, toegevoegd of ontbrekend bestand wordt gerapporteerd. In WP-CLI 2.12.0 is de --exclude=<bestanden> vlag toegevoegd, zodat je bekende aanpassingen (een gepatcht wp-config-sample.php bijvoorbeeld) kunt whitelisten zonder valse positieven.

wp core download --locale=nl_NL downloadt een specifieke taalversie. Handig voor gescripte installaties waar het taalpakket er moet zijn voor de eerste boot.

Bron: wp core commando's.

Pluginbeheer

# Lijst alle plugins, hun status en of er updates beschikbaar zijn.
wp plugin list

# Installeer en activeer in een stap.
wp plugin install woocommerce --activate

# Update alle plugins met een openstaande update.
wp plugin update --all

# Deactiveer een plugin zonder de bestanden te verwijderen.
wp plugin deactivate akismet

# Verwijder een plugin (verwijdert bestanden; draait NIET de uninstall hooks).
wp plugin delete hello

# Controleer of een plugin actief is (exitcode 0 = actief, 1 = niet actief).
# Handig in shellscripts.
wp plugin is-active woocommerce

Sinds WP-CLI 2.12.0 respecteert wp plugin update --all de requires- en requires_php-headers in pluginmetadata. Als je WordPress- of PHP-versie te laag is voor een pluginupdate, wordt de plugin als "unavailable" gemarkeerd in plaats van stil te falen. De --force-check vlag forceert een verse updatecontrole bij de WordPress.org API, voorbij de transient-cache.

Voor het scripted bulkupdaten met een rapport, pijp je de output:

# Lijst plugins met beschikbare updates, alleen slugs.
wp plugin list --update=available --format=ids
# Geeft terug: akismet woocommerce yoast-seo

# Pipe naar update (xargs verwerkt de lijst).
wp plugin list --update=available --format=ids | xargs wp plugin update

Bron: wp plugin commando's.

Themabeheer

Het patroon is identiek aan plugins: wp theme install, wp theme activate, wp theme update --all, wp theme delete, wp theme list. Dezelfde --force-check vlag uit 2.12.0 werkt ook hier.

# Schakel over naar een thema, installeer het eerst als dat nodig is.
wp theme install flavor --activate

# Update alle thema's.
wp theme update --all

Een verschil: wp theme activate accepteert maar een thema tegelijk (je kunt er maar een actief hebben), terwijl wp plugin activate meerdere slugs accepteert.

Bron: wp theme commando's.

Gebruikersbeheer

# Maak een gebruiker aan met de administrator-rol.
# WP-CLI genereert automatisch een veilig wachtwoord en print het naar stdout.
wp user create jan jan@jouwsite.nl --role=administrator

# Lijst alle gebruikers met ID, login, e-mail en rol.
wp user list

# Reset het wachtwoord van een gebruiker (stuurt de reset-e-mail).
wp user reset-password 1

# Update een wachtwoord direct (vermijd dit in gedeelde terminals, zie opmerking).
wp user update 1 --user_pass='nieuw-wachtwoord-hier'

# Verwijder een gebruiker en wijs hun berichten toe aan gebruiker ID 2.
# Gebruik altijd --reassign om verweesd content te voorkomen.
wp user delete 5 --reassign=2

Waarschuwing over shellgeschiedenis. wp user create met --user_pass en wp user update met --user_pass schrijven het wachtwoord in je shellhistorie. Op een gedeelde server is dat een credentiallek. Gebruik in plaats daarvan --prompt=user_pass, dat interactief vraagt:

wp user update 1 --prompt=user_pass

Hetzelfde geldt voor wp config create --dbpass: gebruik liever --prompt=dbpass of stel credentials in via omgevingsvariabelen.

Bron: wp user commando's.

Database-operaties

# Exporteer de volledige database naar een bestand met datumstempel.
wp db export backup-$(date +%Y%m%d).sql

# Importeer vanuit een dump.
wp db import backup-20260408.sql

# Voer een raw SQL-query uit.
wp db query "SELECT option_value FROM wp_options WHERE option_name = 'siteurl'"

# Controleer tabelintegriteit.
wp db check

# Optimaliseer tabellen (handig na massale verwijderingen of WooCommerce-orderpurges).
wp db optimize

# Rapporteer databasegrootte per tabel.
wp db size --tables

Alle wp db commando's lezen credentials uit wp-config.php. Je hoeft nooit database-gebruikersnamen of wachtwoorden op de commandoregel mee te geven.

wp db reset --yes dropt en recreëert alle tabellen. Het is de nucleaire optie. De --yes vlag is juist vereist omdat het commando onomkeerbaar is zonder backup.

Bron: wp db commando's.

Zoeken en vervangen

wp search-replace is het meest ingrijpende enkele commando in WP-CLI. Het herschrijft strings door de hele database, gaat correct om met geserialiseerde PHP-data en heeft geen undo. Het uitgebreide artikel over WordPress zoeken-en-vervangen na migratie behandelt de volledige workflow, inclusief de Gutenberg JSON-escape valkuil en per-tabel scope. Hier de commandoreferentie.

# Stap 1: ALTIJD eerst een dry-run. Toont wat er zou veranderen zonder te schrijven.
wp search-replace 'https://oud.jouwsite.nl' 'https://nieuw.jouwsite.nl' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --dry-run

# Stap 2: Voer de vervanging door.
wp search-replace 'https://oud.jouwsite.nl' 'https://nieuw.jouwsite.nl' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --precise

Vlaggen die ertoe doen

Bron: wp search-replace.

Configuratiebeheer

# Genereer een wp-config.php vanuit nul.
wp config create --dbname=mydb --dbuser=user --dbpass=pass --locale=nl_NL

# Lees een constante.
wp config get WP_DEBUG

# Stel een boolean constante in (--raw betekent: niet als string quoten in PHP).
wp config set WP_DEBUG true --raw

# Controleer of een constante truthy is (exitcode 0 = true).
# Toegevoegd in WP-CLI 2.9.0. Handig in shellcondities.
wp config is-true WP_DEBUG

# Lijst alle gedefinieerde constanten, variabelen en bestandsincludes.
wp config list

Voor een diepere duik in wat elke constante doet en welke defaults ertoe doen, behandelt de wp-config.php referentie de volledige set.

Bron: wp config commando's.

Cronbeheer

WP-Cron is een pseudoscheduler die alleen afgaat als iemand de site bezoekt. Op sites met weinig verkeer of achter agressieve pagecaching stoppen geplande taken gewoon stil. De betrouwbare oplossing is om WP-Cron uit te schakelen en te vervangen door een systeemcron.

# Lijst alle geplande cronevents met hun volgende looptijd.
wp cron event list

# Trigger handmatig een specifieke hook.
wp cron event run wp_update_plugins

# Draai alle events die op dit moment due zijn.
wp cron event run --due-now

# Lijst gedefinieerde cronschema's (hourly, twicedaily, daily, etc.).
wp cron schedule list

# Test of WP-Cron's HTTP-loopback werkt.
wp cron test

WP-Cron vervangen door een systeemcron

Schakel eerst de ingebouwde WP-Cron trigger uit in wp-config.php:

define('DISABLE_WP_CRON', true);

Voeg dan een regel toe aan de crontab van je server:

# Draait elke minuut. WP-CLI voert alleen de events uit die daadwerkelijk due zijn.
* * * * * /usr/local/bin/wp --path=/var/www/html cron event run --due-now >/dev/null 2>&1

De --due-now vlag is de sleutel: het checkt welke events hun geplande tijd gepasseerd zijn en draait alleen die. Elke minuut wp cron event run --due-now draaien is veilig en idempotent.

WP-CLI cron draait in een CLI-proces, niet via HTTP. Dit is een apart uitvoeringspad ten opzichte van WP-Cron's interne HTTP POST naar wp-cron.php. PHP-fouten verschijnen in de terminal (of crontab-mail) in plaats van opgeslokt te worden door een achtergrond-HTTP-request.

Bron: wp cron commando's.

Cache en transients

# Flush de object cache.
wp cache flush

# Rapporteer welke cachebackend actief is (default, Redis, Memcached, etc.).
wp cache type

# Verwijder alle transients uit de database.
wp transient delete --all

Wanneer wp cache flush niets doet. Zonder een persistent cache drop-in (Redis, Memcached) leeft WordPress's objectcache in het PHP-geheugen van het huidige proces. wp cache flush draaien wist dan de in-memory cache van het CLI-proces, die toch wordt weggegooid als het commando eindigt. In dat geval is wp cache flush een no-op. Het heeft alleen echt effect als er een persistent cache drop-in geinstalleerd is; dan flusht het de gedeelde backend en raakt alle requests site-breed.

In WP-CLI 2.12.0 kregen zowel wp cache als wp transient de subcommando's pluck en patch, waarmee je geneste waarden in gecachte arrays kunt lezen en wijzigen zonder de hele blob op te halen en opnieuw weg te schrijven.

Bron: wp cache commando's, wp transient commando's.

Healthchecks met wp doctor

wp doctor zit niet standaard bij WP-CLI. Installeer het eerst als package:

wp package install wp-cli/doctor-command

Draai het dan:

# Draai alle standaard diagnostische checks.
wp doctor check --all

De standaard checksuite omvat 13 controles:

Elke check geeft success, warning of error terug. Aangepaste checksuites definieer je in een doctor.yml-bestand.

Bron: WP-CLI Doctor handbook, doctor-command op GitHub.

WP-CLI in Docker draaien

Docker-containers draaien doorgaans als root. WP-CLI weigert standaard als root te draaien en toont een beveiligingswaarschuwing: "any code within your WordPress instance will have full privileges to the entire server." Twee manieren om dat te onderdrukken:

Optie 1: de --allow-root vlag per commando.

docker exec wordpress-app wp --allow-root plugin update --all

Optie 2: de WP_CLI_ALLOW_ROOT omgevingsvariabele (schoner voor Docker).

Stel het in via je compose.yaml of Dockerfile zodat elke wp-aanroep in de container de waarschuwing automatisch overslaat:

# compose.yaml fragment
services:
  wpcli:
    image: wordpress:cli
    environment:
      WP_CLI_ALLOW_ROOT: "1"
    volumes:
      - wordpress-data:/var/www/html

De --allow-root vlag geeft geen extra rechten. Het onderdrukt alleen de waarschuwing. De WordPress Docker tutorial behandelt een volledige Compose-setup met WP-CLI als profiled service.

Als non-root draaien is altijd beter. In Docker betekent dit een user:-directive in het Compose-bestand of een USER-instructie in de Dockerfile. De containersandbox is niet in elke orchestration-setup een echte beveiligingsgrens, en als root draaien in de container wordt een echte privilege-escalatievector als de container bij de host kan.

Bron: WP-CLI GitHub issue #4548.

Handige aliassen en shellscripts

Wekelijks onderhoudsscript

#!/usr/bin/env bash
# wp-maintenance.sh - draai wekelijks via cron of handmatig.
set -euo pipefail

WP_PATH="/var/www/html"

echo "=== Core-integriteitscheck ==="
wp --path="$WP_PATH" core verify-checksums

echo "=== Pluginupdates ==="
wp --path="$WP_PATH" plugin update --all

echo "=== Thema-updates ==="
wp --path="$WP_PATH" theme update --all

echo "=== Database-optimalisatie ==="
wp --path="$WP_PATH" db optimize

echo "=== Cache flush ==="
wp --path="$WP_PATH" cache flush

echo "=== Doctor check ==="
wp --path="$WP_PATH" doctor check --all

Shell-aliassen

Voeg deze toe aan ~/.bashrc of ~/.zshrc:

# Snelle site-info.
alias wpinfo='wp --info && wp core version && wp plugin list --format=table'

# Veilige search-replace (alleen dry-run).
alias wpsr-dry='wp search-replace --all-tables-with-prefix --skip-columns=guid --dry-run'

# Export met datumstempel.
alias wpbackup='wp db export backup-$(date +%Y%m%d-%H%M%S).sql'

Plugins met openstaande updates als JSON

wp plugin list --update=available --format=json | jq '.[].name'

Handig om te voeden aan monitoring- of notificatiesystemen. De --format=json vlag werkt op vrijwel elk wp ... list commando.

Veelvoorkomende misverstanden

"WP-CLI vereist SSH-toegang." Dat klopt niet. WP-CLI is een PHP-commandoregeltool die in elke shellsessie draait: een SSH-terminal, een docker exec-shell, een vagrant ssh-sessie, een kubectl exec-pod of de ingebouwde terminal van je hostingpaneel. Veel managed WordPress-hosts (Kinsta, WP Engine, Pantheon) bieden WP-CLI aan via hun controlepaneel zonder dat je zelf SSH configureert. WP-CLI's --ssh vlag laat je commando's proxyen naar een remote server over SSH, maar lokaal gebruik heeft helemaal geen SSH nodig.

"wp search-replace zonder --precise is prima voor de meeste sites." Dat is het niet. Zonder --precise gebruikt WP-CLI SQL-level stringvervanging en schakelt alleen over naar PHP-verwerking als het geserialiseerde data detecteert via column-type heuristieken. Die heuristieken missen soms geserialiseerde blobs in niet-standaard kolommen, waardoor ze stil gecorrumpeerd raken. De --precise vlag forceert PHP-level verwerking voor elke rij. Het is trager, maar bij databases onder een paar gigabyte is het verschil verwaarloosbaar. Gebruik --precise altijd bij migraties.

"WP-CLI's croncommando's gebruiken hetzelfde pad als WP-Cron." Dat doen ze niet. WP-Cron werkt door op elke paginalading een HTTP POST te spawnen naar wp-cron.php. wp cron event run voert events direct uit in het CLI-proces, zonder enig HTTP-request. Dit is een compleet gescheiden uitvoeringspad. PHP fatal errors die WP-Cron stil opslikt, verschijnen gewoon in de terminal als je wp cron event run draait. Juist die scheiding is de reden dat het systeemcron vervangingspatroon betrouwbaarder is.