WP-CLI per Agenzie: Guida Completa ai Comandi Essenziali

Name: AgencyPilot
Author: AgencyPilot

Juan Camilo Auriti

Perché WP-CLI è fondamentale per le agenzie

Se gestisci più di 5 siti WordPress, lavorare via interfaccia grafica è un collo di bottiglia. WP-CLI (WordPress Command Line Interface) permette di eseguire operazioni su decine di siti simultaneamente, automatizzare task ripetitivi e intervenire rapidamente in caso di emergenze.

Dati concreti: un’agenzia media che gestisce 30 siti può risparmiare 15-20 ore al mese usando WP-CLI invece della dashboard. Operazioni come aggiornamenti bulk, backup, migrazioni e debug diventano questione di secondi invece che minuti.

WP-CLI non sostituisce pannelli come AgencyPilot, ma li complementa: usalo per operazioni tecniche puntuali, mantieni il SaaS per monitoring, reportistica e gestione client.

Installazione e configurazione iniziale

Requisiti di sistema

Prima di installare WP-CLI, verifica che il server abbia:

PHP 7.4 o superiore (raccomandato 8.1+)
WordPress 5.6 o superiore
Accesso SSH al server
Estensioni PHP: curl, json, mbstring, openssl

Installazione su server Linux

Il metodo più affidabile per installazioni permanenti:

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 WP-CLI, PHP, percorsi e sistema operativo.

Configurazione alias per server multipli

Per agenzie che gestiscono siti su server diversi, gli alias sono essenziali. Crea ~/.wp-cli/config.yml:

@production:
  ssh: utente@server-prod.com/var/www/sito1
@staging:
  ssh: utente@server-staging.com/var/www/sito1
@locale:
  path: /Users/tuonome/Sites/sito1

Uso pratico:

wp @production plugin list
wp @staging db export

Configurazione wp-cli.yml per progetti

Ogni installazione WordPress può avere un file wp-cli.yml nella root per impostazioni specifiche:

path: public_html
url: https://sito-cliente.it
core download:
  locale: it_IT
core install:
  admin_user: admin
  admin_email: dev@agenzia.it

Comandi core: gestione WordPress base

Installazione e aggiornamenti core

Scarica WordPress in italiano:

wp core download --locale=it_IT

Installa WordPress senza usare il browser:

wp core install --url="https://sitocliente.it" \
  --title="Sito Cliente" \
  --admin_user="admintemp" \
  --admin_password="Password!Temp123" \
  --admin_email="dev@agenzia.it"

Aggiorna core su tutti i siti (da script):

wp core update
wp core update-db

Verifica versione e stato:

wp core version
wp core check-update

Gestione database

I comandi database sono tra i più usati in agenzia:

wp db export backup.sql – Backup completo database
wp db export --add-drop-table backup.sql – Con DROP TABLE per import puliti
wp db import backup.sql – Ripristina database
wp db optimize – Ottimizza tutte le tabelle
wp db query "SELECT * FROM wp_options WHERE option_name='siteurl'" – Query diretta
wp db search "vecchiodominio.it" – Cerca stringa in tutto il DB
wp db search-replace "vecchio.it" "nuovo.it" --dry-run – Simula sostituzione

Per migrazioni, il comando search-replace è fondamentale:

wp db search-replace "https://staging.sito.it" "https://sito.it" \
  --skip-columns=guid \
  --report-changed-only

Gestione plugin: installazione, aggiornamenti, troubleshooting

Operazioni base sui plugin

Lista plugin installati con stato:

wp plugin list

Output mostra nome, stato (active/inactive), aggiornamenti disponibili e versione.

Installa e attiva plugin da repository:

wp plugin install wordpress-seo --activate

Installa versione specifica:

wp plugin install akismet --version=4.2.1 --activate

Aggiorna tutti i plugin:

wp plugin update --all

Aggiorna plugin specifici escludendo altri:

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

Troubleshooting con plugin

Quando un sito va in white screen, disattiva tutti i plugin:

wp plugin deactivate --all

Riattiva uno per uno per identificare il colpevole:

wp plugin activate nome-plugin

Verifica integrità file plugin (confronto con repository):

wp plugin verify-checksums --all

Questo comando è prezioso per identificare file modificati da malware o errori di upload.

Gestione plugin premium

Per plugin premium (ACF PRO, Gravity Forms, ecc.), usa installazione da file:

wp plugin install /path/to/plugin-premium.zip --activate

Crea script bash per aggiornamenti bulk di plugin premium:

#!/bin/bash
for site in /var/www/*/public_html; do
  wp plugin install /backups/acf-pro-latest.zip --force --path="$site"
done

Gestione temi: installazione e child theme

Operazioni base sui temi

Lista temi installati:

wp theme list

Installa tema da repository:

wp theme install twentytwentyfour --activate

Installa tema premium da file:

wp theme install /path/to/tema-premium.zip --activate

Aggiorna tutti i temi:

wp theme update --all

Creazione child theme automatica

WP-CLI può generare child theme con scaffold:

wp scaffold child-theme nome-child-theme \
  --parent_theme=nome-tema-parent \
  --theme_name="Nome Child Theme" \
  --author="Agenzia Nome" \
  --author_uri="https://agenzia.it" \
  --activate

Questo crea automaticamente cartella, style.css e functions.php con struttura corretta.

Gestione utenti e permessi

Creazione e modifica utenti

Crea utente amministratore:

wp user create nomeutente email@dominio.it \
  --role=administrator \
  --user_pass="Password!Sicura123" \
  --first_name="Nome" \
  --last_name="Cognome"

Lista tutti gli utenti con ruolo:

wp user list --role=administrator --field=user_email

Cambia password utente (utile per recupero accessi client):

wp user update nomeutente --user_pass="NuovaPassword123"

Elimina utenti spam (con conferma):

wp user delete 123 --yes

Operazioni bulk su utenti

Per siti con molti utenti, operazioni bulk sono essenziali:

# Esporta lista utenti in CSV
wp user list --format=csv > utenti.csv

# Elimina tutti gli utenti con ruolo subscriber
wp user list --role=subscriber --field=ID | xargs wp user delete

# Cambia ruolo a tutti i contributor in author
wp user list --role=contributor --field=ID | xargs -I % wp user set-role % author

Gestione contenuti: post, pagine, media

Operazioni su post e pagine

Crea post da command line:

wp post create --post_type=post \
  --post_title="Titolo Post" \
  --post_content="Contenuto del post qui" \
  --post_status=publish \
  --post_author=1

Lista post con filtri:

wp post list --post_type=post --post_status=draft --format=table

Elimina tutti i post in bozza:

wp post delete $(wp post list --post_status=draft --format=ids) --force

Aggiorna campo custom su tutti i post:

wp post list --format=ids | xargs -I % wp post meta update % campo_custom "valore"

Gestione media library

Rigenera thumbnails (dopo cambio dimensioni):

wp media regenerate --yes

Importa immagini da cartella:

wp media import /path/to/images/*.jpg --post_id=123

Pulisci media non utilizzati (richiede plugin):

wp media list --format=ids | while read id; do
  wp post list --post_type=attachment --p=$id --format=count
done

Cache e performance

Gestione cache con WP-CLI

Per siti con cache plugin (W3 Total Cache, WP Rocket, ecc.):

# W3 Total Cache
wp w3-total-cache flush

# WP Super Cache
wp cache flush

# WP Rocket
wp rocket clean --confirm

# Cache oggetti (Redis/Memcached)
wp cache flush

Transient cleanup

I transient possono gonfiare il database. Pulizia periodica:

# Elimina tutti i transient scaduti
wp transient delete --expired

# Elimina tutti i transient (anche validi)
wp transient delete --all

# Lista transient per debug
wp transient list

Operazioni avanzate per agenzie

Script bash per operazioni bulk

Esempio script per aggiornare tutti i siti in una cartella:

#!/bin/bash
SITES_DIR="/var/www"
LOG_FILE="/var/log/wp-updates.log"

for site in $SITES_DIR/*/public_html; do
  echo "Aggiornamento $site" | tee -a $LOG_FILE
  wp core update --path="$site" | tee -a $LOG_FILE
  wp plugin update --all --path="$site" | tee -a $LOG_FILE
  wp theme update --all --path="$site" | tee -a $LOG_FILE
  echo "---" | tee -a $LOG_FILE
done

Backup automatizzati

Script backup completo (file + database):

#!/bin/bash
SITE_PATH="/var/www/sito/public_html"
BACKUP_DIR="/backups/$(date +%Y%m%d)"

mkdir -p $BACKUP_DIR

# Backup database
wp db export $BACKUP_DIR/database.sql --path=$SITE_PATH

# Backup file (escludendo cache)
tar -czf $BACKUP_DIR/files.tar.gz \
  --exclude='wp-content/cache' \
  --exclude='wp-content/uploads/cache' \
  -C $SITE_PATH .

echo "Backup completato: $BACKUP_DIR"

Health check automatico

Verifica salute siti in cron:

#!/bin/bash
for site in /var/www/*/public_html; do
  SITE_NAME=$(basename $(dirname $site))
  
  # Verifica core updates
  UPDATES=$(wp core check-update --path="$site" --format=count)
  
  if [ $UPDATES -gt 0 ]; then
    echo "$SITE_NAME: $UPDATES aggiornamenti core disponibili"
  fi
  
  # Verifica plugin updates
  PLUGIN_UPDATES=$(wp plugin list --path="$site" --update=available --format=count)
  
  if [ $PLUGIN_UPDATES -gt 0 ]; then
    echo "$SITE_NAME: $PLUGIN_UPDATES plugin da aggiornare"
  fi
done

WP-CLI con AgencyPilot

AgencyPilot integra nativamente WP-CLI per operazioni bulk su più siti. Dalla dashboard puoi:

Eseguire comandi WP-CLI custom su gruppi di siti
Schedulare operazioni ricorrenti (backup, aggiornamenti, cleanup)
Monitorare output e log di esecuzione comandi
Creare template di comandi riutilizzabili

Questo approccio ibrido (GUI per monitoring, CLI per operazioni) è il workflow più efficiente per agenzie moderne. Mantieni controllo visuale su stato siti, ma esegui operazioni tecniche via terminale quando necessario.

Best practice e suggerimenti di sicurezza

Sicurezza nell’uso di WP-CLI

Regole fondamentali per agenzie:

Non salvare password in script – Usa variabili d’ambiente o vault (Ansible Vault, 1Password CLI)
Limita accesso SSH – Solo IP agenzia, chiavi SSH invece di password
Log delle operazioni – Registra sempre chi esegue cosa e quando
Backup prima di operazioni bulk – Sempre, nessuna eccezione
Test su staging – Script nuovi vanno testati su ambiente non produzione

Ottimizzazione performance WP-CLI

Per operazioni su molti siti:

Usa --skip-plugins e --skip-themes quando non necessari
Parallelizza con GNU Parallel: parallel wp plugin update --all --path={} ::: /var/www/*/public_html
Aumenta memory limit PHP per operazioni pesanti: wp --allow-root config set WP_MEMORY_LIMIT 512M
Disabilita output verbose con --quiet in cron job

Documentazione per il team

Crea un repository interno con:

Script bash testati e commentati
Alias WP-CLI per operazioni comuni dell’agenzia
Procedura di rollback per ogni operazione critica
Checklist pre/post intervento su siti production

Risorse e package utili

Package WP-CLI essenziali per agenzie

Estendi WP-CLI con package della community:

# Doctor - diagnostica problemi WordPress
wp package install wp-cli/doctor-command

# Profile - profiling performance
wp package install wp-cli/profile-command

# Dist-archive - crea archivi per distribuzione
wp package install wp-cli/dist-archive-command

Uso Doctor per check automatico:

wp doctor check --all

Risorse aggiuntive

Documentazione ufficiale: developer.wordpress.org/cli/commands
WP-CLI Handbook: guide approfondite su usi avanzati
GitHub WP-CLI: per contribuire o segnalare bug
Community Slack: per supporto real-time da altri developer

FAQ

WP-CLI funziona anche su hosting condiviso?

Dipende dall’hosting. Molti hosting condivisi bloccano accesso SSH o limitano esecuzione script PHP da command line. Hosting gestiti come Kinsta, WP Engine e SiteGround supportano WP-CLI nativamente. Per hosting condiviso economico, verifica documentazione provider o contatta supporto. In alternativa, considera migrazione a VPS o hosting gestito se gestisci siti professionali.

Come automatizzo backup giornalieri con WP-CLI?

Crea script bash che esegue wp db export e archivia file, poi schedulalo con cron. Esempio crontab per backup alle 3 AM: 0 3 * * * /path/to/backup-script.sh. Lo script deve includere compressione (gzip), rotazione backup (elimina file vecchi di 30+ giorni) e notifica email in caso di errore. Per agenzie con molti siti, considera strumenti come AgencyPilot che orchestrano backup centralizzati invece di gestire cron su ogni server.

Posso usare WP-CLI per migrare siti tra server?

Sì, è uno degli usi più comuni. Processo: 1) Esporta DB con wp db export sul server origine, 2) Sincronizza file via rsync o SFTP, 3) Importa DB con wp db import su destinazione, 4) Esegui wp search-replace per aggiornare URL, 5) Aggiorna permessi file e configura web server. Per migrazioni frequenti, crea script che automatizza tutti gli step. Attenzione: verifica sempre su staging prima di migrazioni production.

WP-CLI rallenta il server durante operazioni bulk?

Operazioni come wp media regenerate o wp search-replace su database grandi possono consumare risorse. Best practice: esegui operazioni pesanti in orari di basso traffico, usa nice per ridurre priorità processo (nice -n 19 wp media regenerate), monitora carico server con htop, considera split di operazioni con limiti (--per-page=100 per operazioni graduate). Su VPS con risorse limitate, valuta esecuzione su staging e poi sync finale.

Come gestisco errori in script WP-CLI automatizzati?

Implementa controllo errori in bash con set -e (stop su errore) e verifica exit code WP-CLI. Esempio: if ! wp plugin update --all; then echo "Errore aggiornamento" | mail -s "Alert" admin@agenzia.it; fi. Logga sempre output con timestamp: wp comando 2>&1 | ts >> /var/log/wp-operations.log. Per operazioni critiche, implementa rollback automatico: salva stato pre-operazione e ripristina se comando fallisce. Tool come AgencyPilot forniscono monitoring con alert automatici per fallimenti su operazioni bulk.