WP-CLI: Comandos Essenciais Para Desenvolvedores WordPress

Depois de configurar mais de 300 sites em WordPress aqui na Weboption, posso afirmar com segurança: desenvolvedores que ainda não usam WP-CLI no dia a dia estão perdendo tempo e ganhando dor de cabeça. A interface de linha de comando oficial do WordPress transforma tarefas que consumiriam cinco minutos no painel em segundos de terminal. Este guia cobre os comandos que nossa equipe usa toda semana, desde atualizar o core até criar comandos customizados para automações específicas de cada projeto.

O que é WP-CLI e por que ele importa para desenvolvimento profissional

WP-CLI é a ferramenta de linha de comando para gerenciar instalações WordPress sem precisar abrir o navegador. Com ela, você executa atualizações, manipula banco de dados, gerencia usuários e muito mais diretamente pelo terminal. Segundo dados do próprio repositório oficial, o WP-CLI tem mais de 10 milhões de downloads mensais e é usado por empresas como Pantheon, WP Engine e Automattic em seus pipelines de deploy.

A instalação é simples. Baixe o arquivo Phar, mova para um diretório do PATH e pronto:

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

Em ambientes gerenciados como Kinsta, WP Engine e SiteGround, o WP-CLI já vem pré-instalado via SSH. Nesses casos, verifique a versão com wp --version antes de continuar.

Gerenciando o core do WordPress com wp core

O grupo de comandos wp core cobre tudo relacionado ao núcleo do WordPress, do download inicial à verificação de integridade dos arquivos. Para verificar a versão instalada e checar se há atualizações disponíveis:

wp core version
wp core check-update

Para atualizar o core sem precisar do painel:

wp core update
wp core update-db

O comando wp core update-db é frequentemente esquecido depois de atualizar o WordPress. Sem ele, tabelas do banco de dados ficam desatualizadas, o que causa comportamentos imprevisíveis em versões maiores. Erro clássico que vemos em projetos que chegam para nós depois de uma migração mal executada.

Para instalar o WordPress do zero em um diretório vazio, o fluxo completo fica assim:

wp core download --locale=pt_BR
wp config create --dbname=meu_banco --dbuser=usuario --dbpass=senha
wp core install --url=meusite.com.br --title="Meu Site" --admin_user=admin --admin_password=senhaforte [email protected]

Esse processo que levaria uns dez minutos pelo painel fica pronto em menos de 30 segundos. Multiplicado por dezenas de projetos por mês, o ganho de tempo é real.

Plugins e temas: instalação, ativação e auditoria em segundos

Os comandos wp plugin e wp theme são provavelmente os mais usados no cotidiano de qualquer desenvolvedor. Instalar e ativar um plugin sem passar pelo painel:

wp plugin install woocommerce --activate
wp plugin install advanced-custom-fields --activate

Para listar todos os plugins instalados com status e versão:

wp plugin list

A saída mostra nome, status (active, inactive, must-use), versão instalada e versão disponível. Excelente para auditar um site cliente que você acabou de receber. Em média, nos sites que chegam para auditoria na Weboption, encontramos 4 a 7 plugins inativos que nunca foram removidos, e pelo menos 2 desatualizados com vulnerabilidades conhecidas.

Para atualizar todos os plugins de uma vez:

wp plugin update --all

Com temas, o fluxo é idêntico:

wp theme install astra --activate
wp theme list
wp theme update --all

Uma prática que adotamos nos nossos projetos é rodar wp plugin list --status=inactive --format=csv antes de entregar qualquer site. Plugins inativos ocupam espaço, podem ter vulnerabilidades e confundem quem vai manter o site depois.

Banco de dados: export, import e search-replace

Os comandos de banco de dados são onde o WP-CLI realmente brilha. Fazer export e import de banco pelo phpMyAdmin em sites grandes é sofrimento puro. Com WP-CLI, fica limpo:

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

O export gera um arquivo.sql no diretório atual, com nome de data automático se você usar a variável do shell. Para sites com banco acima de 1 GB (o que é mais comum do que parece em e-commerces com histórico longo), o WP-CLI processa sem timeout, coisa que o phpMyAdmin simplesmente não consegue.

O comando que salva migrações inteiras é o wp search-replace. Depois de mover um site de domínio, todas as URLs antigas ficam no banco. O comando trata isso, inclusive dentro de dados serializados do PHP, que é onde a maioria das ferramentas manuais quebra:

wp search-replace 'http://site-antigo.com.br' 'https://site-novo.com.br' --all-tables

Use sempre a flag --dry-run primeiro para ver quantas substituições serão feitas sem modificar nada:

wp search-replace 'http://site-antigo.com.br' 'https://site-novo.com.br' --all-tables --dry-run

Migrações sem --dry-run são aposta. Já resgatamos projetos de outras agências onde o search-replace trocou strings dentro de campos JSON, quebrando configurações de plugins inteiros. O dry-run custa 5 segundos e evita horas de depuração.

Posts, usuários, cache e cron

O grupo wp post permite criar, editar e deletar conteúdo por linha de comando. Útil para importar conteúdo em massa ou criar posts de teste:

wp post create --post_title="Teste" --post_status=publish --post_type=post
wp post list --post_status=publish --post_type=post --format=table

Para usuários, wp user cobre criação, listagem e redefinição de senha. Redefinir a senha de admin quando o cliente perdeu o acesso:

wp user update admin --user_pass=nova_senha_aqui

Criar um novo admin:

wp user create novo_admin [email protected] --role=administrator --user_pass=senha_segura

Cache: qualquer desenvolvedor que trabalha com plugins de cache sabe que flush manual pelo painel nem sempre funciona direito. Via WP-CLI:

wp cache flush
wp transient delete --all

Para sites usando object cache (Redis, Memcached), o wp cache flush limpa o cache de objetos do WordPress. Em conjunto com o flush do plugin de cache de página, resolve 90% dos problemas de conteúdo desatualizado que clientes relatam.

O WP-Cron merece atenção especial. Em sites de alto tráfego, o cron nativo do WordPress (que dispara em requisições de página) é problemático. Para listar eventos agendados e executar manualmente:

wp cron event list
wp cron event run --due-now

Sites com menos de 500 visitas diárias frequentemente têm jobs de cron atrasados simplesmente porque não há tráfego suficiente para disparar o cron. Nesses casos, configuramos um cron real do servidor apontando para wp cron event run --due-now.

Criando comandos WP-CLI customizados

Criar comandos próprios é onde o WP-CLI se torna uma plataforma de automação. Para projetos com tarefas repetitivas específicas, como gerar relatórios de pedidos WooCommerce ou sincronizar dados com APIs externas, um comando customizado é a solução certa.

A estrutura básica em um plugin ou em functions.php:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
class Weboption_CLI_Commands {
public function limpar_rascunhos( $args, $assoc_args ) {
$posts = get_posts([
'post_status' => 'draft',
'post_type' => 'post',
'numberposts' => -1,
]);
foreach ( $posts as $post ) {
wp_delete_post( $post->ID, true );
WP_CLI:line( "Deletado: {$post->post_title}" );
}
WP_CLI:success( count( $posts ). ' rascunhos removidos.' );
}
}
WP_CLI:add_command( 'weboption', 'Weboption_CLI_Commands' );
}

Com isso, o comando fica disponível como:

wp weboption limpar_rascunhos

Aqui na Weboption, temos um conjunto de comandos internos para onboarding de sites novos: verificar configurações de segurança, limpar plugins de demonstração, configurar permalinks e gerar o primeiro backup. O que era um checklist de 20 minutos virou um único comando que roda em 45 segundos.

Para comandos que recebem parâmetros, use $assoc_args:

wp weboption limpar_rascunhos --antes-de=2025-01-01

Erro que vemos sempre: usar WP-CLI sem entender o contexto de usuário

O erro mais comum que encontramos em times que estão começando com WP-CLI é rodar comandos sem especificar o usuário do WordPress. Alguns comandos, especialmente relacionados a capacidades e permissões, precisam de contexto de usuário. Use a flag --user:

wp post create --post_title="Teste" --post_status=publish --user=admin

O segundo erro frequente é rodar comandos em ambiente de produção sem verificar em qual instalação o WP-CLI está apontando. Em servidores com múltiplos sites WordPress, o --path é obrigatório:

wp plugin update --all --path=/var/www/html/meusite

Já corrigimos situações onde um desenvolvedor atualizou plugins no site errado por omitir o --path. O dano foi pequeno nesse caso, mas poderia ser catastrófico.

Perguntas frequentes

WP-CLI funciona em qualquer hospedagem WordPress?

Funciona em qualquer hospedagem que ofereça acesso SSH. Hospedagens compartilhadas básicas muitas vezes bloqueiam SSH ou não têm PHP no PATH do shell. Hospedagens gerenciadas como Kinsta, WP Engine, Cloudways e Siteground já têm WP-CLI disponível via SSH sem configuração adicional.

Como usar WP-CLI no desenvolvimento local com LocalWP ou Docker?

No LocalWP, o WP-CLI está disponível via menu de contexto do site ou pelo terminal integrado. No Docker, você executa os comandos dentro do container: docker exec -it nome_container wp plugin list. Em ambos os casos, o WP-CLI funciona normalmente sem configuração extra.

WP-CLI pode ser usado em automações e CI/CD?

Sim, e é um dos usos mais poderosos. Em pipelines de deploy, comandos como wp core update-db, wp cache flush e wp search-replace são executados automaticamente após cada deploy. Ferramentas como GitHub Actions, Bitbucket Pipelines e DeployHQ suportam execução de comandos SSH onde o WP-CLI roda normalmente.

Existe risco de usar wp search-replace no banco de produção?

Existe, mas é gerenciável. Sempre faça um wp db export antes e use --dry-run para visualizar as mudanças. O WP-CLI trata dados serializados corretamente, o que ferramentas de search-replace genéricas não fazem, mas uma string mal escolhida pode causar substituições indesejadas em campos inesperados.

Como ver todos os comandos disponíveis no WP-CLI?

Use wp help para a lista completa de grupos de comandos, e wp help nome_do_comando para detalhes de um comando específico. O site oficial wp-cli.org tem documentação completa com exemplos para cada comando e subcomando disponível.