claude-plugins/wordpress/skills/wp-cli/SKILL.md

name, description

name	description
wp-cli	Gestão WordPress via WP-CLI no servidor CWP. Cobre core, plugins, temas, base de dados, utilizadores, migração, search-replace e automação com suporte multi-PHP.

/wp-cli - Gestão WordPress via WP-CLI no CWP

Operações WordPress via linha de comandos no servidor CWP (server.descomplicar.pt). Cobre core, plugins, temas, base de dados, utilizadores, migração e automação.

Servidor: server.descomplicar.pt | porta SSH: 9443 Fonte: Hub/06-Operacoes/Documentacao/Manuais/WP-CLI no CWP.md NotebookLM: WordPress Config CLI

---

Contexto CWP — Regras Obrigatórias

# 1. Usar sempre --allow-root (CWP executa como root)
# 2. Especificar sempre --path= (não fazer cd)
# 3. Usar o PHP correcto para cada utilizador

# Formato base
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp COMANDO --allow-root --path=/home/USER/public_html

# Aliases ~/.bashrc (se configurados)
alias wp74='/opt/alt/php-fpm74/usr/bin/php /usr/local/bin/wp --allow-root'
alias wp82='/opt/alt/php-fpm82/usr/bin/php /usr/local/bin/wp --allow-root'
alias wp83='/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root'

Versões PHP disponíveis

Alias	PHP	Path
wp74	7.4	/opt/alt/php-fpm74/usr/bin/php
wp80	8.0	/opt/alt/php-fpm80/usr/bin/php
wp81	8.1	/opt/alt/php-fpm81/usr/bin/php
wp82	8.2	/opt/alt/php-fpm82/usr/bin/php
wp83	8.3	/opt/alt/php-fpm83/usr/bin/php

Detectar PHP activo de um utilizador

# Ver pool PHP-FPM do utilizador
ps aux | grep "php-fpm: pool USER" | grep -v grep | head -1

# Ou usar wp-auto.sh (auto-detect)
/root/wp-auto.sh --path=/home/USER/public_html plugin list

O script wp-auto.sh está em scripts/wp-auto.sh desta skill.

---

Core WordPress

PATH=/home/USER/public_html

# Verificar versão
wp core version --allow-root --path=$PATH

# Actualizar WordPress
wp core update --allow-root --path=$PATH

# Verificar integridade dos ficheiros
wp core verify-checksums --allow-root --path=$PATH

# Instalar versão específica
wp core download --version=6.4.3 --force --allow-root --path=$PATH

# Informações ambiente
wp --info --allow-root --path=$PATH

---

Plugins

# Listar todos os plugins
wp plugin list --allow-root --path=$PATH

# Listar plugins desactualizados
wp plugin list --update=available --format=table --allow-root --path=$PATH

# Actualizar todos os plugins
wp plugin update --all --allow-root --path=$PATH

# Instalar e activar
wp plugin install akismet --activate --allow-root --path=$PATH

# Activar / desactivar
wp plugin activate NOME --allow-root --path=$PATH
wp plugin deactivate NOME --allow-root --path=$PATH

# Remover plugin
wp plugin delete NOME --allow-root --path=$PATH

# Verificar integridade
wp plugin verify-checksums --all --allow-root --path=$PATH

---

Temas

# Listar temas
wp theme list --allow-root --path=$PATH

# Instalar e activar
wp theme install hello-elementor --activate --allow-root --path=$PATH

# Actualizar todos os temas
wp theme update --all --allow-root --path=$PATH

# Activar tema
wp theme activate NOME --allow-root --path=$PATH

---

Base de Dados

# Exportar (backup)
wp db export /home/USER/backup_$(date +%Y%m%d_%H%M).sql --allow-root --path=$PATH

# Importar (restaurar)
wp db import backup.sql --allow-root --path=$PATH

# Optimizar tabelas
wp db optimize --allow-root --path=$PATH

# Reparar tabelas corrompidas
wp db repair --allow-root --path=$PATH

# Query directa
wp db query "SELECT option_name, option_value FROM wp_options WHERE option_name='siteurl';" --allow-root --path=$PATH

# Tamanho tabelas
wp db query "SELECT table_name, ROUND((data_length+index_length)/1024/1024,2) AS MB FROM information_schema.tables WHERE table_schema=DATABASE() ORDER BY MB DESC LIMIT 20;" --allow-root --path=$PATH

---

Migração de Site (Search-Replace)

# Preview (dry-run) — SEMPRE primeiro
wp search-replace 'https://old.com' 'https://new.com' --dry-run --allow-root --path=$PATH

# Executar após confirmar
wp search-replace 'https://old.com' 'https://new.com' --allow-root --path=$PATH

# Com relatório
wp search-replace 'old.com' 'new.com' --report --allow-root --path=$PATH

# Após migração: limpar cache e regenerar rewrite rules
wp cache flush --allow-root --path=$PATH
wp rewrite flush --allow-root --path=$PATH

---

Utilizadores

# Listar utilizadores
wp user list --allow-root --path=$PATH

# Criar administrador
wp user create admin admin@site.pt --role=administrator --user_pass=SENHA --allow-root --path=$PATH

# Redefinir password
wp user update USERNAME --user_pass=NOVA_SENHA --allow-root --path=$PATH

# Adicionar papel a utilizador existente
wp user set-role USERNAME administrator --allow-root --path=$PATH

# Remover utilizador (transferindo conteúdo)
wp user delete USERNAME --reassign=1 --allow-root --path=$PATH

# Actualizar email admin
wp option update admin_email "novo@email.pt" --allow-root --path=$PATH

---

Cache e Transientes

# Limpar object cache (Redis/Memcached)
wp cache flush --allow-root --path=$PATH

# Apagar todos os transientes
wp transient delete --all --allow-root --path=$PATH

# Regenerar rewrite rules
wp rewrite flush --allow-root --path=$PATH

# Sequência completa pós-alteração
wp cache flush --allow-root --path=$PATH && \
wp transient delete --all --allow-root --path=$PATH && \
wp rewrite flush --allow-root --path=$PATH

---

Modo Manutenção

# Activar modo manutenção
wp maintenance-mode activate --allow-root --path=$PATH

# Verificar estado
wp maintenance-mode status --allow-root --path=$PATH

# Desactivar
wp maintenance-mode deactivate --allow-root --path=$PATH

---

Cron WordPress

# Listar eventos cron
wp cron event list --allow-root --path=$PATH

# Executar evento manualmente
wp cron event run HOOK_NAME --allow-root --path=$PATH

# Ver schedules disponíveis
wp cron schedule list --allow-root --path=$PATH

# Apagar evento
wp cron event delete HOOK_NAME --allow-root --path=$PATH

---

Operações em Massa (Todos os Sites)

# Encontrar todas as instalações WordPress
find /home -name wp-config.php -not -path "*/backup*" 2>/dev/null | while read config; do
    dir=$(dirname "$config")
    user=$(stat -c '%U' "$dir")
    echo "=== $user: $dir ==="
done

# Actualizar todos os sites (com PHP auto-detect)
find /home -name wp-config.php -not -path "*/backup*" 2>/dev/null | while read config; do
    dir=$(dirname "$config")
    user=$(stat -c '%U' "$dir")
    echo "--- Actualizando $user ---"
    php_fpm=$(ps aux | grep "php-fpm: pool ${user}" | grep -v grep | head -1 | grep -o 'php-fpm[0-9][0-9]' | head -1)
    php_ver=${php_fpm:-php-fpm82}
    /opt/alt/${php_ver}/usr/bin/php /usr/local/bin/wp core update --allow-root --path="$dir" 2>/dev/null
    /opt/alt/${php_ver}/usr/bin/php /usr/local/bin/wp plugin update --all --allow-root --path="$dir" 2>/dev/null
done

---

Erros Comuns e Soluções

Erro	Causa	Solução
Operation not permitted	Sem --allow-root	Adicionar --allow-root
PHP Fatal error: memory	Limite memória	define('WP_MEMORY_LIMIT','256M') no wp-config.php
max_execution_time exceeded	Timeout em ops longas	--exec-time=300 ou php.ini
Error establishing database connection	BD em baixo	wp db check --allow-root
Warning: Could not get lock	Outro processo activo	wp cli cache clear --allow-root
PHP version wrong	Site usa PHP diferente	ps aux | grep "pool USER" para detectar
wp elementor flush_css apaga CSS de páginas já OK	O comando limpa todo o directório uploads/elementor/css/, não só a página-alvo — qualquer página não revisitada fica com post-N.css 404/HTML até ser visitada de novo	Depois de qualquer flush, fazer loop curl por todos os permalinks publicados (wp post list --field=url) para forçar regeneração; confirmar content-type: text/css em cada post-N.css; purgar Cloudflare duas vezes se persistir (origem pode ficar um ciclo atrás do edge)
wp option update NOME --format=json parte o site (fatal json_decode(): array given)	Alguns plugins guardam a config como string JSON literal em wp_options (o próprio plugin faz json_decode() sobre ela). --format=json faz o WP-CLI decodificar o input e gravar o array PHP resultante (serializado), não a string — o plugin recebe um array onde esperava string e crasha no bootstrap, ANTES de qualquer comando conseguir corrigir (inclui wp cache flush, que também precisa de arrancar o WP)	Verificar sempre wp option get NOME --format=json primeiro: resultado entre aspas escapadas "{...}" = string (editar com wp db query "UPDATE wp_options SET option_value='...' WHERE option_name='NOME'", nunca --format=json); resultado sem aspas exteriores = já é array. Se ficar preso (site em baixo, wp cache flush também crasha) e o site tiver Redis/Memcached object cache, o valor corrompido fica cacheado e bloqueia até o WP arrancar — limpar directo com redis-cli -n DB flushdb (não precisa de WP a correr) antes de repetir a correcção

---

Diagnóstico Rápido

# Informações completas do ambiente
wp --info --allow-root --path=$PATH

# Verificar conectividade BD
wp db check --allow-root --path=$PATH

# Ver configuração PHP activa
wp eval 'echo PHP_VERSION."\n".php_ini_loaded_file()."\n".ini_get("memory_limit")."\n";' --allow-root --path=$PATH

# Ver URL e email admin
wp option get siteurl --allow-root --path=$PATH
wp option get admin_email --allow-root --path=$PATH

# Listar utilizadores admin
wp user list --role=administrator --allow-root --path=$PATH

---

Recursos Adicionais

Scripts

• scripts/wp-auto.sh — Auto-detecta PHP do utilizador e executa WP-CLI com a versão correcta

Referências

• references/commands.md — Referência completa: todos os comandos com flags, WooCommerce CLI, options, wp eval avançado

Documentação Hub

• Manual: Hub/06-Operacoes/Documentacao/Manuais/WP-CLI no CWP.md
• NotebookLM: WordPress Config CLI
• Skill relacionada: /rank-math — operações Rank Math SEO via WP-CLI

---

WP-CLI no CWP | Descomplicar® | v1.0.0 | 18-02-2026

---

Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

{"date":"2026-08-16","issue":"wp option update WpFastestCache --format=json gravou array PHP serializado em vez de string JSON; o proprio plugin faz json_decode() sobre o valor e partiu com TypeError fatal no bootstrap do WP, derrubando o site (emanuelalmeida.pt); Redis object cache tinha o valor corrompido cacheado, bloqueando ate wp cache flush (que tambem precisa arrancar o WP)","fix":"nunca usar wp option update --format=json para opcoes que o plugin le como string JSON bruta; editar via wp db query UPDATE wp_options SET option_value=... (sempre string literal, nunca decodificado); se object cache (Redis/Memcached) tiver o valor mau cacheado e qualquer comando wp-cli crashar, limpar directo via redis-cli -n DB flushdb (bypassa o bootstrap do WP por completo) antes de tentar de novo","source":"auto"}
{"date":"2026-08-16","issue":"wp elementor flush_css limpa TODO o directorio uploads/elementor/css/, nao so a pagina visada; um flush pontual para corrigir 1 pagina (post-9.css 404) reintroduziu 404 noutra pagina ja corrigida antes na mesma sessao (post-6.css)","fix":"apos qualquer flush_css, loop curl por TODOS os permalinks publicados (wp post list --field=url) para regenerar tudo; verificar content-type text/css (nao text/html) em cada ficheiro; purgar Cloudflare 2x se persistir 404 no edge apos origem ja estar OK","source":"auto"}

Adicionar nova linha após cada erro corrigido.