14 min. ler

WP-CLI: o guia completo para gerenciar o WordPress a partir da linha de comando

WP-CLI é a ferramenta oficial de linha de comando para gerenciar instalações do WordPress diretamente do seu terminal, sem precisar abrir um navegador. Se você já passou uma tarde clicando no painel de administração do WordPress para atualizar plug-ins em vários sites, já sabe por que essa ferramenta existe.

Neste guia, você aprenderá tudo, desde a instalação do WP-CLI no Linux, macOS e Windows até a automatização de tarefas de manutenção complexas com scripts e arquivos de configuração. Quer você esteja gerenciando um único blog ou dezenas de sites de clientes, dominar o WP-CLI mudará fundamentalmente a forma como você trabalha com o WordPress.

O que você aprenderá:

Como instalar e configurar o WP-CLI em diferentes sistemas operacionais
Comandos essenciais para gerenciar plug-ins, temas, usuários e conteúdo
Operações de banco de dados, incluindo exportações, importações e busca e substituição seguras
Técnicas de automação usando scripts, aliases e cron jobs
Práticas recomendadas para evitar armadilhas comuns ao trabalhar no terminal

O que é WP-CLI? (Explicação rápida primeiro)

WP-CLI é a sigla de WordPress Command Line Interface, uma ferramenta de código aberto que permite que você gerencie sites do WordPress totalmente a partir do terminal. Em vez de fazer login no wp-admin e navegar pelos menus, você executa comandos como wp plugin update --all e vê toda a sua pilha de plugins ser atualizada em segundos.

O projeto começou por volta de 2011, criado por desenvolvedores que queriam uma maneira mais rápida de gerenciar o WordPress em escala. Em 2017, ele passou para o âmbito oficial do WordPress.org e agora é mantido por uma equipe dedicada de colaboradores, incluindo Alain Schlesser e Daniel Bachhuber.

Aqui está o que você precisa saber sobre o WP-CLI:

Versão estável atual: Série WP-CLI 2.x
Compatibilidade com o WordPress: Funciona com o WordPress 5.x até o 6.x (e historicamente até o 3.7)
Requisitos do PHP: PHP 7.4+ ou 8.x recomendado para segurança e desempenho
Ecossistema de comandos: Mais de 40 comandos principais que abrangem praticamente todas as operações do WordPress
Usuários principais: Desenvolvedores, agências, engenheiros de DevOps e usuários avançados que gerenciam sites complexos ou múltiplos
Distribuição: Disponível como um arquivo PHAR, por meio de gerenciadores de pacotes ou pré-instalado em muitos hosts WordPress gerenciados

Principais benefícios do uso do WP-CLI

Quando você entender por que o WP-CLI existe, a curva de aprendizado se tornará muito mais fácil de justificar. Esta seção explica as vantagens concretas que fazem com que essa ferramenta valha o seu tempo.

Economia de tempo em tarefas repetitivas
Atualizar 20 plug-ins por meio do painel do WordPress significa 20 carregamentos de página, 20 cliques e a observação de 20 barras de progresso. Com o WP-CLI, você executa o wp plugin update --all uma vez e segue em frente. Para agências que gerenciam sites de vários clientes, essa diferença se traduz em horas economizadas toda semana.

Operações em massa e automatizadas
Considere um cenário em que você está preparando 15 lojas do WooCommerce para a Black Friday. Você precisa atualizar plug-ins, limpar caches e verificar a integridade do banco de dados em cada site. O WP-CLI permite que você crie o script de toda essa sequência e a execute em todos os sites em minutos, em vez de horas. Os principais recursos de automação incluem:

Atualização de todos os plug-ins em várias instalações com um único script
Criação de usuários em massa com funções predefinidas
Execução de manutenção noturna via cron (otimização do banco de dados, limpeza transitória)
Implantação de configurações idênticas do WordPress em novos ambientes

Confiabilidade das operações baseadas no navegador
As operações do navegador atingem tempos limite de HTTP. As importações de grandes bancos de dados falham no meio do processo. As operações de pesquisa e substituição corrompem os dados serializados quando feitas com SQL bruto. O WP-CLI evita todos esses problemas porque é executado diretamente no servidor, sem restrições de tempo limite, e seu comando search-replace lida corretamente com estruturas de dados serializadas.

Controle direto sobre os principais sistemas do WordPress
A partir de um terminal, você pode:

Exportar e importar o banco de dados do WordPress
Modificar as configurações do site wp-config.php
Inspecionar e acionar eventos do wp-cron
Ativar e desativar o modo de manutenção
Executar código PHP arbitrário no contexto do WordPress

Redução da carga no wp-admin
Em servidores de produção ocupados, cada carregamento de página do painel de administração consome recursos. A execução de operações de manutenção via WP-CLI mantém essa carga fora do servidor da Web, o que é importante durante períodos de alto tráfego.

Requisitos do WP-CLI e ambientes compatíveis

Antes de instalar o WP-CLI, você precisa confirmar se o seu servidor ou ambiente local atende aos requisitos básicos. A boa notícia é que a maioria das configurações modernas do WordPress já está qualificada.

Requisitos da versão do PHP:

Mínimo: PHP 5.6 (embora esteja desatualizado)
Recomendado: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 ou 8.5 para segurança e desempenho em 2026

Compatibilidade com a versão do WordPress:

Suporte histórico: WordPress 3.7 e mais recentes
Alvo moderno: WordPress 5.0 a 6.7+ para projetos atuais

Expectativas do sistema operacional:

Melhor suporte: Sistemas do tipo UNIX (Ubuntu 22.04 LTS, Debian 12, CentOS Stream, macOS)
Windows: Suportado via WSL (Subsistema Windows para Linux) ou instalação nativa do PHP

Requisitos adicionais:

PHP disponível na linha de comando (o binário php deve estar em seu PATH)
cURL ou wget para fazer o download do arquivo wp-cli.phar
Acesso SSH para servidores remotos (a maioria dos planos de hospedagem gerenciada do WordPress inclui isso por padrão)

Muitos hosts populares, como Kinsta, SiteGround e DreamHost, agora vêm com o WP-CLI pré-instalado. O WordPress.com também inclui o WP-CLI para sites com acesso SSH ativado.

Como instalar o WP-CLI no Linux e no macOS

O método de instalação padrão usa o arquivo PHAR (PHP Archive) oficial. Esse processo funciona nos terminais Ubuntu, Debian, CentOS, Fedora e macOS.

Etapa 1: Faça o download do arquivo PHAR
Abra o terminal e faça o download de wp-cli.phar usando curl:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Como alternativa, use o wget:

wget https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Etapa 2: verificar o download (opcional, mas recomendado)
Verifique a soma de verificação SHA-256 em relação ao valor oficial publicado na documentação do WP-CLI para garantir que o arquivo não tenha sido adulterado durante o download:

sha256sum wp-cli.phar

Compare a saída com a soma de verificação listada no site oficial do WP-CLI.

Etapa 3: Teste o arquivo PHAR
Confirme se o arquivo php funciona:

php wp-cli.phar --info

Você deverá ver a saída exibindo a versão do WP-CLI, a versão do PHP e as informações do sistema.

Etapa 4: Torne-o executável e mova-o para o PATH
Marque o arquivo como executável e mova-o para um diretório no PATH do sistema:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

O comando sudo é normalmente necessário porque /usr/local/bin é um diretório do sistema. Evite instalar o WP-CLI como root se você for executá-lo principalmente como um usuário comum.

Etapa 5: Verifique a instalação global
Confirme se o WP-CLI está agora disponível globalmente:

wp --info
wp cli version

Você deverá ver a saída confirmando a versão do wp cli, o local do binário do PHP e os detalhes do sistema operacional. Nesse ponto, você tem o WP-CLI instalado e pronto para ser usado.

Como instalar o WP-CLI no Windows

Os usuários do Windows têm dois caminhos principais: usar o Windows Subsystem for Linux (WSL) ou configurar uma instalação nativa do Windows. O WSL proporciona uma experiência mais semelhante à do Linux e é geralmente recomendado.

Opção 1: usando a WSL (recomendado)
Primeiro, habilite a WSL no Windows 10 ou 11:

wsl --install

Instale o Ubuntu a partir da Microsoft Store e, em seguida, inicie o terminal do Ubuntu. A partir daí, siga exatamente as mesmas etapas de instalação do Linux descritas na seção anterior – baixe o arquivo phar, torne-o executável e mova-o para /usr/local/bin/wp.

Opção 2: Instalação nativa no Windows
Para uma configuração nativa, você precisa ter o PHP para Windows instalado com o executável php disponível no PATH do sistema.

Faça o download e instale o PHP no site oficial do PHP para Windows
Adicione o diretório PHP à variável de ambiente PATH do Windows
Para confirmar que o PHP funciona, abra o prompt de comando e execute php -v

Em seguida, faça o download do arquivo PHAR do WP-CLI:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

O Windows inclui o curl por padrão desde 2018, portanto, isso deve funcionar sem configuração adicional. Crie uma pasta para o WP-CLI (por exemplo, C:\wp-cli) e mova o arquivo baixado para lá.

Em seguida, crie um arquivo de wrapper em lote chamado wp.bat na mesma pasta:

@echo off
php "C:\wp-cli\wp-cli.phar" %*

Adicione C:\wp-cli à variável de ambiente PATH do sistema. Agora, abra uma nova janela do prompt de comando ou do PowerShell e verifique:

wp --info

Você deverá ver a versão do WP-CLI e os detalhes do ambiente, confirmando que o WP-CLI está instalado corretamente.

Uso básico do WP-CLI e obtenção de ajuda

Com o WP-CLI instalado, você precisa entender o padrão de comando básico antes de mergulhar em operações específicas. Todos os comandos do WP-CLI seguem essa estrutura:

wp <command> <subcommand> [options]

Os comandos são executados em um diretório de instalação do WordPress – a pasta que contém wp-config.php. Se estiver em outro lugar, você pode especificar o caminho com --path=/var/www/html/mysite.

Verificação do ambiente
Comece confirmando a configuração que você fez:

wp --info

Isso exibe a versão do WP-CLI, a versão do PHP, o caminho binário do PHP, o sistema operacional e outros detalhes do ambiente. Para ver apenas a versão do WP-CLI:

wp cli version

Explorando os comandos disponíveis
Para listar todos os comandos disponíveis do wp cli, você pode usar o comando wp cli:

wp help

Para obter ajuda sobre um comando específico:

wp help plugin
wp help core update

Você também pode anexar --help a qualquer comando:

wp user --help

A saída da ajuda é exibida em um pager semelhante às páginas de manual do Unix. Pressione q para sair.

Primeiros comandos para você experimentar:

wp core version – exibe sua versão do WordPress
wp plugin list – mostra todos os plug-ins do WordPress instalados com seu status
wp theme list – mostra os temas instalados
wp user list – lista todos os usuários do site

Esses comandos somente leitura permitem que você explore o site do WordPress sem alterar nada, o que é perfeito para se familiarizar com a interface.

Instalando e configurando o WordPress com o WP-CLI

O WP-CLI pode executar uma nova instalação completa do WordPress mais rapidamente do que o instalador tradicional baseado na Web. Isso é especialmente valioso quando você está criando ambientes de desenvolvimento ou implantando novos sites de forma programática.

Pré-requisitos
Antes de executar os comandos de instalação, você precisa de um banco de dados MySQL ou MariaDB pronto. Para este exemplo, suponha que você tenha criado:

Nome do banco de dados: wpsite_db
Usuário do banco de dados: wpsite_user
Senha: securepassword123
Anfitrião: localhost

Etapa 1: Faça o download dos arquivos principais do WordPress
Navegue até o diretório de instalação desejado e faça o download do núcleo do WordPress:

wp core download

Isso busca a versão mais recente do WordPress. Para especificar uma versão ou localidade:

wp core download --version=6.4.2 --locale=fr_FR

Após a conclusão, você verá a confirmação de que o download do WordPress foi bem-sucedido.

Etapa 2: Gerar wp-config.php
Crie o arquivo de configuração usando wp config create:

wp config create --dbname=wpsite_db --dbuser=wpsite_user --dbpass=securepassword123 --dbhost=localhost

Isso gera um wp-config.php completo com suas credenciais de banco de dados e sais de segurança gerados automaticamente.

Etapa 3: Execute a instalação
Agora, instale o WordPress com os detalhes do seu site:

wp core install --url=https://example.com --title="My New Site" --admin_user=admin --admin_password=strongpassword [email protected]

Você verá a mensagem “WordPress installed successfully” e seu site estará pronto para ser usado.

Instalação em vários sites
Para redes WordPress em vários sites, use a variante multisite. O WP-CLI pode configurar instalações em vários sites com:

wp core multisite-install --url=https://example.com --title="My Network" --admin_user=admin --admin_password=strongpassword [email protected]

Gerenciando temas com o WP-CLI

O WP-CLI lida com todas as operações de tema sem exigir acesso ao painel de administração do WordPress. Você pode listar, instalar, ativar, atualizar e excluir temas diretamente do seu terminal.

Listagem de temas instalados
Para ver todos os temas instalados atualmente:

wp theme list

Exemplo de saída:

nome	status	atualização	versão
vinte e vinte e quatro	ativo	none	1.0
vinte e vinte e três	inativo	none	1.2
astra	inativo	disponível	4.5.0

Ativação de um tema
Mude para um tema diferente:

wp theme activate astra

Isso altera imediatamente o tema ativo. Se você voltar a um tema padrão, será útil para solucionar problemas relacionados ao tema:

wp theme activate twentytwentyfour

Instalação de novos temas
Instale um tema do repositório do WordPress.org. Você pode instalar um tema do repositório do WordPress.org:

wp theme install astra

Instale e ative em um único comando:

wp theme install astra --activate

Atualização de temas
Atualize um tema específico:

wp theme update astra

Ou atualize todos os temas de uma vez:

wp theme update --all

Exclusão de temas
Remova um tema que você não precisa mais:

wp theme delete twentytwentythree

Gerenciando plug-ins com o WP-CLI

É no gerenciamento de plug-ins que o WP-CLI economiza mais tempo. Você pode realizar operações em massa que exigiriam dezenas de cliques no painel.

Listando plug-ins

wp plugin list

Exemplo de saída:

nome	status	atualização	versão
woocommerce	ativo	none	8.5.1
yoast-seo	ativo	disponível	21.0
elementar	inativo	none	3.18.0

Instalação de plug-ins
Instale um plug-in por seu slug:

wp plugin install woocommerce

Instale e ative:

wp plugin install yoast-seo --activate

Ativação e desativação
Ative um plug-in:

wp plugin activate elementor

Desativar um plug-in (útil para depuração):

wp plugin deactivate elementor

Desative todos os plug-ins de uma só vez (o que salva a vida na depuração da “Tela Branca da Morte”):

wp plugin deactivate --all

Atualização de plug-ins
Atualize um plug-in específico:

wp plugin update yoast-seo

Atualize todos os plug-ins:

wp plugin update --all

Você também pode excluir plug-ins específicos de uma atualização em massa:

wp plugin update --all --exclude=woocommerce

Atualização e reparo do núcleo do WordPress

Manter o WordPress atualizado é fundamental para a segurança. O WP-CLI torna esse processo transparente e controlável.

Verificação de atualizações

wp core check-update

Atualização do WordPress
Atualize para a versão mais recente:

wp core update

Após uma atualização do núcleo, é uma boa prática atualizar o esquema do banco de dados:

wp core update-db

Verificação de somas de verificação
Se você suspeitar que seu site foi invadido, poderá verificar se os arquivos principais não foram modificados:

wp core verify-checksums

Isso compara seus arquivos com as somas de verificação do repositório oficial do WordPress.

Reinstalação do Core
Se os arquivos estiverem corrompidos, você pode forçar uma reinstalação sem afetar o conteúdo:

wp core download --force --skip-content

Gerenciamento de conteúdo, usuários e banco de dados

O WP-CLI permite que você interaja diretamente com os dados do seu site.

Gerenciamento de usuários
Listar usuários:

wp user list

Criar um novo administrador:

wp user create newadmin [email protected] --role=administrator --user_pass=securepass123

Atualizar uma senha de usuário:

wp user update 1 --user_pass=newpassword

Excluir um usuário e reatribuir seu conteúdo:

wp user delete 5 --reassign=1

Operações de banco de dados
Exportar o banco de dados para um arquivo:

wp db export backup.sql

Importar um banco de dados de um arquivo:

wp db import backup.sql

Otimize o banco de dados:

wp db optimize

Abra um console MySQL diretamente conectado ao seu banco de dados do WordPress:

wp db cli

Pesquisar e substituir (da maneira correta)

Mover um site WordPress para um novo domínio manualmente é arriscado porque os dados geralmente são serializados no banco de dados. Uma simples busca e substituição de SQL quebrará widgets e opções de tema. O WP-CLI lida com a serialização corretamente.

Pesquisa e substituição padrão

wp search-replace 'http://old-domain.com' 'https://new-domain.com'

Dry Run (Preview)
Sempre verifique o que será alterado antes de executar o comando:

wp search-replace 'http://old-domain.com' 'https://new-domain.com' --dry-run

Exportando com substituição
Você pode exportar um banco de dados com as substituições feitas no arquivo, deixando o banco de dados ativo intacto:

wp search-replace 'old.com' 'new.com' --export=migrated-db.sql

Manutenção avançada: Cron e cache de objetos

Gerenciamento de trabalhos Cron
Exibir eventos programados:

wp cron event list

Executar todos os eventos cron devidos imediatamente:

wp cron event run --due-now

Gerenciando transientes e cache
Limpe o cache de objetos:

wp cache flush

Excluir todos os transientes expirados:

wp transient delete --expired

Automatização de tarefas com scripts

Você pode combinar comandos WP-CLI em scripts Bash para manutenção automatizada.

Exemplo: Script de manutenção semanal
Crie um arquivo chamado maintain.sh:

#!/bin/bash
# Update everything
wp core update
wp core update-db
wp plugin update --all
wp theme update --all

# Cleanup
wp transient delete --expired
wp cache flush
wp db optimize

echo "Maintenance complete."

Torne-o executável (chmod +x maintain.sh) e execute-o para realizar a manutenção completa do site em segundos.

Usando o WP-CLI remotamente via SSH

Se você configurar aliases, não precisará fazer login no servidor para executar comandos.

Em seu arquivo local wp-cli.yml:

@prod:
  ssh: [email protected]/var/www/html
@dev:
  ssh: [email protected]/var/www/html

Agora você pode executar comandos no servidor remoto a partir de sua máquina local:

wp @prod plugin list
wp @dev core version

Práticas recomendadas

Sempre faça backup: Antes de executar atualizações em massa ou comandos de busca e substituição, execute wp db export.
Use o Dry Run: Para pesquisar e substituir, sempre use primeiro o site --dry-run.
Não execute como root: O WP-CLI avisa se você executar como root. É mais seguro executar como usuário do servidor Web (por exemplo, www-data) ou como sua conta de usuário específica.
Teste na preparação: Use o WP-CLI para clonar seu site de produção para a preparação, testar seus scripts de atualização lá e, em seguida, aplicar à produção.

Conclusão

O WP-CLI transforma o gerenciamento do WordPress de uma série de cliques em operações simplificadas e com scripts. Começando com comandos simples, como verificar versões e listar plug-ins, você constrói a base para a automação avançada. Ao integrar o WP-CLI ao seu fluxo de trabalho hoje, você economizará inúmeras horas em seus projetos do WordPress.