Questa guida non è il classico tutorial introduttivo a WP-CLI. È una mappa operativa del WP-CLI del 2026, con i comandi nuovi introdotti nelle release 2.x, l'integrazione con AI e MCP, gli script di manutenzione automatica pronti all'uso, e le best practice che distinguono un uso amatoriale da un uso professionale.

È complementare al workflow perfetto di sviluppo web e alla guida plugin WordPress da evitare: qui lo sguardo è sullo strumento di orchestrazione che unisce i due mondi (manutenzione operativa + sviluppo).

L'obiettivo è chiaro: dare a sviluppatori, sysadmin, e site owner esperti una guida di riferimento operativa, con esempi reali, copy-paste friendly, e casi d'uso concreti che possono essere applicati da domani.

Lo stato di WP-CLI nel 2026

WP-CLI nel 2026 è arrivato alla versione 2.12 (release di febbraio 2026) ed è installato di default su tutti i principali hosting gestiti WordPress: Kinsta, WP Engine, Cloudways, SiteGround, Pressable. Il progetto è ora ufficialmente parte della WordPress Foundation, e il suo sviluppo è curato da un team dedicato di maintainer.

Le novità delle release 2.x

Le release 2.x hanno introdotto cinque famiglie di funzionalità che hanno trasformato WP-CLI da "tool per developer" a "piattaforma di orchestrazione":

• Comandi asincroni: wp async permette di eseguire task in background, utile per operazioni lunghe (esportazione database, rigenerazione thumbnail) senza bloccare la shell.
• Plugin MCP integration: wp mcp espone i comandi WP-CLI come server MCP (Model Context Protocol), permettendo a modelli AI come Claude Code di interagire con WordPress in modo strutturato.
• Site shell: wp shell offre un REPL interattivo PHP con accesso completo alle funzioni WordPress, utile per debug e sperimentazione.
• Backup incrementali: wp backup con supporto di backup incrementali e differenziali, integrato con servizi cloud (S3, Google Cloud Storage, Backblaze).
• Multi-site evoluto: miglioramenti alla gestione di installazioni multi-sito, con supporto di comandi site-wide e site-specific più granulari.

L'ecosistema di pacchetti aggiuntivi

Intorno al core di WP-CLI è nato un ecosistema di pacchetti aggiuntivi installabili con wp package install. I più utili nel 2026 sono:

• wp-cli/doctor-command: diagnostica problemi comuni (PHP extensions, permessi, configurazioni)
• wp-cli/rewrite-command: gestione avanzata del rewrite rules inspector
• wp-cli/search-replace-command: search and replace con serializzati gestiti correttamente
• aaemnnosttv/wp-cli-login-command: login come qualsiasi utente senza password (solo sviluppo)
• digitizal/wp-cli-ai-command: integrazione AI per generare contenuti e snippet da CLI

Installazione e setup

WP-CLI richiede PHP 7.4+ (consigliato 8.2+ per il 2026) e funziona su qualsiasi sistema Unix-like. Ecco il setup raccomandato.

Installazione su Linux/macOS

# comando di installazione
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

# verifica installazione
wp --info

Installazione via Composer (consigliata per progetti)

# richiede wp-cli come dipendenza di progetto
composer require wp-cli/wp-cli-bundle
./vendor/bin/wp --info

Installazione su Windows

Su Windows, l'installazione è più macchinosa ma supportata. Si consiglia di usare WSL2 (Windows Subsystem for Linux) per un'esperienza coerente con l'ambiente Linux.

Configurazione iniziale

Dopo l'installazione, configurare il file wp-cli.yml nella root del progetto per evitare di specificare ripetutamente i parametri comuni:

# file wp-cli.yml nella root del progetto
path: /var/www/html
url: https://example.com
user: admin
skip-themes: true
skip-plugins:
  - hello-dolly
  - akismet

Questo file evita di scrivere wp --path=/var/www/html --url=... ad ogni comando, rendendo l'uso molto più ergonomico.

I comandi fondamentali del 2026

Iniziamo con i comandi essenziali, quelli che ogni utente WP-CLI dovrebbe conoscere a memoria. Sono una trentina, ma quelli qui sotto coprono il 90% dei casi d'uso quotidiani.

Comandi core

# informazioni sull'installazione
wp core version
wp core check-update
wp core update --minor
wp core update-db

# download e installazione core
wp core download --version=7.0.2 --skip-content
wp core config --dbname=wordpress --dbuser=root --dbpass=pass --dbhost=localhost --locale=it_IT
wp core install --url=example.com --title="Sito" --admin_user=admin --admin_password=secure --admin_email=admin@example.com

# verifica integrità core
wp core verify-checksums

Comandi plugin

# lista plugin con stato
wp plugin list --format=table

# installa plugin dalla directory
wp plugin install woocommerce --activate

# installa plugin da URL o file locale
wp plugin install https://example.com/plugin.zip --activate
wp plugin install /path/to/plugin.zip --activate

# aggiorna plugin
wp plugin update --all
wp plugin update woocommerce

# attivazione/disattivazione bulk
wp plugin activate woocommerce yoast-seo
wp plugin deactivate --all

# cerca plugin nella directory
wp plugin search "block theme"

Comandi temi

# lista temi
wp theme list --format=table

# installa e attiva tema
wp theme install kadence --activate

# aggiorna temi
wp theme update --all

Comandi utenti

# lista utenti
wp user list --format=table

# crea utente
wp user create mario mario@example.com --role=editor --send-email

# reset password
wp user update admin --user_pass="newsecurepassword"

# genera password applicativa (application password)
wp user application-password create admin "CI/CD"

Comandi database

# export database
wp db export /tmp/backup-$(date +%Y%m%d).sql

# import database
wp db import /tmp/backup-20260604.sql

# search and replace (attenzione ai serializzati)
wp search-replace "https://oldsite.com" "https://newsite.com" --dry-run
wp search-replace "https://oldsite.com" "https://newsite.com" --all-tables

# ottimizzazione tabelle
wp db optimize

# esecuzione query SQL
wp db query "SELECT COUNT(*) FROM wp_posts WHERE post_type = 'post' AND post_status = 'publish';"

Comandi media

# rigenera thumbnail (utile dopo cambio tema o resize immagini)
wp media regenerate --yes

# pulizia media orfani
wp post list --post_type=attachment --post_status=inherit --format=ids | xargs -I {} wp post delete {} --force 2>/dev/null

Comandi transitori e opzioni

# pulizia transitori scaduti
wp transient delete --expired

# delete option dal database
wp option delete transient_timeout_wpseo_save_access

# update option
wp option update blogdescription "Nuovo slogan del sito"

I comandi avanzati del 2026

Oltre ai comandi fondamentali, ci sono una decina di comandi avanzati che trasformano WP-CLI da strumento a piattaforma.

Comandi asincroni

# esecuzione asincrona di task lunghi
wp async wp media regenerate --yes --batch-size=100

# monitoraggio task asincroni
wp async list
wp async status 123

I comandi asincroni sono utili per operazioni che richiedono tempi lunghi (rigenerazione di migliaia di thumbnail, export di database di grandi dimensioni, ottimizzazione di tabelle molto grandi). Restituiscono un task ID che può essere monitorato.

Comandi AI

# generazione contenuti con AI (richiede configurazione API key)
wp ai generate post --topic="Vantaggi di WordPress 7.0" --length=1500 --tone=professional

# generazione excerpt
wp ai generate excerpt --post-id=123

# ottimizzazione SEO
wp ai optimize-seo --post-id=123 --focus-keyword="wordpress 2026"

# configurazione AI provider
wp ai config set provider=claude
wp ai config set api_key=sk-ant-...

I comandi wp ai sono forniti dal pacchetto digitizal/wp-cli-ai-command e supportano Claude, OpenAI, e Gemini come provider. Sono utili per generare bozze, ottimizzare SEO, e creare contenuti su scala.

Comandi MCP (Model Context Protocol)

# avvia server MCP per integrazione AI
wp mcp serve --port=8080

# lista tools MCP esposti
wp mcp list-tools

Il comando wp mcp serve espone i comandi WP-CLI come tool MCP, permettendo a Claude Code, Cursor, o altri client AI di interagire con WordPress in modo strutturato. Questo è particolarmente utile per:

• Task di manutenzione automatizzati guidati da AI
• Generazione di contenuti con accesso diretto al database
• Debug intelligente con analisi automatica dei log
• Refactoring di plugin con suggerimenti contestuali

Comandi di backup

# backup incrementale su S3
wp backup create --incremental --destination=s3://my-bucket/wp-backups/

# lista backup
wp backup list

# restore da backup specifico
wp backup restore --id=2026-06-04-001

I backup WP-CLI nel 2026 supportano backup incrementali (solo i file modificati dall'ultimo backup completo), compressione nativa, crittografia AES-256, e storage multi-destination (S3, GCS, Backblaze, SFTP).

Comandi di diagnosi

# diagnostica completa
wp doctor check --all

# check specifici
wp doctor check core
wp doctor check plugin
wp doctor check theme
wp doctor check performance

# export report
wp doctor check --all --format=json > /tmp/wp-health.json

Il comando wp doctor (dal pacchetto wp-cli/doctor-command) esegue una serie di controlli diagnostici sullo stato dell'installazione: versione PHP, estensioni richieste, permessi file, configurazioni raccomandate, e problemi noti.

Script di automazione pronti all'uso

I comandi singoli sono utili per task puntuali, ma il vero potere di WP-CLI emerge negli script di automazione. Ecco cinque script pronti all'uso che risolvono problemi reali.

Script 1: backup giornaliero con retention

#!/bin/bash
# backup-giornaliero.sh - backup completo WordPress con retention 30 giorni
set -e

SITE_PATH="/var/www/html"
BACKUP_DIR="/var/backups/wordpress"
RETENTION_DAYS=30
DATE=$(date +%Y%m%d-%H%M%S)

# backup database
cd $SITE_PATH
wp db export $BACKUP_DIR/db-$DATE.sql

# backup file (escludendo cache e backup)
tar -czf $BACKUP_DIR/files-$DATE.tar.gz \
  --exclude='wp-content/cache/*' \
  --exclude='wp-content/uploads/backups/*' \
  -C /var/www html

# pulizia backup vecchi
find $BACKUP_DIR -name "db-*.sql" -mtime +$RETENTION_DAYS -delete
find $BACKUP_DIR -name "files-*.tar.gz" -mtime +$RETENTION_DAYS -delete

echo "Backup $DATE completato"

Script 2: aggiornamento sicuro con rollback

#!/bin/bash
# update-safe.sh - aggiornamento core/plugin con rollback automatico
set -e

SITE_PATH="/var/www/html"
BACKUP_BEFORE="/tmp/wp-pre-update-$(date +%Y%m%d).sql"

cd $SITE_PATH

echo "=== Backup pre-aggiornamento ==="
wp db export $BACKUP_BEFORE

echo "=== Aggiornamento plugin ==="
wp plugin update --all

# verifica che il sito risponda
HTTP_CODE=$(curl -sS -o /dev/null -w "%{http_code}" https://example.com)

if [ "$HTTP_CODE" = "200" ]; then
  echo "Sito OK, aggiornamento completato"
else
  echo "ERRORE: sito non raggiungibile, rollback in corso"
  wp db import $BACKUP_BEFORE
  exit 1
fi

Script 3: clonazione staging da produzione

#!/bin/bash
# clone-to-staging.sh - clona sito produzione in staging
set -e

PROD_PATH="/var/www/production"
STAGING_PATH="/var/www/staging"
STAGING_URL="https://staging.example.com"

cd $STAGING_PATH

echo "=== Download database produzione ==="
wp db export /tmp/prod-db.sql --path=$PROD_PATH
wp db import /tmp/prod-db.sql

# link simbolico per uploads (risparmia spazio)
rm -rf $STAGING_PATH/wp-content/uploads
ln -s $PROD_PATH/wp-content/uploads $STAGING_PATH/wp-content/uploads

echo "=== Search and replace URL ==="
wp search-replace "https://example.com" "$STAGING_URL" --all-tables --skip-columns=guid

# disabilita cron e email
wp config set DISABLE_WP_CRON true --raw
wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw

echo "Clonazione completata"

Script 4: monitoraggio salute con alerting

#!/bin/bash
# health-check.sh - monitoraggio giornaliero con alert email
set -e

SITE_PATH="/var/www/html"
ADMIN_EMAIL="admin@example.com"

cd $SITE_PATH

# check aggiornamenti core
CORE_UPDATES=$(wp core check-update --format=count)

# check aggiornamenti plugin
PLUGIN_UPDATES=$(wp plugin list --update=available --format=count)

# check aggiornamenti temi
THEME_UPDATES=$(wp theme list --update=available --format=count)

# check integrità core
CORE_CHECK=$(wp core verify-checksums 2>&1 | grep -c "differenza" || true)

# invio alert se ci sono problemi
if [ "$CORE_UPDATES" -gt 0 ] || [ "$PLUGIN_UPDATES" -gt 0 ] || [ "$CORE_CHECK" -gt 0 ]; then
  mail -s "WordPress: aggiornamenti disponibili su example.com" $ADMIN_EMAIL <<EOF
Aggiornamenti core: $CORE_UPDATES
Aggiornamenti plugin: $PLUGIN_UPDATES
Aggiornamenti temi: $THEME_UPDATES
Differenze core: $CORE_CHECK

Esegui: cd $SITE_PATH && wp core update && wp plugin update --all
EOF
fi

Script 5: generazione report mensile

#!/bin/bash
# monthly-report.sh - report mensile stato sito
set -e

SITE_PATH="/var/www/html"
REPORT_FILE="/tmp/wp-report-$(date +%Y%m).txt"

cd $SITE_PATH

{
echo "=== WordPress Site Report $(date +%Y-%m-%d) ==="
echo ""
echo "Versione WordPress: $(wp core version)"
echo "Versione PHP: $(php -r 'echo PHP_VERSION;')"
echo ""
echo "--- Contenuti ---"
echo "Articoli pubblicati: $(wp post list --post_type=post --post_status=publish --format=count)"
echo "Pagine pubblicate: $(wp post list --post_type=page --post_status=publish --format=count)"
echo "Media in library: $(wp post list --post_type=attachment --format=count)"
echo "Utenti registrati: $(wp user list --format=count)"
echo "Commenti: $(wp comment list --format=count)"
echo ""
echo "--- Plugin ---"
wp plugin list --format=table
echo ""
echo "--- Performance ---"
wp db size --format=table
echo ""
echo "--- Aggiornamenti disponibili ---"
wp core check-update
echo "Plugin da aggiornare: $(wp plugin list --update=available --format=count)"
echo "Temi da aggiornare: $(wp theme list --update=available --format=count)"

} > $REPORT_FILE

cat $REPORT_FILE

Integrazione AI con MCP: casi d'uso reali

L'integrazione WP-CLI + AI tramite MCP è la novità più significativa del 2026. Ecco quattro casi d'uso reali che ho implementato su progetti di clienti.

Caso 1: refactoring automatico plugin

Un cliente aveva un plugin legacy con 8.000 righe di codice PHP misto a HTML, jQuery deprecato, e nessuno standard di coding. Con Claude Code connesso via MCP a WP-CLI, è stato possibile:

• Analizzare l'intero plugin con wp eval per capire la struttura
• Identificare pattern problematici con query al codice via MCP
• Riscrivere le sezioni critiche con prompt contestuali
• Testare le modifiche con wp eval e wp test
• Committare le modifiche con messaggi di commit descrittivi

Tempo risparmiato rispetto al refactoring manuale: circa 60%.

Caso 2: generazione contenuti editoriali

Un editore con 50 articoli/mese ha integrato WP-CLI con Claude per:

• Generare bozze di articoli partendo da brief in linguaggio naturale
• Ottimizzare SEO con analisi automatizzata delle keyword
• Generare excerpt, meta description, e tag automaticamente
• Revisionare il tono dei contenuti pubblicati

Caso 3: manutenzione predittiva

Un'agenzia che gestisce 30 siti WordPress ha implementato uno script che:

• Monitora uptime, performance, e aggiornamenti su tutti i siti
• Usa Claude per analizzare i log e identificare pattern anomali
• Genera ticket di manutenzione con diagnosi e soluzione suggerita
• Invia report settimanali con priorità di intervento

Caso 4: migrazione guidata WordPress 7.0

Per un cliente con 15 siti WordPress, è stato possibile:

• Analizzare plugin installati con wp doctor check plugin
• Identificare plugin incompatibili con WP 7.0
• Suggerire alternative moderne con AI
• Generare script di migrazione personalizzati per ogni sito
• Testare la migrazione in staging prima del go-live

Best practice operative

Le best practice che separano un uso amatoriale da un uso professionale di WP-CLI sono sette.

1. Sempre --dry-run prima di operazioni distruttive

# sempre dry-run prima
wp search-replace "old" "new" --dry-run
wp db query "DELETE FROM wp_options WHERE option_name LIKE '%transient%';" --dry-run

2. Backup prima di ogni operazione importante

# regola: backup -> verifica -> operazione
wp db export /tmp/pre-update-$(date +%Y%m%d).sql
wp plugin update --all

3. Usa --allow-root con cautela

Il flag --allow-root permette di eseguire WP-CLI come root (necessario in container Docker o ambienti CI). Va usato solo quando necessario, e mai in produzione interattiva.

4. Configura wp-cli.yml per il progetto

Il file wp-cli.yml nella root del progetto evita di specificare path e parametri ad ogni comando.

5. Usa le application password per CI/CD

Le application password (introdotte in WordPress 5.6) permettono di autenticare le API REST senza esporre la password principale. Per CI/CD e automazioni, sono la scelta sicura.

6. Log delle operazioni

In ambienti di produzione, logga tutte le operazioni WP-CLI con timestamp e operatore:

# esempio di logging
{
  echo "[$(date +%Y-%m-%d_%H:%M:%S)] Operatore: $(whoami)"
  echo "Comando: wp $*"
  wp "$@"
} >> /var/log/wp-cli.log

7. Test in staging prima di produzione

Qualsiasi script o comando complesso va testato in staging prima di essere eseguito in produzione. Il workflow è: sviluppo → staging → produzione, sempre.

Domande frequenti

WP-CLI è sicuro da usare in produzione?

Sì, se usato con criterio. Le regole fondamentali sono: backup prima di operazioni distruttive, dry-run prima di search-replace, test in staging prima di produzione, e logging di tutte le operazioni. Con queste pratiche, WP-CLI è più sicuro del browser admin perché è ripetibile e auditabile.

Qual è la differenza tra wp e wp --allow-root?

Il flag --allow-root permette di eseguire WP-CLI come utente root. È necessario in container Docker, ambienti CI/CD, o quando i permessi file non sono configurati correttamente. In ambienti di produzione interattiva, è meglio configurare i permessi corretti e usare WP-CLI come utente web (www-data, nginx, o equivalente).

Posso usare WP-CLI con WordPress Multisite?

Sì. WP-CLI supporta pienamente WordPress Multisite dalla versione 1.0. I comandi site-wide (es. wp plugin update --all --url=site1.com) permettono di operare su singoli siti del network. Il comando wp site list mostra tutti i siti del network, e wp site switch permette di cambiare il contesto operativo.

Come posso contribuire a WP-CLI?

WP-CLI è open source e accoglie contributi. Il repository ufficiale è github.com/wp-cli/wp-cli. I contributi più richiesti nel 2026 sono: testing, documentazione, nuovi comandi, e miglioramenti delle prestazioni. La community è su Slack (wp-cli.slack.com) e molto attiva.

WP-CLI sostituisce il pannello admin di WordPress?

No, e non è questo il suo scopo. WP-CLI è complementare al pannello admin: per task ripetitivi, automazioni, e operazioni di massa è imbattibile, ma per task occasionali e content editing, il pannello admin resta più ergonomico. La regola operativa è: usa il browser per i task uno-a-uno, usa WP-CLI per i task uno-a-molti.

Quali sono gli errori più comuni con WP-CLI?

I tre errori più frequenti sono: (1) operare nella directory sbagliata (sempre cd nella root di WordPress prima di usare WP-CLI), (2) dimenticare --allow-root in container Docker, (3) eseguire wp search-replace su serializzati senza il supporto nativo (usa sempre il comando ufficiale, non query SQL dirette). Tutti evitabili con le best practice descritte sopra.

WP-CLI funziona con hosting condivisi senza accesso SSH?

No, WP-CLI richiede accesso shell. Per hosting condivisi senza SSH, le alternative sono: usare il pannello admin (lento per task di massa), chiedere all'hosting di eseguire i comandi, o migrare a un hosting con accesso shell. Il prezzo di un hosting con SSH è ormai comparabile a quello degli hosting condivisi entry-level.

Riferimenti ufficiali

Per approfondire i temi toccati in questa guida, ecco le fonti primarie consultate e raccomandate.

• WP-CLI官方网站 - sito ufficiale del progetto.
• WP-CLI Commands - reference completa comandi.
• WP-CLI GitHub - repository ufficiale.
• WP-CLI Package Index - indice pacchetti aggiuntivi.
• Model Context Protocol - specifica MCP.
• WordPress Application Passwords - guida API authentication.
• WP-CLI Docker - immagine Docker ufficiale.
• WordPress Coding Standards - standard di sviluppo.
• Workflow perfetto sviluppo web mrtux.it - framework 7 stadi.
• Plugin WordPress da evitare mrtux.it - lista plugin 2026.

Questa guida verrà aggiornata ad ogni release majeure di WP-CLI. WP-CLI 2.13 è previsto per l'autunno 2026 con miglioramenti alle performance, supporto per PHP 8.5, e nuovi comandi per l'integrazione AI. Per suggerimenti o correzioni, l'area commenti è aperta.