12 min. leggere

WP-CLI: la guida completa per gestire WordPress dalla riga di comando

WP-CLI è lo strumento ufficiale a riga di comando per gestire le installazioni di WordPress direttamente dal tuo terminale, senza mai aprire un browser. Se hai mai passato un pomeriggio a cliccare sulla dashboard di amministrazione di WordPress per aggiornare i plugin su più siti, sai già perché esiste questo strumento.

In questa guida imparerai tutto, dall’installazione di WP-CLI su Linux, macOS e Windows all’automazione di complesse attività di manutenzione con script e file di configurazione. Che tu stia gestendo un singolo blog o decine di siti di clienti, padroneggiare WP-CLI cambierà radicalmente il tuo modo di lavorare con WordPress.

Cosa imparerai:

Come installare e configurare WP-CLI su diversi sistemi operativi
Comandi essenziali per gestire plugin, temi, utenti e contenuti
Operazioni di database, tra cui esportazione, importazione e ricerca-sostituzione sicura.
Tecniche di automazione con l’uso di script, alias e cron job
Le migliori pratiche per evitare le insidie più comuni quando si lavora dal terminale

Cos’è WP-CLI? (Prima una rapida spiegazione)

WP-CLI è l’acronimo di WordPress Command Line Interface, uno strumento open-source che ti permette di gestire i siti WordPress interamente dal terminale. Invece di accedere a wp-admin e navigare attraverso i menu, puoi eseguire comandi come wp plugin update --all e vedere l’intero stack di plugin aggiornarsi in pochi secondi.

Il progetto è nato intorno al 2011, creato da sviluppatori che volevano un modo più veloce per gestire WordPress su scala. Nel 2017 è passato sotto l’ombrello ufficiale di WordPress.org ed è ora gestito da un team dedicato di collaboratori tra cui Alain Schlesser e Daniel Bachhuber.

Ecco cosa devi sapere su WP-CLI:

Versione stabile attuale: WP-CLI serie 2.x
Compatibilità con WordPress: Funziona con WordPress dalla versione 5.x alla 6.x (e storicamente fino alla 3.7).
Requisiti PHP: PHP 7.4+ o 8.x consigliato per la sicurezza e le prestazioni.
Ecosistema di comandi: Oltre 40 comandi principali che coprono praticamente tutte le operazioni di WordPress
Utenti principali: Sviluppatori, agenzie, ingegneri DevOps e power user che gestiscono siti complessi o multipli.
Distribuzione: Disponibile come file PHAR, attraverso i gestori di pacchetti o preinstallato su molti host WordPress gestiti.

I vantaggi principali dell’utilizzo di WP-CLI

Una volta compreso il motivo dell’esistenza di WP-CLI, la curva di apprendimento diventa molto più facile da giustificare. Questa sezione spiega i vantaggi concreti che rendono questo strumento degno del tuo tempo.

Risparmio di tempo sulle attività ripetitive
Aggiornare 20 plugin attraverso la dashboard di WordPress significa caricare 20 pagine, fare 20 clic e guardare 20 barre di avanzamento. Con WP-CLI, esegui wp plugin update --all una volta e vai avanti. Per le agenzie che gestiscono più siti di clienti, questa differenza si traduce in ore risparmiate ogni settimana.

Operazioni massive e automatizzate
Considera uno scenario in cui stai preparando 15 negozi WooCommerce per il Black Friday. Devi aggiornare i plugin, svuotare le cache e verificare l’integrità del database su ogni sito. WP-CLI ti permette di programmare l’intera sequenza e di eseguirla su tutti i siti in pochi minuti anziché in ore. Le principali funzionalità di automazione includono:

Aggiornare tutti i plugin di più installazioni con un solo script
Creazione di utenti in blocco con ruoli predefiniti
Esecuzione della manutenzione notturna tramite cron (ottimizzazione del database, pulizia transitoria)
Distribuire configurazioni identiche di WordPress in nuovi ambienti

Affidabilità delle operazioni via browser
Le operazioni via browser subiscono timeout HTTP. Le importazioni di database di grandi dimensioni falliscono a metà processo. Le operazioni di ricerca-sostituzione corrompono i dati serializzati se eseguite con SQL grezzo. WP-CLI evita tutti questi problemi perché viene eseguito direttamente sul server senza vincoli di timeout e il suo comando di ricerca-sostituzione gestisce correttamente le strutture di dati serializzati.

Controllo diretto dei sistemi principali di WordPress
Da un unico terminale, puoi:

Esportazione e importazione del database di WordPress
Modifica le impostazioni di wp-config.php
Ispezionare e attivare gli eventi wp-cron
Attiva e disattiva la modalità di manutenzione
Eseguire codice PHP arbitrario nel contesto di WordPress

Riduzione del carico su wp-admin
Sui server di produzione affollati, ogni caricamento della pagina della dashboard di amministrazione consuma risorse. Eseguire le operazioni di manutenzione tramite WP-CLI consente di ridurre il carico sul server web, il che è importante nei periodi di traffico elevato.

Requisiti di WP-CLI e ambienti supportati

Prima di installare WP-CLI, devi verificare che il tuo server o ambiente locale soddisfi i requisiti di base. La buona notizia è che la maggior parte delle moderne configurazioni di WordPress soddisfano già i requisiti.

Requisiti della versione PHP:

Minimo: PHP 5.6 (anche se è obsoleto)
Consigliato: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 o 8.5 per la sicurezza e le prestazioni nel 2026

Compatibilità con la versione di WordPress:

Supporto storico: WordPress 3.7 e versioni successive
Obiettivo moderno: WordPress da 5.0 a 6.7+ per i progetti attuali

Aspettative del sistema operativo:

Il miglior supporto: Sistemi UNIX-like (Ubuntu 22.04 LTS, Debian 12, CentOS Stream, macOS)
Windows: Supportato tramite WSL (Windows Subsystem for Linux) o installazione nativa di PHP.

Requisiti aggiuntivi:

PHP disponibile a linea di comando (il binario php deve essere presente nel tuo PATH)
cURL o wget per scaricare il file wp-cli.phar
Accesso SSH per i server remoti (la maggior parte dei piani di hosting WordPress gestiti lo include di default)

Molti host popolari come Kinsta, SiteGround e DreamHost hanno già preinstallato WP-CLI. Anche WordPress.com include WP-CLI per i siti con accesso SSH abilitato.

Come installare WP-CLI su Linux e macOS

Il metodo di installazione standard utilizza il file ufficiale PHAR (PHP Archive). Questo processo funziona sui terminali Ubuntu, Debian, CentOS, Fedora e macOS.

Passo 1: Scaricare il file PHAR
Apri il tuo terminale e scarica wp-cli.phar usando curl:

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

In alternativa, usa wget:

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

Passo 2: Verifica il download (facoltativo ma consigliato)
Controlla il checksum SHA-256 rispetto al valore ufficiale pubblicato nella documentazione di WP-CLI per assicurarti che il file non sia stato manomesso durante il download:

sha256sum wp-cli.phar

Confronta l’output con il checksum elencato sul sito ufficiale di WP-CLI.

Passo 3: Verifica il file PHAR
Verifica che il file php funzioni:

php wp-cli.phar --info

Dovresti vedere l’output che mostra la versione di WP-CLI, la versione di PHP e le informazioni sul sistema.

Passo 4: Rendilo eseguibile e spostalo nel PATH
Contrassegna il file come eseguibile e spostalo in una directory del PATH del tuo sistema:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Il comando sudo è in genere necessario perché /usr/local/bin è una directory di sistema. Evita di installare WP-CLI come root se lo eseguirai principalmente come utente normale.

Passo 5: Verifica l’installazione globale
Conferma che WP-CLI è ora disponibile a livello globale:

wp --info
wp cli version

Dovresti vedere l’output che conferma la versione di wp cli, la posizione del binario PHP e i dettagli del sistema operativo. A questo punto, WP-CLI è installato e pronto all’uso.

Come installare WP-CLI su Windows

Gli utenti di Windows hanno due strade principali: utilizzare Windows Subsystem for Linux (WSL) o creare un’installazione nativa di Windows. WSL offre un’esperienza più simile a quella di Linux ed è generalmente consigliato.

Opzione 1: Utilizzo di WSL (consigliato)
Per prima cosa, attiva WSL su Windows 10 o 11:

wsl --install

Installa Ubuntu dal Microsoft Store, quindi avvia il terminale di Ubuntu. Da qui, segui gli stessi identici passi per l’installazione di Linux descritti nella sezione precedente: scarica il file phar, rendilo eseguibile e spostalo su /usr/local/bin/wp.

Opzione 2: Installazione nativa per Windows
Per un’installazione nativa, è necessario che PHP per Windows sia installato con l’eseguibile php disponibile nel PATH del sistema.

Scarica e installa PHP dal sito ufficiale di PHP per Windows
Aggiungi la directory PHP alla variabile d’ambiente PATH di Windows
Conferma il funzionamento di PHP aprendo il Prompt dei comandi ed eseguendo php -v

Successivamente, scarica il file WP-CLI PHAR:

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

Windows include curl di default dal 2018, quindi dovrebbe funzionare senza ulteriori configurazioni. Crea una cartella per WP-CLI (ad esempio, C:\wp-cli) e sposta lì il file scaricato.

Quindi crea un file batch wrapper chiamato wp.bat nella stessa cartella:

@echo off
php "C:\wp-cli\wp-cli.phar" %*

Aggiungi C:\wp-cli alla variabile d’ambiente PATH del tuo sistema. Ora apri una nuova finestra del Prompt dei comandi o di PowerShell e verifica:

wp --info

Dovresti vedere la versione di WP-CLI e i dettagli dell’ambiente che confermano che WP-CLI è stato installato correttamente.

Utilizzo di base di WP-CLI e aiuto

Con WP-CLI installato, devi comprendere lo schema dei comandi di base prima di immergerti in operazioni specifiche. Tutti i comandi di WP-CLI seguono questa struttura:

wp <command> <subcommand> [options]

I comandi vengono eseguiti all’interno della cartella di installazione di WordPress – la cartella che contiene wp-config.php. Se ti trovi altrove, puoi specificare il percorso con --path=/var/www/html/mysite.

Controllare l’ambiente
Inizia confermando la tua configurazione:

wp --info

Questo mostra la versione di WP-CLI, la versione di PHP, il percorso binario di PHP, il sistema operativo e altri dettagli dell’ambiente. Per vedere solo la versione di WP-CLI:

wp cli version

Esplorare i comandi disponibili
Per elencare tutti i comandi wp cli disponibili:

wp help

Per ottenere aiuto su un comando specifico:

wp help plugin
wp help core update

Puoi anche aggiungere --help a qualsiasi comando:

wp user --help

L’output della guida viene visualizzato in un pager simile alle pagine man di Unix. Premi q per uscire.

I primi comandi da provare:

wp core version – visualizza la versione di WordPress
wp plugin list – mostra tutti i plugin di WordPress installati con il loro stato
wp theme list – mostra i temi installati
wp user list – elenca tutti gli utenti del sito

Questi comandi di sola lettura ti permettono di esplorare il tuo sito WordPress senza modificare nulla, il che è perfetto per prendere confidenza con l’interfaccia.

Installare e configurare WordPress con WP-CLI

WP-CLI può eseguire un’installazione completa di WordPress in modo più rapido rispetto al tradizionale programma di installazione basato sul web. Questo è particolarmente utile per creare ambienti di sviluppo o per distribuire nuovi siti in modo programmatico.

Prerequisiti
Prima di eseguire i comandi di installazione, devi avere un database MySQL o MariaDB pronto. Per questo esempio, supponiamo che tu abbia creato:

Nome del database: wpsite_db
Utente del database: wpsite_user
Password: securepassword123
Ospite: localhost

Passo 1: Scaricare i file del nucleo di WordPress
Vai nella directory di installazione desiderata e scarica il nucleo di WordPress:

wp core download

Questo recupera l’ultima versione di WordPress. Per specificare una versione o un locale:

wp core download --version=6.4.2 --locale=fr_FR

Al termine, vedrai la conferma che WordPress è stato scaricato con successo.

Passo 2: Generare wp-config.php
Crea il file di configurazione utilizzando wp config create:

wp config create --dbname=wpsite_db --dbuser=wpsite_user --dbpass=securepassword123 --dbhost=localhost

Questo genera un wp-config.php completo con le credenziali del tuo database e i sali di sicurezza generati automaticamente.

Passo 3: Esegui l’installazione
Ora installa WordPress con i dati del tuo sito:

wp core install --url=https://example.com --title="My New Site" --admin_user=admin --admin_password=strongpassword [email protected]

Vedrai il messaggio “WordPress installato con successo” e il tuo sito sarà pronto per essere utilizzato.

Installazione multisito
Per le reti WordPress multisito, utilizza la variante multisito. WP-CLI può configurare installazioni multisito con:

wp core multisite-install --url=https://example.com --title="My Network" --admin_user=admin --admin_password=strongpassword [email protected]

Gestione dei temi con WP-CLI

WP-CLI gestisce tutte le operazioni sui temi senza richiedere l’accesso alla dashboard di amministrazione di WordPress. Puoi elencare, installare, attivare, aggiornare e cancellare i temi direttamente dal tuo terminale.

Elenco dei temi installati
Per vedere tutti i temi attualmente installati:

wp theme list

Esempio di uscita:

nome	stato	aggiornamento	versione
ventiquattro	attivo	none	1.0
ventiquattrore	inattivo	none	1.2
astra	inattivo	disponibile	4.5.0

Attivare un tema
Passa a un tema diverso:

wp theme activate astra

Questo cambia immediatamente il tema attivo. Il ritorno al tema predefinito è utile per risolvere i problemi legati ai temi:

wp theme activate twentytwentyfour

Installare nuovi temi
Installa un tema dal repository di WordPress.org:

wp theme install astra

Installa e attiva con un solo comando:

wp theme install astra --activate

Aggiornare i temi
Aggiorna un tema specifico:

wp theme update astra

Oppure aggiorna tutti i temi in una volta sola:

wp theme update --all

Eliminare i temi
Rimuovi un tema che non ti serve più:

wp theme delete twentytwentythree

Gestione dei plugin con WP-CLI

La gestione dei plugin è l’ambito in cui WP-CLI fa risparmiare più tempo. Puoi eseguire operazioni in blocco che richiederebbero decine di clic nella dashboard.

Elenco dei plugin

wp plugin list

Esempio di uscita:

nome	stato	aggiornamento	versione
woocommerce	attivo	none	8.5.1
yoast-seo	attivo	disponibile	21.0
elemento	inattivo	none	3.18.0

Installare i plugin
Installa un plugin in base al suo slug:

wp plugin install woocommerce

Installa e attiva:

wp plugin install yoast-seo --activate

Attivare e disattivare
Attivare un plugin:

wp plugin activate elementor

Disattiva un plugin (utile per il debug):

wp plugin deactivate elementor

Disattiva tutti i plugin in una volta sola (salvavita per il debug della “White Screen of Death”):

wp plugin deactivate --all

Aggiornare i plugin
Aggiorna un plugin specifico:

wp plugin update yoast-seo

Aggiorna tutti i plugin:

wp plugin update --all

Puoi anche escludere determinati plugin da un aggiornamento massivo:

wp plugin update --all --exclude=woocommerce

Aggiornare e riparare il nucleo di WordPress

Mantenere WordPress aggiornato è fondamentale per la sicurezza. WP-CLI rende questo processo trasparente e controllabile.

Controllo degli aggiornamenti

wp core check-update

Aggiornamento di WordPress
Aggiorna all’ultima versione:

wp core update

Dopo un aggiornamento del core, è buona norma aggiornare lo schema del database:

wp core update-db

Verificare le checksum
Se sospetti che il tuo sito sia stato violato, puoi verificare che i file principali non siano stati modificati:

wp core verify-checksums

Questo confronta i tuoi file con le checksum del repository ufficiale di WordPress.

Reinstallare il Core
Se i file sono danneggiati, puoi forzare una reinstallazione senza compromettere i tuoi contenuti:

wp core download --force --skip-content

Gestione di contenuti, utenti e database

WP-CLI ti permette di interagire direttamente con i dati del tuo sito.

Gestione utenti
Elenca gli utenti:

wp user list

Crea un nuovo amministratore:

wp user create newadmin [email protected] --role=administrator --user_pass=securepass123

Aggiorna la password di un utente:

wp user update 1 --user_pass=newpassword

Elimina un utente e riassegna i suoi contenuti:

wp user delete 5 --reassign=1

Operazioni sul database
Esporta il database in un file:

wp db export backup.sql

Importa un database da un file:

wp db import backup.sql

Ottimizza il database:

wp db optimize

Apri una console MySQL direttamente collegata al tuo database WordPress:

wp db cli

Cerca e sostituisci (nel modo giusto)

Spostare manualmente un sito WordPress su un nuovo dominio è rischioso perché i dati sono spesso serializzati nel database. Un semplice “trova-e-sostituisci” in SQL potrebbe danneggiare i widget e le opzioni del tema. WP-CLI gestisce correttamente la serializzazione.

Ricerca-Sostituzione standard

wp search-replace 'http://old-domain.com' 'https://new-domain.com'

Esecuzione a secco (anteprima)
Controlla sempre cosa cambierà prima di eseguire il comando:

wp search-replace 'http://old-domain.com' 'https://new-domain.com' --dry-run

Esportazione con sostituzione
Puoi esportare un database con le sostituzioni effettuate nel file, lasciando inalterato il database attivo:

wp search-replace 'old.com' 'new.com' --export=migrated-db.sql

Manutenzione avanzata: Cron e Object Cache

Gestione dei Cron Jobs
Visualizza gli eventi programmati:

wp cron event list

Esegui immediatamente tutti gli eventi cron dovuti:

wp cron event run --due-now

Gestione dei transitori e della cache
Cancella la cache degli oggetti:

wp cache flush

Elimina tutti i transitori scaduti:

wp transient delete --expired

Automatizzare le attività con gli script

Puoi combinare i comandi WP-CLI in script Bash per la manutenzione automatica.

Esempio: Script di manutenzione settimanale
Crea un file chiamato maintain.sh:

#!/bin/bash
# Update everything
wp core update
wp core update-db
wp plugin update --all
wp theme update --all

# Cleanup
wp transient delete --expired
wp cache flush
wp db optimize

echo "Maintenance complete."

Rendilo eseguibile (chmod +x maintain.sh) ed eseguilo per eseguire la manutenzione completa del sito in pochi secondi.

Utilizzare WP-CLI da remoto tramite SSH

Non è necessario accedere al server per eseguire i comandi se si configurano gli alias.

Nel tuo file locale wp-cli.yml:

@prod:
  ssh: [email protected]/var/www/html
@dev:
  ssh: [email protected]/var/www/html

Ora puoi eseguire i comandi sul server remoto dal tuo computer locale:

wp @prod plugin list
wp @dev core version

Migliori pratiche

Esegui sempre il backup: Prima di eseguire aggiornamenti in blocco o comandi di ricerca-sostituzione, esegui wp db export.
Usa il Dry Run: Per la ricerca-sostituzione, usa sempre prima --dry-run.
Non eseguire come root: WP-CLI ti avverte se esegui come root. È più sicuro eseguirlo come utente del server web (ad esempio, www-data) o come account utente specifico.
Test su Staging: Utilizza WP-CLI per clonare il tuo sito di produzione su quello di staging, per testare gli script di aggiornamento e poi applicarli alla produzione.

Conclusione

WP-CLI trasforma la gestione di WordPress da una serie di clic in operazioni semplificate e scriptabili. Iniziando con comandi semplici come il controllo delle versioni e l’elenco dei plugin, si gettano le basi per un’automazione avanzata. Integrare WP-CLI nel tuo flusso di lavoro oggi stesso ti farà risparmiare innumerevoli ore nei tuoi progetti WordPress.