WP-CLI per Agenzie WordPress: Guida Pratica con Script pronti [2026]

Cosa È WP-CLI e Perché Ogni Agenzia WordPress Dovrebbe Usarlo

WP-CLI è la command-line interface ufficiale di WordPress, uno strumento che permette di gestire ogni aspetto di un sito WordPress direttamente dal terminale senza mai aprire il browser. Nella nostra esperienza di gestione di oltre 50 siti WordPress per clienti, WP-CLI riduce i tempi operativi del 70-80% rispetto alla gestione via wp-admin per task ripetitivi come aggiornamenti, migrazioni e manutenzione.

Per un’agenzia che gestisce multipli siti, WP-CLI non è un optional: è la differenza tra scalare i clienti senza assumere nuovo personale o annegare in ticket di supporto. Se gestisci già multipli siti con strumenti come ManageWP, MainWP o AgencyPilot, WP-CLI è il complemento perfetto per le operazioni che richiedono precisione e automazione.

TL;DR — Punti Chiave

• WP-CLI gestisce plugin, temi, utenti, database e contenuti via terminale
• Riduce i tempi operativi del 70-80% per task ripetitivi su multipli siti
• Si integra con script bash, cron job e pipeline CI/CD per automazione completa
• Comandi avanzati per ricerca/sostituzione nel database, export/import, e performance optimization
• Essenziale per disaster recovery: ripristina un sito in minuti, non ore

Installazione e Configurazione di WP-CLI

L’installazione di WP-CLI richiede meno di 2 minuti e funziona su qualsiasi server con accesso SSH. I requisiti minimi sono: PHP 7.4+ (consigliato 8.2+), WordPress 6.0+, e accesso SSH al server.

Installazione Standard

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

# Rendilo eseguibile
chmod +x wp-cli.phar

# Sposta nel PATH
sudo mv wp-cli.phar /usr/local/bin/wp

# Verifica l'installazione
wp --info

L’output del comando wp --info mostra la versione di WP-CLI, PHP, e il percorso di WordPress. Se vedi questi dati, sei pronto per iniziare.

Configurazione per Multi-Sito (Agenzie)

Per gestire multipli siti, la best practice è creare un file di configurazione globale che definisce i percorsi di ogni installazione WordPress. Crea il file ~/.wp-cli/config.yml:

# ~/.wp-cli/config.yml
core config:
  path: /var/www/html

# Alias per multipli siti
@cliente1:
  path: /var/www/cliente1
@cliente2:
  path: /var/www/cliente2
@cliente3:
  path: /var/www/cliente3

Con questa configurazione, puoi eseguire comandi su siti specifici usando la sintassi wp @cliente1 plugin list o anche wp @cliente1,@cliente2,@cliente3 plugin update --all per aggiornamenti batch su multipli siti contemporaneamente.

I 10 Comandi WP-CLI Essenziali per Agenzie

Questi sono i comandi che usiamo quotidianamente in AgencyPilot per gestire i siti dei clienti. Ogni comando include esempi pratici e flag utili.

1. Gestione Plugin

# Lista tutti i plugin con stato e versione
wp plugin list --format=table

# Installa e attiva un plugin
wp plugin install wordfence --activate

# Aggiorna tutti i plugin
wp plugin update --all

# Disattiva tutti i plugin (debug rapido)
wp plugin deactivate --all

# Cerca plugin con una keyword
wp plugin search seo --per-page=5

2. Gestione Temi

# Lista temi installati
wp theme list --status=active

# Installa e attiva un tema
wp theme install twentytwentyfour --activate

# Aggiorna tutti i temi
wp theme update --all

3. Aggiornamenti Core

# Verifica versione core corrente
wp core version

# Cerca aggiornamenti
wp core check-update

# Aggiorna WordPress core
wp core update

# Forza reinstallazione file core (utile dopo hack)
wp core download --force

L’ultimo comando è particolarmente utile in caso di sicurezza WordPress compromessa: reinstalla i file core sovrascrivendo eventuali modifiche malevole senza toccare il database.

4. Gestione Database

# Ottimizza il database
wp db optimize

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

# Importa un database
wp db import backup-20260724.sql

# Resetta il database (ATTENZIONE: cancella tutto)
wp db reset --yes

# Cerca e sostituisci URL (migrazione)
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid

Il comando wp search-replace è probabilmente il più potente per le agenzie: esegue una ricerca e sostituzione serializzata nel database, gestendo correttamente i dati PHP serializzati che un semplice SQL REPLACE non saprebbe gestire. È essenziale per le migrazioni WordPress tra domini.

5. Gestione Utenti

# Crea un nuovo utente amministratore
wp user create mario.rossi mario@example.com --role=administrator --user_pass=Sicura2026!

# Lista utenti per ruolo
wp user list --role=administrator --fields=user_login,user_email,registered

# Cambia password a un utente
wp user update 1 --user_pass=NuovaPassword2026!

# Elimina un utente e riassegna i contenuti
wp user delete 5 --reassign=1

6. Gestione Contenuti

# Lista post per tipo
wp post list --post_type=post --posts_per_page=10 --format=table

# Crea un post
wp post create --post_type=post --post_title='Articolo di test' --post_status=draft

# Aggiorna un post
wp post update 42 --post_title='Nuovo titolo'

# Elimina un post
wp post delete 42 --force

7. Cache e Performance

# Svuota cache oggetti (Redis)
wp cache flush

# Svuota cache del plugin di caching
wp rocket clean --confirm

# Svuota transients
wp transient delete --all

# Rigenera thumbnail
wp media regenerate --yes

Per siti con problemi di Core Web Vitals, svuotare la cache e rigenerare le miniature sono operazioni che WP-CLI esegue in secondi contro i minuti richiesti da wp-admin.

8. Gestione Configurazione

# Leggi un valore wp-config.php
wp config get DB_HOST

# Scrivi un nuovo valore
wp config set WP_DEBUG true --raw

# Aggiungi una costante
wp config set WP_MEMORY_LIMIT '256M'

# Lista tutte le costanti
wp config list --format=table

9. Export e Import WXR

# Esporta tutto il contenuto in WXR
wp export --dir=/tmp/exports --user=1

# Importa da file WXR
wp import /tmp/exports/wordpress.2026-07-24.xml --authors=create

10. Cron e Schedulazione

# Lista event cron
wp cron event list --format=table

# Esegui un evento cron specifico
wp cron event run wp_version_check

# Elimina tutti i cron event orfani
wp cron event delete --all

Automazione con WP-CLI: Script Pronti per la Produzione

L’automazione è dove WP-CLI trasforma radicalmente il lavoro di un’agenzia. Invece di eseguire comandi manualmente su ogni sito, puoi creare script bash che gestiscono multipli siti in parallelo. Ecco tre script che usiamo ogni giorno in AgencyPilot.

Script 1: Aggiornamento Batch Sicuro

Questo script aggiorna core, plugin e temi su tutti i siti configurati, creando un backup prima di ogni aggiornamento e inviando un report via email.

#!/bin/bash
# update-all-sites.sh — Aggiornamento batch sicuro

SITES=("cliente1" "cliente2" "cliente3" "cliente4" "cliente5")
BACKUP_DIR="/backups/$(date +%Y%m%d)"
REPORT_FILE="/tmp/update-report-$(date +%Y%m%d).txt"

mkdir -p "$BACKUP_DIR"

echo "=== Report Aggiornamenti $(date) ===" > "$REPORT_FILE"

for SITE in "${SITES[@]}"; do
    echo "" >> "$REPORT_FILE"
    echo "--- Aggiornamento $SITE ---" >> "$REPORT_FILE"
    
    # Backup del database
    wp @$SITE db export "$BACKUP_DIR/${SITE}-pre-update.sql" 2>>"$REPORT_FILE"
    
    # Aggiorna core
    wp @$SITE core update 2>>"$REPORT_FILE"
    
    # Aggiorna plugin
    wp @$SITE plugin update --all 2>>"$REPORT_FILE"
    
    # Aggiorna temi
    wp @$SITE theme update --all 2>>"$REPORT_FILE"
    
    # Flush cache
    wp @$SITE cache flush 2>>"$REPORT_FILE"
    
    # Verifica sito attivo
    if wp @$SITE option get siteurl 2>/dev/null; then
        echo "✅ $SITE: aggiornamento completato" >> "$REPORT_FILE"
    else
        echo "❌ $SITE: ERRORE — sito non risponde" >> "$REPORT_FILE"
        # Ripristina backup
        wp @$SITE db import "$BACKUP_DIR/${SITE}-pre-update.sql"
    fi
done

# Invia report
mail -s "Report Aggiornamenti WP $(date +%Y-%m-%d)" admin@agencypilot.it < "$REPORT_FILE"

Script 2: Health Check Quotidiano

#!/bin/bash
# wp-health-check.sh — Controlla lo stato di tutti i siti

SITES=("cliente1" "cliente2" "cliente3" "cliente4" "cliente5")
ALERT_EMAIL="alerts@agencypilot.it"
ISSUES=0

for SITE in "${SITES[@]}"; do
    # Verifica sito online
    URL=$(wp @$SITE option get siteurl 2>/dev/null)
    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$URL" 2>/dev/null)
    
    if [ "$HTTP_CODE" != "200" ]; then
        echo "⚠️ $SITE ($URL): HTTP $HTTP_CODE"
        ISSUES=$((ISSUES + 1))
    fi
    
    # Verifica plugin disabilitati per errore
    BROKEN=$(wp @$SITE plugin list --status=active 2>/dev/null | grep -c "fatal")
    if [ "$BROKEN" -gt "0" ]; then
        echo "⚠️ $SITE: $BROKEN plugin con errori fatali"
        ISSUES=$((ISSUES + 1))
    fi
    
    # Verifica spazio database
    DB_SIZE=$(wp @$SITE db size 2>/dev/null)
    echo "📊 $SITE: DB = $DB_SIZE"
done

if [ "$ISSUES" -gt "0" ]; then
    echo "⚠️ Rilevati $ISSUES problemi. Invio alert."
    # Invia notifica
fi

Script 3: Deployment da Git

#!/bin/bash
# wp-deploy.sh — Deploy WordPress da repository Git

SITE=$1
REPO=$2
BRANCH=${3:-main}

if [ -z "$SITE" ] || [ -z "$REPO" ]; then
    echo "Uso: $0   [branch]"
    exit 1
fi

WP_PATH=$(wp @$SITE --info 2>/dev/null | grep "wp_path" | awk '{print $2}')

# Backup pre-deploy
wp @$SITE db export "/backups/${SITE}-pre-deploy-$(date +%Y%m%d%H%M).sql"

# Pull codice
cd "$WP_PATH" || exit 1
git pull origin "$BRANCH"

# Attiva tema
wp @$SITE theme activate custom-theme

# Svuota cache
wp @$SITE cache flush
wp @$SITE rewrite flush

# Verifica
if wp @$SITE option get siteurl 2>/dev/null; then
    echo "✅ Deploy completato su $SITE"
else
    echo "❌ Deploy fallito — ripristino backup"
    wp @$SITE db import "/backups/${SITE}-pre-deploy-*.sql"
    exit 1
fi

WP-CLI per Sicurezza e Hardening

WP-CLI è uno strumento formidabile per le operazioni di sicurezza. Quando un sito viene compromesso, il terminale è spesso l'unico accesso disponibile quando wp-admin è inaccessibile o compromesso. Vediamo i comandi essenziali per la sicurezza WordPress.

Audit Rapido Sicurezza

# Verifica file core modificati
wp core verify-checksums

# Lista tutti gli utenti amministratore
wp user list --role=administrator --fields=ID,user_login,user_email,user_registered

# Cerca plugin con vulnerabilità note
wp plugin list --format=csv | awk -F',' '{print $2}' | while read p; do
    wp plugin status "$p" 2>/dev/null
done

# Verifica permessi file
wp eval 'echo (fileowner(ABSPATH) === posix_getuid()) ? "OK" : "WARNING: wrong owner";'

# Lista sessioni utente attive
wp user session list --format=table

Il comando wp core verify-checksums confronta i file del sito con gli hash ufficiali di WordPress.org. Se rileva discrepanze, hai un potenziale problema di sicurezza che richiede immediata attenzione.

Hardening Rapido Post-Hack

# Reinstalla file core
wp core download --force

# Disattiva tutti i plugin
wp plugin deactivate --all

# Reattiva plugin uno per uno identificando quello compromesso
wp plugin activate wordfence

# Resetta tutte le password utente
wp user list --fields=ID | tail -n +2 | while read id; do
    wp user update "$id" --user_pass=$(openssl rand -base64 16)
done

# Pulisci transients e cache
wp transient delete --all
wp cache flush

WP-CLI e Backup: Strategia 3-2-1 Automatizzata

La strategia di backup WordPress 3-2-1 prevede 3 copie, su 2 supporti diversi, con 1 copia off-site. WP-CLI rende questa strategia automatizzabile:

#!/bin/bash
# backup-3-2-1.sh — Strategia backup 3-2-1 con WP-CLI

SITE=$1
REMOTE_BUCKET="s3://agencypilot-backups"
DATE=$(date +%Y%m%d-%H%M%S)
LOCAL_DIR="/backups/local"
MEDIA_DIR="/backups/media"

# Copia 1: Database locale
wp @$SITE db export "$LOCAL_DIR/${SITE}-db-$DATE.sql"

# Copia 2: File locale (tar)
wp @$SITE --info 2>/dev/null | grep wp_path | awk '{print $2}' | xargs tar czf "$MEDIA_DIR/${SITE}-files-$DATE.tar.gz"

# Copia 3: Off-site (S3)
aws s3 cp "$LOCAL_DIR/${SITE}-db-$DATE.sql" "$REMOTE_BUCKET/$SITE/db/"
aws s3 cp "$MEDIA_DIR/${SITE}-files-$DATE.tar.gz" "$REMOTE_BUCKET/$SITE/files/"

# Pulisci backup vecchi (> 30 giorni)
find "$LOCAL_DIR" -name "${SITE}-db-*.sql" -mtime +30 -delete
find "$MEDIA_DIR" -name "${SITE}-files-*.tar.gz" -mtime +30 -delete

Integrazione WP-CLI con CI/CD Pipeline

Per le agenzie che usano pipeline CI/CD (GitHub Actions, GitLab CI), WP-CLI può automatizzare deployment, test e sincronizzazione dati. Ecco un esempio con GitHub Actions:

# .github/workflows/deploy-wordpress.yml
name: Deploy WordPress
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install WP-CLI
        run: |
          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
      
      - name: Deploy to production
        run: |
          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }} << 'EOF'
            cd /var/www/html
            git pull origin main
            wp core verify-checksums
            wp plugin update --all
            wp cache flush
            wp rewrite flush
          EOF
      
      - name: Run post-deploy tests
        run: |
          wp --path=/var/www/html search-replace 'http://staging.example.com' 'https://example.com' --dry-run

WP-CLI Avanzato: Comandi Custom e Package

WP-CLI supporta comandi personalizzati tramite il sistema di package. Puoi creare comandi custom per le esigenze specifiche della tua agenzia o installare package della community.

Installare Package della Community

# Lista package disponibili
wp package list

# Installa package per gestione SEO
wp package install wp-cli/profile-command

# Installa package per profiling query
wp package install wp-cli/profile-command:@stable

# Verifica package installati
wp package list --format=table

Creare un Comando Custom

Se la tua agenzia ha bisogno di un'operazione specifica ripetuta, puoi creare un comando custom. Ecco un esempio che genera un report riassuntivo di un sito:

// wp-content/plugins/agencypilot-cli/cli-report.php
publish} published, {$posts->draft} drafts");
        WP_CLI::log("Pages: {$pages->publish} published");
        WP_CLI::log("Plugins: " . count($plugins) . " total");
        WP_CLI::log("Themes: " . count($themes) . " total");
        WP_CLI::log("DB Size: " . size_format(wp_get_db()->get_var('SELECT SUM(data_length) FROM information_schema.tables WHERE table_schema = DATABASE()')));
        WP_CLI::success("Report generated");
    });
}

Tabella Comparativa: wp-admin vs WP-CLI

Best Practice WP-CLI per Agenzie

Nella nostra esperienza gestendo siti WordPress per agenzie, abbiamo identificato queste best practice fondamentali:

1. Usa sempre alias — Configura gli alias nel file config.yml per evitare errori sul sito sbagliato. Un comando eseguito sul sito errato può causare danni irreversibili.
2. Backup prima di ogni operazione — Anche le operazioni più sicure possono andare storte. Un wp db export prima di qualsiasi aggiornamento ti salva in caso di problemi.
3. Testa su staging prima — Se hai un ambiente staging, esegui prima gli aggiornamenti lì. WP-CLI rende la sincronizzazione staging→produzione rapida.
4. Automatizza con cron — I task ripetitivi (backup, health check, aggiornamenti) dovrebbero essere automatizzati via crontab, non eseguiti manualmente.
5. Logga tutto — Redirect dell'output su file per ogni script. In caso di problemi, hai l'audit trail completo.
6. Usa --dry-run — Per operazioni distruttive (search-replace, db reset), usa sempre prima --dry-run per verificare cosa verrebbe modificato.
7. Aggiorna WP-CLI regolarmente — wp cli update per avere le ultime fix di sicurezza e nuovi comandi.

FAQ — Domande Frequenti su WP-CLI per Agenzie

WP-CLI funziona su hosting condiviso?

WP-CLI richiede accesso SSH, che molti hosting condivisi non offrono. Tuttivamente, la maggior parte dei provider moderni (SiteGround, Kinsta, Cloudways, WP Engine) supporta WP-CLI. Se il tuo hosting non lo supporta, considera di passare a un provider gestito o VPS.

WP-CLI può danneggiare il sito?

Come qualsiasi strumento potente, WP-CLI può causare danni se usato in modo errato. I comandi come wp db reset o wp search-replace senza --dry-run possono causare perdita di dati. Segui sempre la regola: backup prima, --dry-run per testare, poi esegui.

Qual è la differenza tra WP-CLI e wp-admin?

WP-CLI gestisce via terminale le stesse operazioni che fai via wp-admin, ma con tre vantaggi chiave: velocità (nessun caricamento pagine), automazione (script bash e cron), e accessibilità (funziona anche quando wp-admin è bloccato o compromesso).

Posso usare WP-CLI su WordPress Multisite?

Sì, WP-CLI supporta pienamente il multisite. Usa --url=subsite.example.com per eseguire comandi su un sottosito specifico, oppure ometti il flag per operazioni sulla rete intera.

WP-CLI è gratuito?

Sì, WP-CLI è open source e gratuito, rilasciato sotto licenza MIT. È mantenuto dalla community WordPress e supportato da Automattic. Non richiede costi di licenza o abbonamenti.

Conclusione

WP-CLI è uno strumento indispensabile per ogni agenzia WordPress che vuole scalare. Riduce drasticamente i tempi operativi, elimina gli errori umani tramite automazione, e fornisce accesso di emergenza quando il wp-admin non è disponibile. In AgencyPilot, usiamo WP-CLI ogni giorno per gestire oltre 50 siti con un team ridotto, mantenendo tempi di risposta rapidi e qualità elevata.

Se non hai ancora integrato WP-CLI nel tuo workflow, inizia oggi: installa lo strumento, configura gli alias per i tuoi siti, e crea il tuo primo script di automazione. Il ROI si vede dalla prima settimana.