WP-CLI: guida completa ai comandi WordPress da terminale

Gestire WordPress dalla dashboard è comodo finché le operazioni sono poche e occasionali. Quando devi aggiornare più plugin, intervenire sul database, sostituire URL dopo una migrazione, controllare WP-Cron o ripetere la stessa procedura su più installazioni, però, cliccare nell’interfaccia diventa rapidamente il modo meno efficiente di lavorare.

WP-CLI è l’interfaccia a riga di comando ufficiale per WordPress. Permette di eseguire dal terminale molte delle operazioni che normalmente faresti nel back-end, ma con un vantaggio importante: i comandi possono essere ripetuti, concatenati, inseriti in script e utilizzati anche su server remoti.

La documentazione ufficiale di WP-CLI include comandi per core, plugin, temi, database, utenti, contenuti, media, cron, cache e numerose altre aree di WordPress.

Il punto, però, non è imparare a memoria decine di comandi. In questa guida vedremo come ragiona WP-CLI, quali operazioni conviene realmente spostare sul terminale, come evitare gli errori più pericolosi e come passare dalle operazioni manuali alle automazioni senza perdere controllo su ciò che succede al sito.

Cos’è WP-CLI e perché cambia il modo di gestire WordPress

WP-CLI significa WordPress Command Line Interface. In pratica, invece di aprire il browser, entrare in /wp-admin/, navigare tra menu e premere pulsanti, puoi impartire istruzioni a WordPress direttamente da una shell.

Un comando come:

wp plugin list

chiede a WordPress di restituire l’elenco dei plugin installati.

Questo:

wp core check-update

controlla invece se sono disponibili aggiornamenti del core.

E questo:

wp cron event list

mostra gli eventi registrati nel sistema WP-Cron.

Sono operazioni differenti, ma condividono la stessa logica:

wp → oggetto → azione → argomenti/opzioni

Capire questa struttura è molto più utile che memorizzare una lista di istruzioni.

WP-CLI rispetto alla dashboard di WordPress

La dashboard e WP-CLI non sono due sistemi separati. Nella maggior parte dei casi sono due modi differenti di interagire con la stessa installazione WordPress.

Se dalla dashboard attivi un plugin, WordPress modifica il suo stato. Se esegui:

wp plugin activate nome-plugin

l’obiettivo finale è analogo, ma il percorso cambia.

Da terminale puoi:

• eseguire l’operazione senza caricare un’interfaccia grafica;
• ripeterla in modo identico;
• applicarla a più componenti;
• concatenarla con altre operazioni;
• inserirla in uno script;
• elaborarne l’output con altri strumenti.

La differenza diventa evidente quando il lavoro cresce.

Aggiornare un plugin dalla dashboard non è complicato. Aggiornare venti installazioni WordPress, verificare quali plugin sono cambiati e registrare il risultato è un problema completamente diverso.

WP-CLI nasce proprio in questo secondo scenario.

Cosa puoi fare realmente dalla riga di comando

La command reference ufficiale comprende un insieme molto ampio di comandi. Tra le operazioni più comuni puoi:

• installare e aggiornare WordPress;
• gestire plugin e temi;
• esportare e importare database;
• modificare opzioni;
• creare e gestire utenti;
• lavorare con post, termini e media;
• controllare gli eventi WP-Cron;
• verificare file core e plugin;
• eseguire search-replace nel database;
• gestire installazioni multisite;
• eseguire codice PHP;
• utilizzare comandi personalizzati e package.

Questo non significa che WP-CLI debba sostituire sempre /wp-admin/. Significa che ti offre un’interfaccia più adatta quando l’operazione deve essere precisa, ripetibile o automatizzabile.

Quando WP-CLI conviene e quando la dashboard resta più pratica

Userei WP-CLI soprattutto per aggiornamenti ripetuti, migrazioni, manutenzione, troubleshooting, gestione del database e automazioni.

La dashboard resta invece perfettamente sensata quando devi svolgere un’attività visuale o occasionale: comporre una pagina, controllare una configurazione grafica, modificare un menu o lavorare con un plugin la cui UI fornisce informazioni che il comando non restituisce in modo altrettanto leggibile.

La domanda corretta non è quindi “WP-CLI o dashboard?”, ma:

questa operazione trae vantaggio dall’essere trasformata in un comando ripetibile?

Se la risposta è sì, vale la pena spostarla sul terminale.

Cosa serve prima di usare WP-CLI

Prima dei comandi viene l’ambiente in cui vengono eseguiti.

WP-CLI non è una console remota magica capace di collegarsi automaticamente al tuo WordPress. Deve poter raggiungere i file dell’installazione, utilizzare PHP e, per molte operazioni, caricare la configurazione del sito.

Terminale, PHP e accesso al server

La documentazione di installazione corrente richiede PHP 7.2.24 o successivo e indica il pacchetto Phar come metodo raccomandato per l’installazione manuale. Il requisito è un dato software volatile: prima di installare WP-CLI su un ambiente nuovo conviene quindi controllare sempre la pagina ufficiale di installazione.

Il primo controllo è semplice:

php --version

Poi verifica WP-CLI:

wp --info

wp --info è molto utile anche nel troubleshooting perché mostra, tra le altre cose, il binario PHP utilizzato dalla CLI e il file php.ini caricato.

Questo dettaglio conta: il PHP usato dal terminale può non essere lo stesso utilizzato dal sito web.

Su hosting o server con più versioni PHP potresti quindi avere un sito che funziona correttamente via browser e un comando WP-CLI che genera errori perché la shell utilizza un interprete differente.

SSH, directory di WordPress e permessi

Se WordPress si trova su un server remoto, normalmente accederai alla macchina tramite SSH.

Se non hai familiarità con questo passaggio, prima di usare WP-CLI conviene capire come funziona SSH e come viene utilizzato per amministrare un server.

Una volta entrato nel server, devi spostarti nella directory dell’installazione:

cd /percorso/del/sito

e verificare che WP-CLI riesca a riconoscere WordPress:

wp core is-installed

Se invece vuoi eseguire il comando da un’altra directory, puoi indicare esplicitamente il percorso:

wp core is-installed --path=/var/www/html

Qui emerge una delle caratteristiche più importanti di WP-CLI: il contesto conta quanto il comando.

Stessa istruzione, directory diversa, installazione diversa.

Prima di un comando che modifica dati, assicurati sempre di sapere su quale sito stai operando.

Come verificare se il tuo hosting ha già WP-CLI

Molti hosting orientati a WordPress forniscono WP-CLI senza richiedere un’installazione manuale.

Dopo l’accesso SSH prova:

wp --info

e:

wp cli version

Se entrambi funzionano, normalmente non hai bisogno di installare una seconda copia.

Prima di aggiornare manualmente un WP-CLI fornito dal provider, verifica inoltre come viene gestito dall’hosting. Una versione centralizzata potrebbe essere mantenuta direttamente dal provider.

Come installare WP-CLI e verificare che funzioni

Se WP-CLI non è disponibile, la procedura ufficiale raccomandata su sistemi Unix-like consiste nel scaricare il file Phar, verificarlo e renderlo eseguibile.

Installazione consigliata su Linux e macOS

Puoi scaricare il file con:

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

Verifica inizialmente che il file venga eseguito:

php wp-cli.phar --info

Poi rendilo eseguibile:

chmod +x wp-cli.phar

e spostalo in una directory presente nel PATH:

sudo mv wp-cli.phar /usr/local/bin/wp

A questo punto:

wp --info

dovrebbe funzionare da qualsiasi directory.

La documentazione ufficiale descrive anche procedure alternative tramite Homebrew, Composer, Docker e package specifici per alcune distribuzioni.

Non sceglierei un metodo alternativo solo perché sembra più sofisticato. Se ti serve semplicemente utilizzare WP-CLI, il Phar è una soluzione diretta e facilmente comprensibile. Composer acquista più senso quando WP-CLI entra in un progetto PHP già gestito come dipendenza.

Installare WP-CLI su Windows

Anche su Windows PHP deve essere disponibile nel PATH.

La procedura ufficiale suggerisce di salvare wp-cli.phar, per esempio in:

C:\wp-cli

e creare nella stessa directory un file wp.bat con:

@ECHO OFF
php "c:/wp-cli/wp-cli.phar" %*

Poi aggiungi la directory al PATH:

setx path "%path%;c:\wp-cli"

La documentazione distingue inoltre il caso di Git Bash, dove il wrapper .bat non viene utilizzato nello stesso modo.

Se lavori principalmente con WordPress locale su Windows, valuta comunque se il tuo ambiente di sviluppo integra già WP-CLI. Installarne più copie senza sapere quale viene richiamata dal PATH può complicare inutilmente il debugging.

wp --info, wp cli version e wp help: i primi controlli da fare

Dopo l’installazione eseguirei sempre:

wp --info

wp cli version

wp help

Per ottenere informazioni su un comando specifico:

wp help plugin

oppure:

wp help search-replace

La guida integrata è una delle funzioni più utili di WP-CLI. Quando devi utilizzare un’opzione che non ricordi, è meglio controllarne sintassi e significato invece di affidarti alla memoria.

Come è fatto un comando WP-CLI: sintassi, argomenti e opzioni

La vera svolta arriva quando smetti di considerare i comandi come stringhe da copiare e inizi a leggerne la struttura.

Prendiamo:

wp plugin update akismet

Puoi scomporlo così:

wp
└── plugin
    └── update
        └── akismet

wp richiama WP-CLI.

plugin identifica l’area su cui vuoi lavorare.

update indica l’azione.

akismet è l’argomento che specifica il plugin.

A questo puoi aggiungere opzioni:

wp plugin update akismet --dry-run

In questo caso --dry-run chiede di simulare l’aggiornamento senza eseguirlo realmente. La funzione è documentata per wp plugin update.

Argomenti posizionali, flag e parametri

Considera:

wp user create mario [email protected] --role=editor

mario e [email protected] sono argomenti necessari al comando.

--role=editor modifica invece il comportamento assegnando il ruolo Editor al nuovo utente.

La documentazione WP-CLI usa convenzioni abbastanza regolari:

<argomento>        obbligatorio
[<argomento>]      opzionale
--flag             opzione booleana
--chiave=valore    opzione con valore

Questa sintassi permette di leggere quasi qualsiasi pagina della command reference senza conoscere già il comando.

Le opzioni globali che risolvono molti problemi

WP-CLI dispone anche di parametri globali che possono essere utilizzati con molti comandi.

Fra quelli più utili:

--path=/percorso/wordpress

indica quale installazione utilizzare.

--url=https://example.com

specifica il sito da simulare ed è particolarmente importante nel multisite.

--user=admin

esegue l’operazione nel contesto dell’utente indicato quando il comando lo utilizza.

--skip-plugins

evita il caricamento dei plugin normali.

--skip-themes

evita il caricamento dei temi.

--debug

aumenta le informazioni diagnostiche.

Sono opzioni particolarmente importanti perché molti presunti “errori WP-CLI” derivano in realtà da directory sbagliata, PHP sbagliato, configurazione WordPress o codice caricato da plugin e tema. La command reference documenta questi parametri come opzioni globali.

Gestire WordPress core con WP-CLI

Una delle applicazioni più naturali di WP-CLI è la manutenzione del core.

Per conoscere la versione installata:

wp core version

Per controllare se esistono aggiornamenti:

wp core check-update

Per aggiornare:

wp core update

Dopo un aggiornamento che richiede modifiche alla struttura del database:

wp core update-db

WP-CLI include anche comandi per installazione, download e gestione multisite. La documentazione del gruppo wp core mantiene l’elenco corrente dei sottocomandi disponibili.

Aggiornare WordPress senza trasformare il comando in una scorciatoia pericolosa

Il fatto che basti una riga per aggiornare WordPress non elimina le normali precauzioni.

Prima di intervenire su un sito importante dovresti sapere:

1. se esiste un backup ripristinabile;
2. se temi e plugin sono compatibili;
3. se puoi testare l’aggiornamento in staging;
4. come verificare il sito dopo l’operazione.

WP-CLI rende più veloce l’esecuzione, non rende inutile il processo di manutenzione.

Se devi approfondire l’intero workflow, trovi i passaggi nella guida su come aggiornare WordPress in sicurezza.

Verificare l’integrità dei file core con i checksum

Un comando molto utile in diagnostica è:

wp core verify-checksums

Confronta i file del core con i checksum pubblicati per WordPress.

Se il controllo segnala una differenza, significa che almeno un file verificato non corrisponde alla copia attesa. Non significa automaticamente “il sito è stato hackerato”: la causa può essere malware, una modifica manuale, un file incompleto o un altro intervento sull’installazione.

Il valore del comando è proprio questo: trasforma un sospetto generico in una differenza verificabile.

Gestire plugin e temi da terminale

Il gruppo wp plugin permette di installare, attivare, disattivare, aggiornare, eliminare e interrogare i plugin.

Per vedere quelli installati:

wp plugin list

Per installarne uno dal repository WordPress.org:

wp plugin install akismet

Per installarlo e attivarlo immediatamente:

wp plugin install akismet --activate

Per attivare un plugin già presente:

wp plugin activate akismet

Per disattivarlo:

wp plugin deactivate akismet

Per aggiornare un singolo plugin:

wp plugin update akismet

Per simulare prima l’aggiornamento:

wp plugin update akismet --dry-run

Per aggiornare tutti i plugin disponibili:

wp plugin update --all

Il punto interessante non è risparmiare tre clic. È poter interrogare e modificare molti componenti in modo prevedibile.

Gestire i temi

La logica è analoga:

wp theme list

wp theme install twentytwentyfive

wp theme activate twentytwentyfive

wp theme update --all

Prima di lanciare aggiornamenti massivi su un sito in produzione, però, eviterei di trasformare la comodità di --all in un automatismo.

Un aggiornamento multiplo riduce il lavoro manuale, ma aumenta il numero di variabili modificate contemporaneamente. Su progetti importanti è spesso meglio separare:

backup → staging → aggiornamento → verifica → produzione

Se devi strutturare questo processo, puoi approfondire come usare un ambiente staging WordPress.

Disattivare plugin durante un troubleshooting

Immagina che WordPress generi un errore fatale e che non riesca più ad aprire il pannello.

WP-CLI può permetterti di disattivare il componente problematico senza entrare nella dashboard:

wp plugin deactivate nome-plugin

Se invece vuoi capire se il bootstrap fallisce a causa di un plugin, prova un comando diagnostico senza caricarli:

wp plugin list --skip-plugins --skip-themes

La documentazione di troubleshooting conferma che plugin e temi possono interferire con il caricamento di WP-CLI e che --skip-plugins e --skip-themes sono strumenti utili per isolarli.

Questa è una distinzione fondamentale: non stai “risolvendo WP-CLI”, stai usando WP-CLI per capire quale parte dell’ambiente WordPress sta impedendo il caricamento corretto.

Database WordPress con WP-CLI: export, import e manutenzione

WP-CLI può interagire con il database utilizzando le credenziali presenti in wp-config.php.

Il gruppo wp db comprende operazioni di controllo, export, import, query, ottimizzazione, riparazione e altre funzioni amministrative.

Per verificare il database:

wp db check

Per esportarlo:

wp db export backup-before-change.sql

Per importare un dump:

wp db import backup-before-change.sql

Cosa contiene davvero wp db export

Qui c’è un errore concettuale che vale la pena evitare.

Il comando:

wp db export backup.sql

crea un backup del database, non un backup completo del sito.

Nel database trovi contenuti, opzioni, utenti, configurazioni e molti dati dei plugin. Non contiene però automaticamente tutto il filesystem di WordPress: temi, plugin, upload e altri file devono essere salvati separatamente.

Per un ripristino completo devi quindi ragionare almeno su:

database + wp-content + configurazioni/file necessari

Se vuoi una strategia più semplice per siti normali, puoi partire dalla guida dedicata al backup di WordPress e al ripristino del sito.

Operazioni distruttive: il problema non è il comando, ma il contesto

WP-CLI contiene anche comandi in grado di eliminare o azzerare dati.

Il fatto che esistano nella command reference non significa che siano comandi da “provare”.

Prima di qualsiasi istruzione distruttiva verifica sempre:

wp option get siteurl

e, quando necessario:

wp option get home

In questo modo hai almeno una conferma immediata del sito su cui stai lavorando.

Su infrastrutture con produzione, staging e sviluppo, questa abitudine vale più di qualsiasi scorciatoia.

wp search-replace: modificare URL e dati senza rompere WordPress

wp search-replace è uno dei comandi WP-CLI più utili e allo stesso tempo uno di quelli da utilizzare con maggiore attenzione.

Serve a cercare un valore nel database e sostituirlo con un altro.

Il caso classico è una migrazione:

https://vecchio-dominio.it
→
https://nuovo-dominio.it

Un normale search-replace SQL può creare problemi con dati PHP serializzati. WP-CLI gestisce invece in modo consapevole la serializzazione e non modifica le chiavi primarie.

Iniziare sempre con --dry-run

Prima di modificare realmente il database:

wp search-replace \
'https://vecchio-dominio.it' \
'https://nuovo-dominio.it' \
--dry-run

--dry-run esegue la ricerca e produce il report senza salvare le modifiche.

Solo dopo aver verificato il risultato puoi decidere di eseguire:

wp search-replace \
'https://vecchio-dominio.it' \
'https://nuovo-dominio.it'

La sequenza corretta non è quindi:

comando → speriamo

ma:

backup → dry-run → verifica → esecuzione → verifica finale

Quando usare --all-tables-with-prefix

Per impostazione predefinita wp search-replace lavora sulle tabelle registrate nell’oggetto $wpdb.

In alcuni progetti possono esistere ulteriori tabelle con lo stesso prefisso. Se sai che devono essere incluse puoi utilizzare:

wp search-replace \
'https://vecchio-dominio.it' \
'https://nuovo-dominio.it' \
--all-tables-with-prefix \
--dry-run

Non aggiungerei l’opzione automaticamente a qualsiasi tutorial di migrazione.

Ampliare il numero di tabelle significa ampliare anche il perimetro della modifica. Prima devi sapere quali dati vuoi cambiare.

Migrazioni e cambio dominio

Durante una migrazione può essere necessario modificare anche home e siteurl.

Per esempio:

wp option update home 'https://nuovo-dominio.it'

wp option update siteurl 'https://nuovo-dominio.it'

Se stai affrontando specificamente questo scenario, nella guida su come modificare correttamente l’URL di WordPress trovi anche gli altri metodi disponibili.

Il punto importante è distinguere due operazioni:

cambiare gli URL principali di WordPress e sostituire riferimenti al vecchio dominio nei dati non sono necessariamente la stessa cosa.

WP-CLI permette di gestirle entrambe, ma con comandi differenti.

Gestire utenti, contenuti, cron, cache e media

WP-CLI non si ferma alla manutenzione tecnica.

Puoi interrogare una parte consistente dei dati e delle funzioni operative di WordPress.

Utenti

Per vedere gli utenti:

wp user list

Puoi limitare l’output:

wp user list --fields=ID,user_login,user_email,roles

Per creare un nuovo utente:

wp user create mario [email protected] --role=editor

Per modificarne il ruolo:

wp user update mario --role=author

In uno script eviterei invece di inserire password sensibili direttamente nella riga di comando quando esistono alternative più sicure, perché comandi e cronologia della shell possono diventare un punto di esposizione.

WP-Cron

Per elencare gli eventi pianificati:

wp cron event list

Per mostrare soltanto hook e prossima esecuzione:

wp cron event list --fields=hook,next_run

Per eseguire gli eventi scaduti:

wp cron event run --due-now

La command reference permette inoltre di pianificare, eliminare e annullare eventi.

Questo è particolarmente utile quando devi capire se un problema dipende dal sistema WP-Cron o dalla normale attivazione degli eventi attraverso le visite al sito.

Cache e transient

WP-CLI dispone di comandi per interagire con la cache oggetti e con i transient.

Per esempio:

wp cache flush

può svuotare la WordPress Object Cache dell’installazione.

Prima di usare questo comando su un sito ad alto traffico devi però conoscere il sistema di caching reale. WordPress Object Cache, page cache, CDN e cache proprietarie dell’hosting sono livelli differenti: svuotarne uno non significa necessariamente svuotare tutti gli altri.

Media

Per rigenerare le miniature:

wp media regenerate --yes

Su una Media Library molto grande questa operazione può diventare pesante. Prima di lanciarla indiscriminatamente valuta quantità di allegati, spazio disponibile e carico del server.

Ancora una volta, WP-CLI rende semplice avviare l’operazione. Non decide al posto tuo se sia una buona idea.

Come usare WP-CLI in sicurezza

WP-CLI può modificare WordPress con grande velocità.

È esattamente il motivo per cui va trattato come uno strumento amministrativo e non come un insieme di comandi da copiare senza contesto.

Backup e staging prima dei comandi ad alto impatto

Prima di search-replace, aggiornamenti importanti, importazioni o operazioni massive preferisco sempre questo ordine:

backup
↓
staging quando possibile
↓
comando
↓
verifica tecnica
↓
verifica funzionale
↓
produzione

Per una modifica piccola può sembrare prudenza eccessiva. Ma quando il comando opera su migliaia di righe del database, il costo di un controllo preventivo è molto inferiore al costo di un rollback improvvisato.

Root, privilegi e permessi

Usare un account con più privilegi del necessario aumenta il potenziale impatto di un errore.

WP-CLI può inoltre comportarsi diversamente quando il proprietario dei file, l’utente della shell e l’utente utilizzato dal processo web non coincidono.

Se dopo un comando compaiono file appartenenti all’utente sbagliato, il problema potrebbe manifestarsi più tardi come errore negli aggiornamenti, negli upload o nella cache.

Non limitarti quindi a chiedere:

Il comando funziona?

Chiedi anche:

Con quale utente viene eseguito e quali file può modificare?

--dry-run non esiste per qualsiasi operazione

Uno degli errori più facili da commettere è pensare che ogni comando WP-CLI possa essere simulato.

Non è così.

Usa --dry-run solo quando il comando specifico lo documenta.

Per gli altri casi, il controllo preventivo deve essere costruito diversamente: backup, staging, interrogazione dello stato corrente o esecuzione su un sottoinsieme controllato.

Mantieni segreti e credenziali fuori dagli script quando possibile

Un comando è testo.

Se scrivi password, token o chiavi direttamente in uno script, devi considerare:

• chi può leggere il file;
• se lo script entra in Git;
• se il comando viene registrato nella shell history;
• se il sistema di CI/CD registra l’output;
• quali utenti possono leggere variabili e log.

Il vantaggio dell’automazione non compensa una gestione debole dei segreti.

Per i siti esposti pubblicamente, WP-CLI va inserito in una strategia più ampia di sicurezza WordPress, non considerato una misura di sicurezza in sé.

Risolvere gli errori WP-CLI più comuni

Quando WP-CLI genera un errore, la prima domanda non dovrebbe essere “come faccio a far sparire il messaggio?”, ma:

in quale fase sta fallendo?

Un comando può fallire prima di caricare WordPress, durante wp-config.php, durante il bootstrap del CMS oppure a causa di codice proveniente da plugin e temi.

La guida ufficiale al troubleshooting parte proprio da configurazione, ambiente, estensioni e bootstrap.

“This does not seem to be a WordPress installation”

Se WP-CLI non trova WordPress, controlla innanzitutto la directory:

pwd

e i file:

ls

Poi prova:

wp core is-installed

Se WordPress si trova altrove:

wp core is-installed --path=/percorso/corretto

Qui --path non è una soluzione magica. Sta semplicemente dicendo a WP-CLI quale directory deve trattare come installazione.

Un plugin o un tema blocca il caricamento

Prova a escludere i plugin:

wp plugin list --skip-plugins

oppure plugin e tema:

wp plugin list --skip-plugins --skip-themes

Se il comando torna a funzionare, hai ristretto il problema.

Puoi quindi tentare con un singolo plugin escluso:

wp plugin list --skip-plugins=nome-plugin

Questo approccio è molto più utile di disattivare componenti casualmente: stai costruendo una diagnosi per esclusione.

Errori PHP

Controlla:

wp --info

e confronta il PHP indicato con quello previsto dall’ambiente.

Per maggiore dettaglio:

wp plugin list --debug

--debug mostra informazioni aggiuntive sul bootstrap e gli errori PHP.

Se il sito funziona via browser e WP-CLI no, uno dei primi sospetti dovrebbe essere proprio la differenza fra ambiente PHP web e PHP CLI.

Errori nel wp-config.php

WP-CLI deve poter interpretare correttamente wp-config.php.

Configurazioni che dipendono rigidamente da variabili server disponibili soltanto durante una richiesta HTTP possono creare problemi nel contesto della CLI.

La documentazione ufficiale segnala esplicitamente questo tipo di incompatibilità.

Questo spiega un principio più generale:

un sito che funziona nel browser non garantisce automaticamente che il suo bootstrap sia compatibile con un’esecuzione da riga di comando.

Capire se il problema è WP-CLI o WordPress

Un buon percorso diagnostico è:

wp --info
↓
directory/percorso
↓
wp-config.php
↓
PHP CLI
↓
comando con --skip-plugins
↓
comando con --skip-themes
↓
--debug
↓
riproduzione in ambiente pulito

Se il problema scompare quando escludi un’estensione, probabilmente non stai osservando un bug del core WP-CLI.

Se compare anche su una nuova installazione minimale, invece, hai un’indicazione molto più forte che il problema vada indagato a livello di ambiente o strumento.

Automatizzare WordPress con WP-CLI

Fin qui abbiamo usato WP-CLI come sostituto rapido della dashboard.

Il suo vero potenziale emerge quando un comando diventa una procedura ripetibile.

Immagina di voler controllare aggiornamenti, esportare il database e poi aggiornare i plugin.

Manualmente:

wp core check-update
wp plugin list --update=available
wp db export pre-update.sql
wp plugin update --all

Queste istruzioni possono diventare parte di uno script che aggiunge condizioni, logging e controlli.

A quel punto WP-CLI non è più semplicemente “WordPress da terminale”. Diventa uno dei componenti della tua infrastruttura operativa.

Output leggibile da script

Molti comandi possono restituire output in formati strutturati.

Per esempio:

wp plugin list --format=json

oppure:

wp cron event list --fields=hook,next_run --format=json

Questo consente a uno script di elaborare i dati senza dover interpretare una tabella pensata per una persona.

Altri output disponibili, a seconda del comando, possono includere CSV, YAML, count o singoli field.

La conseguenza pratica è importante: lo stesso comando può servire a un operatore umano oppure alimentare un’automazione.

Cron e pipeline di deploy

Il sito ufficiale WP-CLI indica esplicitamente script, cron job e deploy step fra gli scenari di utilizzo.

Un workflow potrebbe, per esempio:

deploy
↓
verifica installazione
↓
aggiornamento database
↓
flush di una cache specifica
↓
controllo finale

Non inserirei però comandi distruttivi in un cron semplicemente perché è possibile farlo.

Più l’operazione è automatica, più diventano importanti:

• idempotenza;
• gestione degli errori;
• exit code;
• log;
• rollback;
• credenziali;
• ambiente corretto.

Automazione significa ridurre il lavoro ripetitivo, non rimuovere i controlli.

Alias e gestione remota

WP-CLI può anche eseguire comandi contro installazioni remote.

La documentazione ufficiale sulla gestione remota permette di utilizzare SSH direttamente oppure definire alias in wp-cli.yml o config.yml.

Un alias può trasformare una destinazione complessa in un nome leggibile.

Dopo aver configurato un ambiente chiamato @production, puoi avere comandi come:

wp @production plugin list

e, per un’altra installazione:

wp @staging plugin list

Il vantaggio è evidente, ma anche il rischio.

Quando i nomi diventano semplici, è ancora più importante distinguere visivamente produzione e staging e costruire protezioni contro l’esecuzione accidentale sul target sbagliato.

Estendere WP-CLI oltre i comandi standard

WP-CLI non è limitato alla command reference installata di default.

Può essere esteso tramite package e comandi personalizzati.

WP-CLI Packages

I package possono aggiungere comandi o modificare il comportamento di WP-CLI.

Prima di installarne uno valuta però:

• manutenzione;
• provenienza;
• compatibilità;
• codice eseguito;
• reale necessità.

Un package viene eseguito all’interno di un contesto amministrativo potente. La valutazione della sorgente è quindi più importante di quanto sarebbe per un semplice tool locale privo di accesso al sito.

Creare un comando personalizzato

Se gestisci un plugin o una piattaforma WordPress con procedure specifiche, puoi esporle come comando WP-CLI.

Concettualmente potresti arrivare a:

wp myproject sync-products

invece di dover costruire ogni volta uno script PHP isolato.

Questo ha senso quando una procedura:

• appartiene davvero all’applicazione;
• deve essere eseguita più volte;
• necessita del contesto WordPress;
• deve poter restituire errori e output prevedibili.

Per una singola operazione occasionale, un comando custom sarebbe probabilmente sovraingegnerizzazione.

WP-CLI, REST API, MCP e AI Agent: strumenti diversi per problemi diversi

Con la crescita delle automazioni e degli agenti AI è facile mettere nello stesso contenitore qualsiasi sistema capace di “controllare WordPress”.

In realtà WP-CLI, REST API e MCP risolvono problemi differenti.

WP-CLI: esecuzione esplicita e deterministica

Quando scrivi:

wp plugin deactivate akismet

hai scelto esplicitamente l’azione.

Il comando non deve capire le tue intenzioni: deve eseguire l’istruzione secondo i parametri forniti.

Per questo WP-CLI è molto adatto a:

• script;
• deploy;
• manutenzione;
• procedure definite;
• troubleshooting;
• operazioni amministrative ripetibili.

REST API: interazione applicativa via HTTP

La REST API serve invece a esporre e manipolare risorse attraverso richieste HTTP.

È più naturale quando un’applicazione esterna deve comunicare con WordPress senza disporre di una shell sul server.

Anche la REST API può naturalmente essere utilizzata in modo deterministico. La differenza principale è il tipo di interfaccia e di trasporto, non una contrapposizione fra “automatico” e “manuale”.

MCP: strumenti esposti a client e agenti

Nel nuovo ecosistema WordPress, l’Abilities API consente di definire funzionalità con input, output e controlli di permesso, mentre l’MCP Adapter può esporre determinate ability come strumenti utilizzabili da client compatibili.

Qui compare una distinzione importante.

Con WP-CLI normalmente il comando è già deciso:

operatore/script
→ comando
→ esecuzione

In un workflow agentico può invece esserci:

obiettivo
→ interpretazione
→ scelta dello strumento
→ esecuzione
→ osservazione del risultato
→ eventuale azione successiva

È un modello operativo differente.

Se vuoi approfondire questa parte senza trasformare una guida WP-CLI in un articolo sull’intelligenza artificiale, trovi l’analisi completa in WordPress MCP e AI Agent.

Quale scegliere

Userei WP-CLI quando conosci già l’operazione e vuoi eseguirla in modo diretto, ripetibile e scriptabile.

Userei una REST API quando un’applicazione deve comunicare con WordPress attraverso HTTP e l’operazione è adatta alle risorse esposte.

Utilizzerei MCP e un agente quando il valore sta anche nella capacità del sistema di interpretare un obiettivo, scegliere fra strumenti disponibili e costruire una sequenza di azioni.

Nessuno dei tre approcci elimina automaticamente gli altri.

Anzi, più WordPress diventa programmabile, più aumenta il valore di interfacce prevedibili e ben controllate.

Comandi WP-CLI da tenere a portata di mano

Questa tabella non vuole sostituire la command reference. Serve come promemoria per le operazioni affrontate nella guida.

Obiettivo	Comando
Informazioni sull’ambiente	wp --info
Versione WP-CLI	wp cli version
Aiuto su un comando	wp help <comando>
Versione WordPress	wp core version
Controllare aggiornamenti core	wp core check-update
Aggiornare WordPress	wp core update
Aggiornare il database WordPress	wp core update-db
Verificare checksum core	wp core verify-checksums
Elencare plugin	wp plugin list
Aggiornare plugin	wp plugin update <plugin>
Aggiornare tutti i plugin	wp plugin update --all
Disattivare un plugin	wp plugin deactivate <plugin>
Elencare temi	wp theme list
Aggiornare i temi	wp theme update --all
Esportare database	wp db export backup.sql
Importare database	wp db import backup.sql
Controllare database	wp db check
Simulare search-replace	wp search-replace <old> <new> --dry-run
Elencare utenti	wp user list
Elencare eventi cron	wp cron event list
Eseguire cron dovuti	wp cron event run --due-now
Svuotare Object Cache	wp cache flush
Rigenerare miniature	wp media regenerate --yes
Ignorare plugin nel bootstrap	--skip-plugins
Ignorare tema nel bootstrap	--skip-themes
Specificare installazione	--path=<percorso>
Debug dettagliato	--debug

Prima di usare un comando che non conosci:

wp help nome-comando

oppure consulta la command reference.

È una piccola abitudine che evita molti errori derivati da esempi vecchi, opzioni ricordate male o comportamenti cambiati nel tempo.

Conclusione

WP-CLI diventa realmente utile quando smetti di considerarlo una scorciatoia per utenti avanzati e inizi a vederlo per quello che è: un’interfaccia programmabile verso WordPress.

Per modificare un singolo plugin una volta all’anno, la dashboard può essere più semplice. Quando invece devi aggiornare componenti, diagnosticare errori, lavorare sul database, migrare installazioni, controllare cron, gestire più ambienti o trasformare una procedura in automazione, il terminale offre un vantaggio difficile da ottenere con una sequenza di clic.

Il passaggio più importante non è imparare più comandi. È costruire un metodo:

capire il target
→ controllare lo stato
→ proteggere i dati
→ eseguire
→ verificare
→ automatizzare solo ciò che è già sotto controllo

È anche il limite da ricordare. WP-CLI può rendere un’operazione molto veloce, compresa un’operazione sbagliata.

Backup, staging, privilegi corretti, --dry-run quando disponibile e verifica del contesto devono quindi restare parte del workflow.

Se invece il problema non è il singolo comando ma la gestione tecnica continuativa del sito — aggiornamenti, errori, migrazioni, sicurezza o manutenzione — può avere più senso intervenire sul processo complessivo con un servizio di assistenza WordPress piuttosto che risolvere ogni problema separatamente.