Guia de instalação do WP-CLI

By , Founder · Updated

O WP-CLI é uma interface de linha de comandos para o WordPress. Permite-te instalar Plugins, gerir utilizadores, executar operações na base de dados e muito mais — tudo a partir de um terminal, sem precisares de aceder ao backend do WordPress. Este guia cobre a instalação em Linux, macOS e Windows, incluindo passos de verificação e resolução de problemas para as falhas mais comuns.

TL;DR: no Linux ou macOS (método phar), descarrega o ficheiro Phar, torna-o executável e move-o para a tua PATH. No macOS, o caminho mais rápido é brew install wp-cli. No Windows, instala o Cygwin ou usa o WSL2 e segue depois os passos do Linux. Executa wp --version para confirmares que a instalação correu bem.

Referência rápida por plataforma e método

Plataforma Método recomendado Alternativa
Linux curl (phar) Composer
macOS Homebrew (brew install wp-cli) curl (phar)
Windows (Cygwin) curl (phar) no terminal Cygwin —
Windows (WSL2) Segue os passos do Linux dentro do WSL2 —

O WP-CLI também pode ser instalado como pacote Composer; consulta a documentação oficial do WP-CLI para as instruções de require wp-cli/wp-cli.

Pré-requisitos

  • PHP 5.4 ou superior
  • WordPress 3.7 ou superior
  • Acesso SSH ao teu servidor para instalações em Linux
  • Privilégios de administrador para instalações em Windows

Instalação em Linux

  1. Descarregar o WP-CLI:

Abre uma janela de terminal e descarrega o ficheiro Phar do WP-CLI utilizando curl:

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

Nos nossos testes no Ubuntu 22.04 LTS, o método curl conclui-se em menos de um minuto numa ligação de servidor normal.

  1. Tornar o WP-CLI executável:

Torna o ficheiro Phar descarregado executável:

Bash
chmod +x wp-cli.phar
  1. Mover o WP-CLI para o diretório bin:

Move o executável para um diretório que esteja na tua PATH. O diretório /usr/local/bin é a localização normalizada:

Bash
sudo mv wp-cli.phar /usr/local/bin/wp
  1. Verificar a instalação do WP-CLI:

Confirma que o WP-CLI está corretamente instalado consultando as informações do sistema:

Bash
wp --info

Instalação em macOS

O macOS é o ambiente de desenvolvimento principal para muitos developers de WordPress. O método Homebrew é o mais simples e mantém o WP-CLI atualizado automaticamente.

Instalar via Homebrew (recomendado)

Se tens o Homebrew instalado, executa:

brew install wp-cli

Depois da instalação, confirma que funciona:

wp --version

Instalar via Phar (sem Homebrew)

Se preferes o método manual, os passos Phar do Linux funcionam no macOS sem alterações:

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
wp --version

Instalação em Windows

  1. Descarregar o WP-CLI:

Visita a página do WP-CLI no GitHub e descarrega o ficheiro Phar mais recente em:

Bash
https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
  1. Descarregar e instalar o Cygwin:

O WP-CLI requer um terminal estilo Unix. Descarrega e instala o Cygwin a partir do site oficial:

Bash
https://www.cygwin.com/

Durante a instalação, certifica-te de que instalas os pacotes curl, php, php-curl, php-mbstring, openssl e openssh.

  1. Mover o WP-CLI para o diretório Cygwin:

Move o ficheiro wp-cli.phar para o diretório home do Cygwin, normalmente C:cygwin64homeYour_User.

  1. Tornar o WP-CLI executável:

Abre o terminal Cygwin e navega para o teu diretório home com cd ~. Depois, torna o ficheiro Phar executável:

Bash
chmod +x wp-cli.phar
  1. Mover o WP-CLI para o diretório bin:

Move o executável para a tua PATH. O diretório /usr/bin dentro do Cygwin é a localização normalizada:

Bash
mv wp-cli.phar /usr/bin/wp
  1. Verificar a instalação do WP-CLI:

Confirma que o WP-CLI está corretamente instalado consultando as informações do sistema:

Bash
wp --info

Verificar a instalação

Depois de instalares o WP-CLI por qualquer método, confirma que está a funcionar com dois comandos.

Verificar a versão:

wp --version

O comando devolve uma string de versão como WP-CLI x.y.z. Consulta a página de versões do WP-CLI para confirmares que tens a versão mais recente.

Executar uma verificação básica de saúde:

wp doctor check

Isto verifica problemas comuns de configuração. Executa-o a partir de um diretório WordPress para obteres resultados específicos do site. O comando doctor faz parte do pacote wp-cli/doctor-command, que requer instalação separada — vê o README do wp-cli/doctor-command para instruções de configuração.

Resolução de problemas

A partir dos tickets de suporte do WP STAGING, a causa mais comum de falhas na instalação do WP-CLI é uma má configuração da PATH. A seguir ficam as principais falhas e respetivas correções.

wp: command not found após a instalação (Linux/macOS)

O Phar do WP-CLI não foi colocado num diretório da tua $PATH. Confirma para onde o wp foi movido:

which wp

Se o comando não devolver nada, o binário não está na tua PATH. Adiciona /usr/local/bin à PATH editando ~/.bashrc ou ~/.zshrc:

export PATH="$PATH:/usr/local/bin"
source ~/.bashrc

Depois tenta novamente wp --version.

PHP não encontrado na PATH (Windows / Cygwin)

O WP-CLI precisa de ter o PHP acessível a partir do terminal. No Cygwin, verifica se o PHP está instalado executando php --version. Se devolver erro, executa novamente o instalador do Cygwin e adiciona o pacote php.

Permissão negada no ficheiro Phar (Linux/macOS)

Se vires um erro "Permission denied" ao mover o ficheiro para /usr/local/bin, prefixa o comando com sudo:

sudo mv wp-cli.phar /usr/local/bin/wp

Se o sudo não estiver disponível (por exemplo, em Hosting partilhado), move o ficheiro para um diretório onde tenhas permissões de escrita (p. ex., ~/bin/) e adiciona esse diretório à tua PATH.

Incompatibilidade de versão do PHP

O WP-CLI requer PHP 5.4 ou superior. Executa php --version para verificares a versão a que o teu terminal recorre. Se tens várias versões de PHP instaladas, a versão que o WP-CLI deteta depende da ordem da tua PATH. Na maioria dos casos, vemos este problema em servidores com uma versão de PHP abaixo do mínimo 5.4 — atualizar o PHP para cumprir o requisito resolve-o. Consulta php.net/manual/en/install.php para orientação sobre a instalação do PHP.

Conclusão

Agora que o WP-CLI está instalado, podes começar a usá-lo para gerir o teu site WordPress a partir da linha de comandos. A documentação oficial do WP-CLI cobre a referência completa de comandos e o manual.

Artigos relacionados

Updated on May 23, 2026

Rene Hermenau

Autor: Rene Hermenau

About the author: René Hermenau is the founder of WP STAGING. He works on WordPress backups, staging, migrations, database handling, and safe deployment workflows.