WP-CLI: Guida Completa per Agenzie Web (2026)

Name: AgencyPilot
Author: AgencyPilot

Juan Camilo Auriti

Perché WP-CLI è indispensabile per le agenzie

Se gestisci più di 5 siti WordPress per clienti, operare via dashboard è inefficiente. WP-CLI (WordPress Command Line Interface) permette di eseguire operazioni complesse in secondi, automatizzare task ripetitivi e gestire emergenze senza accesso al pannello admin.

I vantaggi concreti per le agenzie:

Velocità operativa: aggiornare plugin su 20 siti richiede 30 secondi invece di 40 minuti
Automazione: script per deploy, backup, manutenzione programmata
Troubleshooting rapido: accesso diretto al database e ai file senza FTP
Operazioni batch: modifiche identiche su decine di siti contemporaneamente
Gestione da remoto: SSH permette interventi da qualsiasi postazione

Secondo dati Kinsta 2025, le agenzie che usano WP-CLI riducono del 60% il tempo dedicato alla manutenzione ordinaria. Per chi usa strumenti come AgencyPilot, WP-CLI diventa il braccio operativo che esegue comandi sui siti client in modo centralizzato.

Installazione e configurazione iniziale

WP-CLI richiede ambiente Unix-like (Linux, macOS, WSL su Windows) con PHP 7.4 o superiore e WordPress 5.9+.

Installazione su server Linux

Il metodo ufficiale via curl è il più affidabile:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Verifica l’installazione:

wp --info

Dovresti vedere output con versione PHP, MySQL, directory WordPress. Se appare errore “wp: command not found”, aggiungi /usr/local/bin al PATH nel tuo .bashrc o .zshrc.

Configurazione per ambienti multi-cliente

Per agenzie che gestiscono molti siti, crea alias nel file ~/.wp-cli/config.yml:

@cliente1:
  ssh: utente@server1.example.com/var/www/cliente1
@cliente2:
  ssh: utente@server2.example.com/var/www/cliente2

Ora puoi eseguire comandi su siti remoti:

wp @cliente1 core version
wp @cliente2 plugin list --status=active

Per operazioni batch su tutti i siti, usa @all dopo aver definito gli alias.

Permessi e sicurezza

Aspetti critici per ambienti di produzione:

Utente dedicato: esegui WP-CLI con utente che ha ownership sui file WordPress (solitamente www-data o nginx)
Nessun sudo: configurare permessi corretti evita di usare privilegi root
SSH key-based auth: per accesso remoto, usa chiavi SSH invece di password
Log delle operazioni: configura logging con --debug per tracciare modifiche critiche

Comandi essenziali per gestione quotidiana

Core WordPress: aggiornamenti e informazioni

Verifica versione e aggiornamenti disponibili:

wp core version
wp core check-update

Aggiornamento a versione specifica (utile per testare prima del rollout generale):

wp core update --version=6.7.1
wp core update-db  # aggiorna database se necessario

Download WordPress in nuova directory (per setup iniziale):

wp core download --locale=it_IT --path=/var/www/nuovo-cliente

Configurazione database per nuova installazione:

wp config create --dbname=wpdb --dbuser=wpuser --dbpass=password --locale=it_IT

Plugin: installazione e gestione massiva

Lista tutti i plugin con stato aggiornamenti:

wp plugin list --fields=name,status,version,update

Installazione multipla da file di testo (plugin-standard.txt con uno slug per riga):

cat plugin-standard.txt | xargs wp plugin install --activate

Aggiornamento selettivo (escludi plugin critici da verificare manualmente):

wp plugin update --all --exclude=woocommerce,elementor-pro

Disattivazione temporanea per troubleshooting:

wp plugin deactivate --all
wp plugin activate yoast-seo  # riattiva uno alla volta

Ricerca plugin vulnerabili (combinato con wp-vulnerability-scanner):

wp plugin list --field=name | xargs -I {} wp plugin status {}

Temi: gestione e switch rapido

Lista temi installati:

wp theme list

Installazione e attivazione tema child:

wp theme install twentytwentyfour
wp scaffold child-theme cliente-child --parent_theme=twentytwentyfour --activate

Switch tema per test (con rollback immediato se problemi):

wp theme activate nuovo-tema
# testa il frontend
wp theme activate tema-precedente  # rollback se necessario

Database: backup, search-replace, ottimizzazione

Export database completo:

wp db export backup-$(date +%Y%m%d-%H%M%S).sql

Search-replace per migrazione dominio (con dry-run):

wp search-replace 'vecchiodominio.it' 'nuovodominio.it' --dry-run
wp search-replace 'vecchiodominio.it' 'nuovodominio.it' --skip-columns=guid

Ottimizzazione tabelle (importante dopo grandi operazioni):

wp db optimize

Query diretta per check rapidi:

wp db query "SELECT COUNT(*) FROM wp_posts WHERE post_status='publish'"

Import database da backup:

wp db import backup-20260520-143022.sql

Utenti: gestione accessi e reset password

Lista utenti con ruoli:

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

Creazione utente amministratore temporaneo (per emergenze):

wp user create emergenza-admin emergency@agency.it --role=administrator --user_pass=TempPass2026!

Reset password quando il cliente la dimentica:

wp user update nome-utente --user_pass=NuovaPassword123

Eliminazione utenti spam (da iscrizioni massive):

wp user list --role=subscriber --field=ID | xargs wp user delete --yes

Post e contenuti: manipolazione bulk

Creazione post programmatici per test:

wp post generate --count=10 --post_type=post --post_status=publish

Lista post in bozza da più di 30 giorni:

wp post list --post_status=draft --post_type=post --fields=ID,post_title,post_date

Eliminazione revisioni vecchie (libera spazio database):

wp post delete $(wp post list --post_type='revision' --format=ids) --force

Cambio autore massivo per migrazione contenuti:

wp post list --post_type=post --author=5 --format=ids | xargs -I % wp post update % --post_author=7

Comandi avanzati per operazioni complesse

Cache e performance

Gestione cache oggetti (Redis/Memcached):

wp cache flush
wp cache type  # mostra tipo cache attivo

Per plugin cache specifici (WP Rocket, W3 Total Cache):

wp rocket clean --confirm
wp w3-total-cache flush all

Regenerazione miniature immagini dopo cambio tema:

wp media regenerate --yes

Cron e task schedulati

Lista eventi cron programmati:

wp cron event list

Esecuzione manuale cron (utile se disabilitato via DISABLE_WP_CRON):

wp cron event run --due-now

Eliminazione evento specifico che causa problemi:

wp cron event delete plugin_problematico_check

Per agenzie che gestiscano cron via server, aggiungi a crontab:

*/15 * * * * cd /var/www/cliente && wp cron event run --due-now --quiet

Multisite: gestione network

Lista tutti i siti nel network:

wp site list

Creazione nuovo sito nel network:

wp site create --slug=nuovosito --title="Nuovo Sito Cliente" --email=admin@cliente.it

Operazioni su sito specifico del network:

wp plugin activate woocommerce --url=sottosito.rete.it

Eliminazione siti spam o inutilizzati:

wp site list --field=url | grep 'spam-pattern' | xargs -I {} wp site delete --slug={} --yes

WP-CLI package: estensioni community

Installazione package per funzionalità extra:

wp package install wp-cli/doctor-command
wp package install git@github.com:pressbooks/pb-cli.git

Package utili per agenzie:

doctor-command: diagnostica salute installazione WordPress
profile-command: profiling performance per identificare colli di bottiglia
search-replace-command: versione avanzata search-replace
cron-command: gestione avanzata scheduled tasks

Esecuzione diagnostica completa:

wp doctor check --all

Script e automazione per workflow agenzia

Script manutenzione settimanale

Crea file manutenzione-settimanale.sh:

#!/bin/bash
SITI=("cliente1" "cliente2" "cliente3")

for SITO in "${SITI[@]}"; do
  echo "Manutenzione $SITO..."
  wp @$SITO core update
  wp @$SITO plugin update --all
  wp @$SITO theme update --all
  wp @$SITO cache flush
  wp @$SITO db optimize
  echo "$SITO completato\n"
done

echo "Manutenzione completata su tutti i siti"

Esegui via cron ogni domenica alle 3:00:

0 3 * * 0 /home/agency/scripts/manutenzione-settimanale.sh >> /var/log/wp-maintenance.log 2>&1

Backup automatizzato pre-aggiornamenti

Script sicuro per aggiornamenti major:

#!/bin/bash
SITO=$1
DATA=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="/backup/$SITO"

mkdir -p $BACKUP_DIR

echo "Backup database..."
wp @$SITO db export $BACKUP_DIR/db-$DATA.sql

echo "Backup file..."
tar -czf $BACKUP_DIR/files-$DATA.tar.gz -C /var/www/$SITO .

echo "Aggiornamento WordPress..."
wp @$SITO core update
wp @$SITO core update-db

echo "Verifica sito..."
STATUS=$(curl -o /dev/null -s -w "%{http_code}" https://$SITO.it)

if [ $STATUS -eq 200 ]; then
  echo "Aggiornamento completato con successo"
else
  echo "ERRORE: sito non risponde. Avviare rollback manuale."
  exit 1
fi

Deploy automatico sito staging su produzione

Sincronizzazione database e file con search-replace:

#!/bin/bash
# Da eseguire su server produzione

wp db export backup-pre-sync-$(date +%Y%m%d).sql

scp staging@staging.agency.it:/var/www/db-staging.sql /tmp/
wp db import /tmp/db-staging.sql

wp search-replace 'staging.cliente.it' 'cliente.it' --skip-columns=guid

rsync -avz --exclude 'wp-config.php' staging@staging.agency.it:/var/www/cliente/wp-content/ /var/www/cliente/wp-content/

wp cache flush
wp rewrite flush

Monitoring e alert automatici

Script per verificare aggiornamenti disponibili con notifica:

#!/bin/bash
SITI=("cliente1" "cliente2" "cliente3")
ALERT=""

for SITO in "${SITI[@]}"; do
  UPDATES=$(wp @$SITO plugin list --update=available --format=count)
  if [ $UPDATES -gt 0 ]; then
    ALERT="$ALERT\n$SITO: $UPDATES aggiornamenti disponibili"
  fi
done

if [ -n "$ALERT" ]; then
  echo -e "Aggiornamenti necessari:$ALERT" | mail -s "WP Updates Alert" team@agency.it
fi

Troubleshooting: risolvere problemi comuni

Sito in errore 500 dopo aggiornamento

Procedura sistematica di debug:

Abilita debug mode via WP-CLI:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw

Controlla log errori:

tail -f /var/www/cliente/wp-content/debug.log

Disattiva tutti i plugin:
```
wp plugin deactivate --all
```
Riattiva tema di default:
```
wp theme activate twentytwentyfour
```
Se il sito torna online, riattiva plugin uno alla volta per identificare il colpevole

Database corrotto o errore “Error establishing connection”

Verifica connessione database:

wp db check

Ripara tabelle danneggiate:

wp db repair

Verifica credenziali wp-config.php:

wp config get DB_NAME
wp config get DB_USER
wp config get DB_PASSWORD

Permessi file errati

Reset permessi standard WordPress:

find /var/www/cliente -type d -exec chmod 755 {} \;
find /var/www/cliente -type f -exec chmod 644 {} \;
chmod 600 /var/www/cliente/wp-config.php

WP-CLI non trova WordPress

Se ricevi “Error: This does not seem to be a WordPress installation”:

Verifica di essere nella directory root WordPress (con wp-config.php)
Specifica path manualmente: wp --path=/var/www/cliente plugin list
Controlla ownership file: ls -la wp-config.php (deve essere leggibile dall’utente che esegue WP-CLI)

Integrazione WP-CLI con strumenti agenzia

AgencyPilot e automazione centralizzata

Se usi AgencyPilot per gestire portfolio clienti, puoi integrare WP-CLI via API per eseguire comandi da dashboard centralizzata. AgencyPilot supporta esecuzione remota comandi WP-CLI su tutti i siti monitorati.

Esempio workflow: dalla dashboard AgencyPilot selezioni 15 siti cliente e lanci “Aggiorna tutti i plugin” — sotto il cofano vengono eseguiti comandi WP-CLI via SSH su ogni server.

Git e deployment

Workflow deployment con WP-CLI:

git pull origin main
composer install --no-dev
wp plugin update --all
wp cache flush
wp rewrite flush

Aggiungi a git hooks per automazione post-deploy.

CI/CD con WP-CLI

Esempio GitHub Actions per testing automatico:

name: WP Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup 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: Install WordPress
        run: |
          wp core download
          wp config create --dbname=test --dbuser=root --dbpass=root
          wp core install --url=test.local --title=Test --admin_user=admin --admin_password=admin --admin_email=test@test.com
      - name: Run tests
        run: wp plugin list

Best practice e ottimizzazioni

Performance WP-CLI su grandi siti

Per siti con database enormi (>5GB), alcune operazioni possono essere lente:

Usa --skip-plugins quando possibile per evitare caricamento plugin non necessari
Limita risultati query: wp post list --posts_per_page=100
Usa --format=ids invece di --format=table per output più veloci
Per search-replace massicci, considera --report-changed-only

Sicurezza comandi critici

Comandi pericolosi da proteggere:

wp db reset: elimina tutto il database (richiede –yes esplicito)
wp site delete: elimina sito da multisite
wp user delete: rimuove utenti
wp plugin delete: elimina plugin e dati

Best practice: crea alias safe per comandi critici con conferma:

alias wp-reset='echo "ATTENZIONE: comando distruttivo. Conferma con wp db reset --yes"'

Logging e audit trail

Traccia tutte le operazioni WP-CLI per compliance:

# Aggiungi a .bashrc/.zshrc
wp() {
  echo "[$(date)] wp $@" >> /var/log/wp-cli-audit.log
  command wp "$@"
}

Risorse e aggiornamenti continui

WP-CLI è attivamente sviluppato. Mantieni aggiornato il tool:

wp cli update

Risorse ufficiali:

Documentazione completa: https://developer.wordpress.org/cli/commands/
Handbook WP-CLI: https://make.wordpress.org/cli/handbook/
Package community: https://wp-cli.org/package-index/
GitHub WP-CLI: https://github.com/wp-cli/wp-cli

Per agenzie, investire tempo in automazione WP-CLI si ripaga in settimane. Un singolo script può far risparmiare ore ogni mese moltiplicato per decine di clienti.

FAQ

Come posso eseguire WP-CLI su un hosting condiviso senza accesso SSH?

La maggior parte degli hosting condivisi non permette WP-CLI per limitazioni di sicurezza. Soluzioni alternative: usa hosting che supportino SSH (Kinsta, Siteground GOgeek, WP Engine), oppure installa WP-CLI localmente e lavora su copie staging. Alcuni provider offrono WP-CLI via pannello custom (cPanel terminal limitato). Per agenzie, consigliamo passare a VPS o managed hosting con accesso SSH completo — i benefici superano di gran lunga i costi.

È sicuro eseguire aggiornamenti automatici con WP-CLI senza test manuali?

Dipende dalla criticità del sito. Per blog semplici con pochi plugin, aggiornamenti automatici via script sono generalmente sicuri. Per e-commerce o siti complessi, raccomandiamo workflow a 3 step: 1) test su staging con WP-CLI, 2) verifica funzionalità critiche, 3) deploy su produzione solo se staging OK. Usa sempre backup pre-aggiornamento automatizzati. In AgencyPilot implementiamo rollback automatico se health check post-aggiornamento fallisce.

Posso usare WP-CLI per migrare siti tra server diversi?

Sì, è uno degli usi più potenti. Workflow completo migrazione: 1) Export database sul server origine wp db export, 2) tar dei file tar -czf, 3) trasferimento via scp/rsync, 4) import database su destinazione wp db import, 5) search-replace URL/path wp search-replace, 6) aggiornamento permalink e cache. Tempo totale per sito medio: 5-10 minuti contro ore via pannello. Script la procedura per migrazioni ricorrenti.

Come debuggo errori durante esecuzione comandi WP-CLI?

Usa flag --debug per output verboso: wp plugin update --all --debug. Per errori fatali PHP, abilita error reporting nel server. Verifica log PHP (solitamente /var/log/php-fpm/error.log o /var/log/apache2/error.log). Comando utile: wp --info mostra configurazione ambiente (versione PHP, estensioni caricate). Per errori database, usa wp db check per diagnostica. Se WP-CLI crasha, testa con WordPress vanilla per escludere conflitti plugin/tema.

Quale utente Linux dovrebbe eseguire comandi WP-CLI in produzione?

Usa lo stesso utente che possiede i file WordPress (solitamente www-data, nginx, o utente dedicato al sito). Evita root per sicurezza. Verifica ownership con ls -la wp-config.php e switch utente con sudo -u www-data wp plugin list. Per agenzie con molti siti, crea utente dedicato per script automatici con permessi limitati a directory specifiche. Configura sudoers per permettere esecuzione WP-CLI senza password solo per comandi specifici se necessario.