WP-CLI para Quem Vive no Terminal

O WP-CLI é a interface de linha de comando para uma instalação WordPress. Ele economiza cliques, mas o verdadeiro motivo para aprendê-lo é o conjunto de tarefas para as quais o painel administrativo não tem tela alguma: reescrever dados serializados de opções durante uma troca de domínio, executar PHP arbitrário contra um site em produção e atualizar dez instalações a partir de um único prompt.

A maioria das pessoas conhece a ferramenta numa emergência. Uma atualização de plugin derruba o admin, o painel não carrega e, de repente, FTP mais phpMyAdmin é o único caminho de volta. Esse caminho funciona, mas é lento e exige certa coragem.

Este artigo está organizado por tarefa, não por namespace. Cada seção é uma atividade que é dolorosa ou impossível no painel, seguida do comando que a resolve e das flags que a tornam segura.

Esses Comandos São Executados Imediatamente

Não há diálogo de confirmação, tela de pré-visualização nem desfazer. O wp search-replace escreve em todas as linhas correspondentes no instante em que você pressiona enter. O wp plugin deactivate --all desativa tudo em um site de produção com a mesma facilidade com que faria em um laptop. O único rollback que você tem é o export do banco de dados feito previamente, então faça um.

Como Trocar de Domínio Sem Quebrar Dados Serializados?

O wp search-replace é a ferramenta certa para uma troca de domínio: ele lê PHP serializado corretamente e não mexe nas chaves primárias, e nenhuma dessas duas coisas um find-and-replace SQL simples consegue fazer. O motivo está no formato de armazenamento: a função serialize() do PHP registra uma string como o seu comprimento em bytes seguido da própria string.

a:1:{s:3:"url";s:27:"https://staging.example.com";}

Um UPDATE ... REPLACE() SQL às cegas reescreve a URL para https://example.com e deixa o 27 intacto. O comprimento declarado não corresponde mais ao conteúdo, o PHP não consegue mais desserializar o valor, e o widget ou opção de plugin que vivia ali silenciosamente volta a ser nada. O WP-CLI desserializa a estrutura, substitui dentro dela e serializa novamente com os comprimentos corretos.

Escale em três etapas:

# 1. report what would change; writes nothing
wp search-replace 'https://staging.example.com' 'https://example.com' \
  --skip-columns=guid --dry-run

# 2. optional: write the result to a SQL file instead of the database
wp search-replace 'https://staging.example.com' 'https://example.com' \
  --skip-columns=guid --export=migration.sql

# 3. apply it
wp search-replace 'https://staging.example.com' 'https://example.com' \
  --skip-columns=guid

O --dry-run executa o trabalho inteiro e imprime o relatório, depois descarta as alterações. O --export envia o resultado para um arquivo SQL e deixa o banco de dados em produção intocado, permitindo que você leia o diff ou o aplique em outro lugar. Pule a coluna guid porque o WordPress trata o guid de um post como fixo por toda a vida do post: altere-o e leitores de feed podem exibir todo o seu acervo antigo como novidade.

Para dados aninhados problemáticos, adicione --precise. Por padrão, o comando usa consultas SQL rápidas e muda automaticamente para PHP em colunas que contêm dados serializados; o --precise força o uso de PHP em todas as colunas, o que é mais lento, porém mais confiável diante de estruturas serializadas complexas. O modo regex também é substancialmente mais lento, então recorra a ele apenas quando uma string literal não resolver.

Como Atualizar Plugins e o Core em Vários Sites?

Um comando atualiza tudo que tiver atualização disponível, sem paginação de painel e sem checkboxes por plugin:

wp plugin update --all
wp core update
wp core update-db

O wp core update-db executa a rotina de atualização do banco de dados do WordPress, que é a etapa que o painel realiza para você na tela de upgrade após uma atualização do core. Rode-o depois do wp core update para que a atualização termine, em vez de ficar pela metade.

Combinada com os aliases abordados adiante, a mesma linha se torna wp @all plugin update --all e atinge, em sequência, todas as instalações que você mantém.

Exporte Antes, Importe Depois

O wp db export chama o mysqldump e obtém host, nome, usuário e senha do banco a partir do wp-config.php, de modo que você nunca digita dados de conexão. Informe um nome de arquivo explícito; se omitir, ele grava {dbname}-{Y-m-d}-{random-hash}.sql.

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

Restaurar é a imagem espelhada:

wp db import backup-20250413-141055.sql

O wp db import aceita tanto um nome de arquivo quanto entrada via pipe, de modo que você pode enviar um export direto de um host para outro por ssh. Para uma estratégia de prazo mais longo do que um único dump antes de uma alteração arriscada, os artigos da OpenReplay sobre backup no WordPress cobrem agendamento e armazenamento externo.

Como Voltar a Entrar em um Site do Qual Você Foi Bloqueado?

Três comandos cobrem quase todo bloqueio de acesso, na ordem em que você os executaria sob pressão. Crie um administrador novo, redefina a senha de um usuário existente ou tire os plugins completamente da jogada:

wp user create ops ops@example.com --role=administrator
wp user reset-password admin --show-password --skip-email
wp plugin deactivate --all

O wp user reset-password gera uma nova senha; --show-password a imprime no terminal e --skip-email impede que a notificação vá para uma caixa de entrada que talvez você não controle. O wp plugin deactivate aceita --all para desativar tudo, além de --exclude=<name> para manter ativa uma lista separada por vírgulas.

Quando o que quebrou o admin foi um erro fatal em um plugin, o WP-CLI pode falhar no bootstrap pelo mesmo motivo que o site falha. O parâmetro global --skip-plugins impede que todos os plugins, ou uma lista nomeada, sejam carregados durante a execução do comando:

wp plugin deactivate broken-plugin --skip-plugins

Pular não altera o estado armazenado; um plugin ignorado dessa forma continua reportando como ativo. Isso apenas lhe garante um bootstrap funcional para que a desativação possa ocorrer. Também não ajuda quando o código fatal está em um mu-plugin, porque o WP-CLI carrega mu-plugins de qualquer forma. Este é o momento em que a maioria dos mantenedores precisa do WP-CLI pela primeira vez, e é mais rápido do que abrir um cliente FTP e renomear diretórios de plugins. Uma vez que o admin esteja de volta, a metade diagnóstica do trabalho é abordada no artigo da OpenReplay sobre a tela branca da morte do WordPress.

Executando PHP Pontual com wp eval

O wp eval executa PHP arbitrário contra uma instalação WordPress totalmente carregada. Não há equivalente no painel, e é justamente esse o ponto: qualquer função que um plugin registre, qualquer opção, qualquer consulta, vira um one-liner.

wp eval 'echo get_option( "siteurl" );'
wp eval 'echo count( get_users( [ "role" => "administrator" ] ) );'

Qualquer coisa mais longa pertence a um arquivo. O wp eval-file recebe o caminho de um arquivo PHP, entrega quaisquer argumentos posicionais extras ao script como $args e pula completamente o bootstrap do WordPress se você passar --skip-wordpress. Seu código roda dentro de um método, então cada global que você tocar precisa da sua própria linha global.

Não existe dry run para o wp eval. O que quer que o script escreva, ele escreve. Esse é o argumento mais claro a favor do export.

Como Executar o WP-CLI Contra um Host Remoto?

É aqui que a ferramenta deixa de ser apenas uma conveniência. O parâmetro global --ssh do WP-CLI tem o formato --ssh=[<scheme>:][<user>@]<host>[:<port>][<path>] e funciona entregando o seu comando ao binário ssh, que por sua vez o repassa ao WP-CLI instalado do outro lado.

wp --ssh=dev_user@example.com:2222~/webapps/production plugin list

O caminho não leva separador. Escreva-o logo após a porta, ou logo após o host se você omitiu a porta, e comece-o com / ou ~. Além de ssh, a referência de configuração do handbook documenta vagrant, docker, docker-compose e docker-compose-run. Este último inicia um container novo com docker-compose run, em vez de usar um que já esteja em execução.

Há um pré-requisito absoluto: o servidor remoto precisa do seu próprio WP-CLI, e ele tem que responder por wp. Um wp que funciona quando você faz login manualmente ainda pode retornar command-not-found via --ssh, porque o shell que executa um comando remoto não monta o mesmo $PATH. A maioria das distribuições coloca uma verificação no topo do ~/.bashrc que encerra o script cedo quando o shell não é interativo, de modo que qualquer linha de PATH abaixo dela nunca é executada; o zsh, nessa situação, lê o ~/.zshenv em vez do ~/.zshrc. A solução é definir o $PATH explicitamente no lado remoto.

Digitar essa string duas vezes já é o bastante. Registre aliases no wp-cli.yml do seu projeto ou no seu ~/.wp-cli/config.yml global:

@prod:
  ssh: deploy@example.com~/webapps/production
@stage:
  ssh: deploy@staging.example.com~/webapps/staging
@all:
  - @prod
  - @stage

wp @prod plugin update --all
wp @all core check-update

Um grupo de aliases executa uma única invocação contra várias instalações, o que é a diferença entre manter dez sites de clientes e logar em dez painéis. Para uma instalação local que não está no seu diretório atual, o parâmetro global --path informa ao WP-CLI onde estão os arquivos do WordPress:

wp --path=/var/www/example.com/htdocs plugin update --all

Para Onde Ir Agora

A única ideia que vale a pena levar daqui: o WP-CLI entende as estruturas de dados do WordPress, e o mysql e o phpMyAdmin não, e é por isso que uma troca de domínio pertence ao wp search-replace e a nenhum outro lugar. Escolha a próxima migração que você tem agendada, escreva a linha com --dry-run, leia o relatório e execute wp db export antes de remover a flag. Tudo o que foi descrito acima é irreversível no instante em que você pressiona enter.

Perguntas Frequentes

O wp search-replace atualiza todos os sites de uma rede multisite?

Não. Ele atua nas tabelas que o próprio WordPress registra, então em multisite você obtém apenas as tabelas do site atual, a menos que adicione --network. Para alcançar todas as tabelas do banco de dados, qualquer que seja o prefixo e independentemente de o WordPress conhecê-las ou não, use --all-tables, que tem prioridade sobre --network e --all-tables-with-prefix. Em uma rede, adicione também --url para que o WP-CLI inicialize no site correto.

Por que o WP-CLI se recusa a rodar como root?

O WP-CLI para com um erro YIKES quando detecta o usuário root. Tudo dentro da instalação, incluindo plugins e temas que você não escreveu, herdaria o alcance do root sobre o servidor, de modo que um único trecho de código hostil poderia dominar a máquina inteira. A flag --allow-root pula essa verificação e containers rodando como root frequentemente precisam dela, mas o projeto desaconselha seu uso. Em vez disso, execute como o usuário de sistema dono dos arquivos do WordPress.

O que significa o erro 'This does not seem to be a WordPress installation'?

O WP-CLI não encontrou arquivos do core do WordPress onde procurou, então nunca fez o bootstrap. Execute o comando a partir do diretório que contém wp-admin, wp-content e wp-includes, ou aponte para a instalação com o parâmetro global --path. Passe o valor na forma com sinal de igual, --path=/var/www/html, porque um argumento separado por espaço deixa a flag sem valor e o mesmo erro se repete.

O WP-CLI roda no Windows?

O WP-CLI é feito para um ambiente UNIX-like como Linux, macOS, FreeBSD ou Cygwin, e tem suporte apenas parcial no Windows em si, então WSL ou Cygwin é o caminho confiável em uma máquina Windows. Ele também requer WordPress 4.9 ou mais recente, e qualquer versão anterior à release atual do WordPress pode não funcionar plenamente.