Che cos’è WP-CLI
WP-CLI, acronimo di WordPress Command-Line Interface, è l’interfaccia a riga di comando utilizzata per amministrare WordPress senza passare dal pannello di controllo del CMS.
In pratica, molte operazioni normalmente eseguite tramite browser possono essere effettuate direttamente dal terminale utilizzando comandi testuali.
Si possono controllare e aggiornare WordPress, installare plugin e temi, gestire gli utenti, esportare il database, effettuare sostituzioni al suo interno e svolgere numerose attività di manutenzione.
WP-CLI risulta particolarmente utile quando si lavora via SSH su un server oppure quando occorre eseguire la stessa operazione su più installazioni. Per vedere un caso concreto, è disponibile anche la guida dedicata a come installare WordPress con WP-CLI, nella quale l’intera installazione viene eseguita dal terminale.
Non sostituisce necessariamente il pannello di amministrazione. È semplicemente un modo diverso, e spesso più pratico, per eseguire operazioni amministrative e tecniche.
Come funziona la riga di comando di WordPress
Una interfaccia a riga di comando permette di comunicare con un sistema attraverso istruzioni testuali anziché utilizzando finestre, pulsanti e menu.
WP-CLI applica questo principio a WordPress.
La struttura di base di un comando è piuttosto semplice:
wp comando sottocomando [parametri]
Ad esempio:
wp plugin list
‘wp’ richiama WP-CLI, ‘plugin’ indica l’area sulla quale si vuole lavorare e ‘list’ specifica l’operazione da eseguire.
Un altro esempio è:
wp plugin update --all
In questo caso viene richiesto l’aggiornamento di tutti i plugin per i quali è disponibile una nuova versione.
Requisiti per utilizzare WP-CLI
La documentazione ufficiale WP-CLI indica attualmente come requisito PHP 7.2.24 o successivo. WP-CLI non impone ulteriori requisiti oltre a quelli richiesti da WordPress.
Prima dell’installazione si può quindi verificare la versione di PHP disponibile:
php --version
Su molti servizi hosting WP-CLI è già disponibile e non occorre installarlo manualmente.
Sui piani Hosting WordPress di VHosting è quindi opportuno verificare prima la disponibilità del comando dal terminale:
wp --info
Se il comando restituisce le informazioni sull’ambiente WP-CLI, non serve procedere con una nuova installazione.
Come installare WP-CLI
Quando WP-CLI non è già disponibile sul sistema, la documentazione ufficiale raccomanda l’installazione attraverso il file Phar.
Il download può essere effettuato con:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
Prima di installarlo si verifica che il file possa essere eseguito:
php wp-cli.phar --info
Successivamente si rende eseguibile il file:
chmod +x wp-cli.phar
Su un sistema nel quale si dispone dei privilegi necessari, lo si può spostare in una directory presente nel ‘PATH’:
sudo mv wp-cli.phar /usr/local/bin/wp
A questo punto si verifica l’installazione:
wp --info
Il comando mostra informazioni relative a WP-CLI, PHP e all’ambiente nel quale viene eseguito.
La procedura di installazione e i requisiti aggiornati sono disponibili nella documentazione ufficiale WP-CLI.
Posizionarsi nella directory di WordPress
Un passaggio semplice ma importante consiste nel posizionarsi nella directory che contiene l’installazione WordPress.
Ad esempio:
cd /percorso/del/sito
Da questa directory si possono eseguire i comandi WP-CLI.
Se non si vuole cambiare directory, molti comandi accettano anche il parametro globale ‘–path’:
wp core version --path=/percorso/del/sito
Il percorso reale dipende dalla configurazione dell’hosting e non va quindi dato per scontato.
Quando si lavora direttamente dalla shell, gli stessi strumenti possono essere utilizzati anche per operazioni più articolate. Un esempio pratico è la migrazione di WordPress tramite SSH, durante la quale si interviene direttamente su file e database senza dipendere dal pannello di amministrazione.
Come ottenere aiuto sui comandi WP-CLI
WP-CLI dispone di un sistema di help integrato.
Per visualizzare i comandi disponibili:
wp help
Per ottenere informazioni su un comando specifico si può indicarne il nome:
wp help plugin
oppure:
wp help search-replace
È un sistema utile soprattutto quando non si ricorda esattamente un parametro.
Controllare la versione di WP-CLI e WordPress
Per conoscere la versione di WP-CLI installata:
wp --version
Per visualizzare informazioni più complete:
wp --info
Per conoscere invece la versione del core WordPress presente nell’installazione:
wp core version
Sono operazioni di sola lettura e non modificano il sito.
Controllare se WordPress deve essere aggiornato
Prima di effettuare un aggiornamento si può controllare se ne esiste uno disponibile:
wp core check-update
Per forzare un nuovo controllo ignorando il risultato memorizzato temporaneamente:
wp core check-update --force-check
Per aggiornare WordPress:
wp core update
Dopo un aggiornamento del core può essere necessario eseguire l’aggiornamento del database previsto da WordPress:
wp core update-db
Prima di aggiornare un sito in produzione è opportuno disporre di un backup recente e verificato. È inoltre utile controllare compatibilità di plugin e tema. Questi aspetti sono trattati più nel dettaglio nella guida dedicata agli aggiornamenti WordPress e alle precauzioni da adottare.
Quando l’aggiornamento riguarda un sito importante, un’altra possibilità consiste nell’effettuare prima le prove in un ambiente separato. WP-CLI può essere impiegato anche nella creazione di un’area di staging WordPress, così da effettuare test senza intervenire immediatamente sul sito pubblico.
Verificare l’integrità dei file di WordPress
Uno dei comandi più interessanti per la diagnostica è:
wp core verify-checksums
WP-CLI confronta i file del core presenti sul server con i checksum forniti da WordPress.org per la versione installata.
Il controllo viene eseguito prima del caricamento di WordPress. Questo lo rende utile anche durante alcune attività di diagnostica.
Un risultato positivo indica che i file controllati corrispondono ai checksum previsti. Una mancata corrispondenza richiede invece un’analisi: non significa automaticamente che il sito sia compromesso, perché occorre capire quali file risultano differenti e perché.
Questo controllo può essere utilizzato anche durante l’analisi di un sito sospetto. Nella guida su come verificare un sito WordPress potenzialmente infetto da malware vengono mostrati altri controlli eseguibili tramite WP-CLI.
Gestire i plugin con WP-CLI
Per visualizzare i plugin installati:
wp plugin list
Per installare un plugin presente nel repository WordPress.org si utilizza il suo slug.
Ad esempio, per Contact Form 7:
wp plugin install contact-form-7
Per installarlo e attivarlo direttamente:
wp plugin install contact-form-7 --activate
Se il plugin è già installato:
wp plugin activate contact-form-7
Per disattivarlo:
wp plugin deactivate contact-form-7
Per aggiornarlo:
wp plugin update contact-form-7
Per aggiornare tutti i plugin:
wp plugin update --all
Per eliminare un plugin:
wp plugin delete contact-form-7
Quest’ultimo comando modifica il filesystem. Prima di utilizzarlo va quindi verificato con attenzione il nome del plugin.
Verificare i checksum dei plugin
WP-CLI dispone anche di un controllo dei checksum per i plugin ospitati su WordPress.org.
Per verificare tutti quelli supportati:
wp plugin verify-checksums --all
Per controllarne uno solo:
wp plugin verify-checksums akismet
Il comando confronta i file installati con i checksum forniti da WordPress.org.
Non tutti i plugin possono necessariamente essere verificati in questo modo. In particolare, un plugin distribuito esternamente al repository WordPress.org potrebbe non disporre dei checksum necessari.
Gestire i temi
La logica utilizzata per i plugin si applica anche ai temi.
Per visualizzare quelli installati:
wp theme list
Per installare un tema dal repository WordPress.org:
wp theme install twentytwentyfive
Per attivarlo:
wp theme activate twentytwentyfive
Per aggiornare un singolo tema:
wp theme update twentytwentyfive
Per aggiornare tutti i temi:
wp theme update --all
Esportare il database
Prima di operazioni importanti sul database è buona pratica crearne una copia.
WP-CLI permette di esportarlo con:
wp db export
È possibile indicare esplicitamente il nome del file:
wp db export backup.sql
Il file SQL contiene l’esportazione del database utilizzato dall’installazione WordPress.
Importare un database
WP-CLI può effettuare anche l’operazione inversa:
wp db import backup.sql
Attenzione: l’importazione modifica il database. Il comando deve quindi essere utilizzato solo quando si conosce esattamente il contenuto del file SQL e si dispone di un backup adeguato.
Cercare e sostituire valori nel database
‘wp search-replace’ è particolarmente utile durante una migrazione WordPress.
Un caso tipico è la sostituzione del vecchio dominio con quello nuovo.
Prima di modificare realmente il database conviene utilizzare ‘–dry-run’:
wp search-replace 'https://vecchio.example' 'https://nuovo.example' --dry-run
In questa modalità WP-CLI esegue la ricerca e mostra cosa verrebbe sostituito, ma non salva le modifiche.
Dopo aver controllato il risultato si può eseguire l’operazione reale:
wp search-replace 'https://vecchio.example' 'https://nuovo.example'
Il comando è progettato per gestire anche i dati PHP serializzati, presenti frequentemente nel database di WordPress.
Questo aspetto è importante. Una semplice sostituzione testuale eseguita direttamente su un dump SQL può danneggiare dati serializzati quando cambia la lunghezza delle stringhe.
Prima di un ‘search-replace’ reale è quindi consigliabile esportare il database e provare sempre prima l’operazione con ‘–dry-run’.
La sintassi completa è riportata nella documentazione ufficiale di wp search-replace.
Visualizzare gli utenti WordPress
Per ottenere l’elenco degli utenti:
wp user list
WP-CLI consente anche di creare, modificare ed eliminare utenti. Queste operazioni richiedono maggiore attenzione perché intervengono direttamente sugli account del sito.
Per verificare i parametri disponibili prima di procedere:
wp help user
Visualizzare gli articoli
Per ottenere l’elenco dei contenuti di WordPress si può utilizzare:
wp post list
Il comando può essere filtrato. Ad esempio, per visualizzare i post pubblicati:
wp post list --post_type=post --post_status=publish
Questo permette di ottenere rapidamente informazioni sui contenuti anche quando non è possibile o conveniente utilizzare il pannello di amministrazione.
Leggere le opzioni di WordPress
WP-CLI permette di interrogare la tabella delle opzioni attraverso il comando ‘wp option’.
Ad esempio:
wp option get siteurl
oppure:
wp option get home
Questi due comandi risultano utili durante la diagnosi di problemi relativi all’URL configurato per WordPress.
Per visualizzare tutte le possibilità:
wp help option
Usare WP-CLI quando WordPress genera un errore
Uno dei vantaggi pratici della riga di comando emerge quando il backend di WordPress non è accessibile.
Se si sospetta che il problema dipenda da un plugin, WP-CLI permette ad esempio di controllare quelli installati:
wp plugin list
e disattivare uno specifico plugin:
wp plugin deactivate nome-plugin
È possibile anche eseguire alcuni comandi evitando il caricamento dei plugin:
wp core version --skip-plugins
Oppure saltando plugin e tema:
wp core version --skip-plugins --skip-themes
Questi parametri sono utili in fase diagnostica quando un’estensione interferisce con il normale caricamento di WordPress.
Quando occorre individuare la causa di un problema PHP o di un comportamento anomalo, WP-CLI può essere affiancato agli strumenti di diagnostica del CMS. La procedura per registrare errori e warning è descritta nella guida su come attivare il debug su WordPress.
Comandi WP-CLI da ricordare
Per un controllo rapido di un’installazione, alcuni comandi risultano particolarmente pratici:
wp --info wp --version wp core version wp core check-update wp core verify-checksums wp plugin list wp plugin verify-checksums --all wp theme list wp user list wp post list wp db export backup.sql
Non tutti modificano il sito. ‘wp core version’, ‘wp plugin list’, ‘wp theme list’ e i comandi di verifica possono essere usati principalmente per raccogliere informazioni.
Comandi come ‘update’, ‘delete’, ‘import’ e ‘search-replace’ intervengono invece sull’installazione e vanno utilizzati sapendo esattamente quale sarà l’effetto.
Dove trovare tutti i comandi WP-CLI
La documentazione completa e aggiornata dei comandi si trova nel manuale ufficiale WP-CLI su Developer.WordPress.org.
È il riferimento da utilizzare quando occorre verificare la sintassi, i parametri disponibili e il comportamento di un comando.
Nella pratica WP-CLI si incontra soprattutto lavorando via SSH o tramite il terminale messo a disposizione dal pannello hosting. Permette di controllare rapidamente una versione di WordPress, verificare i file del core, aggiornare plugin e temi, esportare il database o intervenire su un sito quando il pannello ‘/wp-admin’ non è raggiungibile. Proprio in questi casi la riga di comando passa dall’essere una semplice alternativa al browser a diventare uno strumento concreto di amministrazione e diagnostica.
