13 min. lê

WP-CLI: O Guia Completo para Gerir o WordPress a partir da Linha de Comando

WP-CLI é a ferramenta oficial de linha de comandos para gerir instalações WordPress diretamente a partir do teu terminal, sem nunca abrir um browser. Se alguma vez passaste uma tarde a clicar no painel de administração do WordPress para atualizar plugins em vários sites, já sabes porque é que esta ferramenta existe.

Neste guia, aprenderás tudo, desde a instalação do WP-CLI no Linux, macOS e Windows até à automatização de tarefas de manutenção complexas com scripts e ficheiros de configuração. Quer estejas a gerir um único blog ou dezenas de sites de clientes, dominar o WP-CLI vai mudar fundamentalmente a forma como trabalhas com o WordPress.

O que vais aprender:

  • Como instalar e configurar o WP-CLI em diferentes sistemas operativos
  • Comandos essenciais para gerir plug-ins, temas, utilizadores e conteúdos
  • Operações de bases de dados, incluindo exportações, importações e pesquisa e substituição seguras
  • Técnicas de automatização utilizando scripts, aliases e tarefas cron
  • Melhores práticas para evitar as armadilhas mais comuns quando trabalhas a partir do terminal

O que é WP-CLI? (Explica rapidamente primeiro)

WP-CLI significa WordPress Command Line Interface – uma ferramenta de código aberto que te permite gerir sites WordPress inteiramente a partir do terminal. Em vez de entrar no wp-admin e navegar pelos menus, executa comandos como wp plugin update --all e vê toda a sua pilha de plugins ser actualizada em segundos.

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

Eis o que precisas de 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é 6.x (e historicamente até 3.7)
  • Requisitos de PHP: PHP 7.4+ ou 8.x recomendado para segurança e desempenho
  • Ecossistema de comandos: Mais de 40 comandos principais que cobrem praticamente todas as operações do WordPress
  • Utilizadores principais: Programadores, agências, engenheiros de DevOps e utilizadores avançados que gerem sítios complexos ou múltiplos
  • Distribuição: Disponível como um ficheiro PHAR, através de gestores de pacotes, ou pré-instalado em muitos hosts WordPress geridos

Principais benefícios de usar o WP-CLI

Depois de entenderes o porquê da existência do WP-CLI, a curva de aprendizagem torna-se muito mais fácil de justificar. Esta secção explica as vantagens concretas que fazem com que esta ferramenta valha o teu tempo.

Economia de tempo em tarefas repetitivas
Atualizar 20 plugins através do painel de controle do WordPress significa 20 carregamentos de página, 20 cliques e ver 20 barras de progresso. Com WP-CLI, você executa 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
Considera um cenário em que estás a preparar 15 lojas WooCommerce para a Black Friday. Você precisa atualizar plugins, limpar caches e verificar a integridade do banco de dados em cada site. O WP-CLI permite que você crie um script de toda essa sequência e execute-a em todos os sites em minutos, em vez de horas. Os principais recursos de automação incluem:

  • Atualização de todos os plugins em várias instalações com um único script
  • Criar utilizadores em massa com funções predefinidas
  • Executa a manutenção nocturna através do cron (otimização da base de dados, limpeza transitória)
  • Implantação de configurações idênticas do WordPress em novos ambientes

Fiabilidade das operações baseadas no browser
As operações do browser atingem tempos limite HTTP. Importações de grandes bases de dados falham a meio do processo. Operações de busca e substituição corrompem dados serializados quando feitas com SQL bruto. WP-CLI evita todos esses problemas porque ele roda diretamente no servidor sem restrições de timeout, e seu comando search-replace lida corretamente com estruturas de dados serializadas.

Controlo direto sobre os principais sistemas WordPress
A partir de um terminal, podes:

  • Exportar e importar a base de dados do WordPress
  • Modifica as definições de wp-config.php
  • Inspecionar e acionar eventos wp-cron
  • Liga e desliga o modo de manutenção
  • Executa código PHP arbitrário no contexto do WordPress

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

Requisitos do WP-CLI e ambientes suportados

Antes de instalar o WP-CLI, tens de confirmar que o teu servidor ou ambiente local cumpre os requisitos básicos. A boa notícia é que a maioria das configurações modernas do WordPress já está qualificada.

Requisitos da versão PHP:

  • Mínimo: PHP 5.6 (embora este 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
  • Destino moderno: WordPress 5.0 a 6.7+ para projectos actuais

Expectativas do sistema operativo:

  • Suporta melhor: Sistemas do tipo UNIX (Ubuntu 22.04 LTS, Debian 12, CentOS Stream, macOS)
  • Windows: Suportado via WSL (Windows Subsystem for Linux) ou instalação nativa do PHP

Requisitos adicionais:

  • PHP disponível na linha de comando (o binário php tem de estar no teu PATH)
  • cURL ou wget para descarregar o ficheiro wp-cli.phar
  • Acesso SSH para servidores remotos (a maioria dos planos de alojamento WordPress gerido inclui este acesso por defeito)

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 utiliza o ficheiro PHAR (PHP Archive) oficial. Este processo funciona em terminais Ubuntu, Debian, CentOS, Fedora e macOS.

Passo 1: Descarrega o ficheiro PHAR
Abre o teu terminal e descarrega wp-cli.phar utilizando curl:

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

Em alternativa, utiliza o wget:

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

Passo 2: Verifica o download (opcional, mas recomendado)
Verifica a soma de verificação SHA-256 em relação ao valor oficial publicado na documentação do WP-CLI para garantir que o ficheiro não foi adulterado durante o download:

sha256sum wp-cli.phar

Compara o resultado com a soma de verificação listada no site oficial do WP-CLI.

Passo 3: Testa o ficheiro PHAR
Confirma que o ficheiro php funciona:

php wp-cli.phar --info

Deves ver uma saída que mostra a versão do WP-CLI, a versão do PHP e a informação do sistema.

Passo 4: Torna-o executável e move-o para o PATH
Marca o ficheiro como executável e move-o para um diretório no PATH do teu sistema:

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

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

Passo 5: Verifica a instalação global
Confirma que o WP-CLI está agora disponível globalmente:

wp --info
wp cli version

Deves ver uma mensagem a confirmar a versão do wp cli, a localização do binário do PHP e os detalhes do sistema operativo. Neste ponto, tens o WP-CLI instalado e pronto a usar.

Como instalar o WP-CLI no Windows

Os utilizadores do Windows têm dois caminhos principais: utilizar 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: Utilizar a WSL (Recomendado)
Primeiro, ativa a WSL no Windows 10 ou 11:

wsl --install

Instala o Ubuntu a partir da Microsoft Store e, em seguida, inicia o terminal do Ubuntu. A partir daí, segue exatamente os mesmos passos de instalação do Linux descritos na secção anterior – transfere o ficheiro phar, torna-o executável e move-o para /usr/local/bin/wp.

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

  1. Transfere e instala o PHP a partir do site oficial do PHP para Windows
  2. Adiciona o diretório PHP à tua variável de ambiente PATH do Windows
  3. Confirma que o PHP funciona abrindo o Command Prompt e executando php -v

Em seguida, descarrega o ficheiro WP-CLI PHAR:

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

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

Em seguida, cria um ficheiro de acompanhamento de lote com o nome wp.bat na mesma pasta:

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

Adiciona C:\wp-cli à variável de ambiente PATH do sistema. Agora abre uma nova janela do Prompt de Comando ou do PowerShell e verifica: 

wp --info

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

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

Com o WP-CLI instalado, tens de compreender o padrão de comando básico antes de mergulhar em operações específicas. Todos os comandos WP-CLI seguem esta estrutura: 

wp <command> <subcommand> [options]

Os comandos são executados a partir de um diretório de instalação do WordPress – a pasta que contém wp-config.php. Se estiveres noutro local, podes especificar o caminho com --path=/var/www/html/mysite.

Verificar o teu ambiente
Começa por confirmar a tua configuração:

wp --info

Mostra 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

Explorar os comandos disponíveis
Para listar todos os comandos wp cli disponíveis:

wp help

Para obter ajuda sobre um comando específico:

wp help plugin
wp help core update

Também podes acrescentar --help a qualquer comando:

wp user --help

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

Primeiro, experimenta os comandos:

  • wp core version – mostra a tua versão do WordPress
  • wp plugin list – mostra todos os plugins WordPress instalados com o seu estado
  • wp theme list – mostra os temas instalados
  • wp user list – lista todos os utilizadores do sítio

Estes comandos só de leitura permitem-te explorar o teu site WordPress sem alterar nada, o que é perfeito para te sentires confortável com a interface.

Instalar e configurar o WordPress com WP-CLI

WP-CLI pode executar uma instalação completa do WordPress mais rápido do que o instalador tradicional baseado na web. Isso é especialmente valioso ao criar ambientes de desenvolvimento ou implantar novos sites de forma programática.

Pré-requisitos
Antes de executar os comandos de instalação, precisas de uma base de dados MySQL ou MariaDB pronta. Para este exemplo, assume que criaste:

  • Nome da base de dados: wpsite_db
  • Utilizador da base de dados: wpsite_user
  • Senha: securepassword123
  • Apresenta-te: localhost

Passo 1: Transferir os ficheiros do núcleo do WordPress
Navega até ao diretório de instalação pretendido e transfere o núcleo do WordPress:

wp core download

Vai buscar 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, verás a confirmação de que o WordPress foi transferido com êxito.

Passo 2: Gerar wp-config.php
Cria o ficheiro de configuração utilizando wp config create:

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

Isto gera um wp-config.php completo com as credenciais da tua base de dados e sais de segurança gerados automaticamente.

Passo 3: Executa a instalação
Agora instala o WordPress com os detalhes do teu sítio:

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

Verás a mensagem “WordPress instalado com sucesso” e o teu site está pronto a ser utilizado.

Instalação multisite
Para redes WordPress multisite, usa a variante multisite. O WP-CLI pode configurar instalações multisite com: 

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

Gerir temas com WP-CLI

O WP-CLI lida com todas as operações de temas sem exigir acesso ao painel de administração do WordPress. Podes listar, instalar, ativar, atualizar e eliminar temas diretamente a partir do teu terminal.

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

wp theme list

Mostra a saída:

nomeestatutoactualizaversão
vinte e vinte e quatroativonone1.0
vinte e vinte e trêsinativonone1.2
astrainativodisponível4.5.0

Ativar um tema
Muda para um tema diferente:

wp theme activate astra

Isto altera imediatamente o tema ativo. Voltar para um tema padrão é útil para solucionar problemas relacionados ao tema: 

wp theme activate twentytwentyfour

Instalar novos temas
Instala um tema a partir do repositório WordPress.org:

wp theme install astra

Instala e ativa num só comando:

wp theme install astra --activate

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

wp theme update astra

Ou actualiza todos os temas de uma só vez:

wp theme update --all

Eliminar temas
Remove um tema de que já não precisas:

wp theme delete twentytwentythree

Gerir plug-ins com WP-CLI

A gestão de plugins é onde o WP-CLI poupa mais tempo. Podes realizar operações em massa que exigiriam dezenas de cliques no painel de controlo.

Listagem de plugins

wp plugin list

Mostra a saída:

nomeestatutoactualizaversão
woocommerceativonone8.5.1
yoast-seoativodisponível21.0
elementarinativonone3.18.0

Instalar plugins
Instala um plugin pelo seu slug:

wp plugin install woocommerce

Instala e ativa:

wp plugin install yoast-seo --activate

Ativar e desativar
Ativar um plug-in:

wp plugin activate elementor

Desactiva um plugin (útil para depuração):

wp plugin deactivate elementor

Desactiva todos os plugins de uma só vez (salva-vidas para a depuração do “Ecrã Branco da Morte”):

wp plugin deactivate --all

Atualizar plugins
Actualiza um plugin específico:

wp plugin update yoast-seo

Actualiza todos os plugins:

wp plugin update --all

Também podes excluir plug-ins específicos de uma atualização em massa:

wp plugin update --all --exclude=woocommerce

Atualizar e reparar o núcleo do WordPress

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

Verificar se há actualizações

wp core check-update

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

wp core update

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

wp core update-db

Verificar as somas de verificação
Se suspeitas que o teu site foi pirateado, podes verificar se os ficheiros principais não foram modificados:

wp core verify-checksums

Compara os teus ficheiros com as somas de verificação do repositório oficial do WordPress.

Reinstalar o Core
Se os ficheiros estiverem corrompidos, podes forçar uma reinstalação sem afetar o teu conteúdo:

wp core download --force --skip-content

Gerir conteúdos, utilizadores e bases de dados

WP-CLI permite-te interagir diretamente com os dados do teu site.

Gestão de utilizadores
Lista os utilizadores:

wp user list

Cria um novo administrador:

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

Actualiza a palavra-passe de um utilizador:

wp user update 1 --user_pass=newpassword

Elimina um utilizador e reatribui o seu conteúdo:

wp user delete 5 --reassign=1

Operações da base de dados
Exportar a base de dados para um ficheiro:

wp db export backup.sql

Importa uma base de dados a partir de um ficheiro:

wp db import backup.sql

Optimiza a base de dados:

wp db optimize

Abre uma consola MySQL diretamente ligada à tua base de dados WordPress:

wp db cli

Pesquisar e substituir (da forma correta)

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

Pesquisa-Substituição padrão

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

Dry Run (Pré-visualização)
Verifica sempre o que vai mudar antes de executares o comando:

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

Exportar com substituição
Podes exportar uma base de dados com as substituições feitas no ficheiro, deixando a base de dados ativa intacta:

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

Manutenção avançada: Cron e Object Cache

Gerir tarefas Cron
Vê os eventos agendados:

wp cron event list

Executa todos os eventos cron devidos imediatamente:

wp cron event run --due-now

Gerenciando transientes e cache
Limpa o cache de objetos:

wp cache flush

Apaga todos os transientes expirados:

wp transient delete --expired

Automatização de tarefas com scripts

Podes combinar comandos WP-CLI em scripts Bash para uma manutenção automatizada.

Exemplo: Script de manutenção semanal
Cria um ficheiro com o nome 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."

Torna-o executável (chmod +x maintain.sh) e executa-o para realizar a manutenção completa do sítio em segundos.

Usando WP-CLI remotamente via SSH

Não precisas de iniciar sessão no servidor para executar comandos se configurares aliases.

No teu ficheiro local wp-cli.yml:

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

Agora podes executar comandos no servidor remoto a partir da tua máquina local:

wp @prod plugin list
wp @dev core version

Melhores práticas

  • Faz sempre uma cópia de segurança: Antes de executar actualizações em massa ou comandos de pesquisa e substituição, executa wp db export.
  • Utiliza o Dry Run: Para pesquisar-substituir, utiliza sempre primeiro --dry-run.
  • Não corras como Root: WP-CLI avisa-te se correres como root. É mais seguro correr como o utilizador do servidor web (por exemplo, www-data) ou a tua conta de utilizador específica.
  • Testa no Staging: Usa o WP-CLI para clonar o teu site de produção para o staging, testa os teus scripts de atualização lá e depois aplica-os à produção.

Conclusão

O WP-CLI transforma a gestão 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 plugins, constrói a base para a automação avançada. Integrar o WP-CLI no teu fluxo de trabalho hoje poupará inúmeras horas nos teus projectos WordPress.