O guia completo para instalar o WP-CLI

Publicados: 2022-03-16

A interface de linha de comando do WordPress (WP-CLI) é uma poderosa ferramenta focada no desenvolvedor do WordPress. Aqui no Delicious Brains nós o usamos para nos ajudar a escrever testes, gerenciar mudanças nos bancos de dados do nosso site e até temos suporte WP-CLI no WP Migrate DB Pro. Por último, mas não menos importante, SpinupWP, nosso painel de controle de servidor baseado em nuvem para WordPress, faz uso intenso do WP-CLI para gerenciar sites WordPress, por isso é uma ferramenta incrivelmente importante para nós.

Adoramos tanto que achamos importante que todo desenvolvedor WordPress saiba como instalá-lo e usá-lo. Este post abordará a instalação do WP-CLI e a configuração para funcionar de forma eficiente com esta ferramenta incrível.

Índice

O que é WP-CLI?
Como instalar o WP-CLI no macOS e Linux
1. O Método Oficial
2. Instalando o WP-CLI usando um gerenciador de pacotes
3. Instalando o WP-CLI usando o APT
4. Instalando o WP-CLI usando o Homebrew
5. Instalando o WP-CLI usando o Composer
6. Instalando o WP-CLI usando o Docker
7. Verificando se o WP-CLI funciona
Como instalar o WP-CLI no Windows
1. Verificando se o WP-CLI funciona no Windows
Depois de instalar o WP-CLI
1. Configurando a conclusão da guia
2. Criando um arquivo de configuração WP-CLI
3. Atualizando o WP-CLI
Empacotando

O que é WP-CLI?

WP-CLI é uma interface de linha de comando para WordPress. Ele permite que você faça muitas das mesmas tarefas que o painel de administração em seu site WordPress, mas a partir de um terminal de linha de comando em seu computador ou servidor web. Isso o torna muito útil durante o desenvolvimento e após a implantação do site. Você pode usar o WP-CLI para instalar o WordPress, configurar instalações multisite, atualizar plugins e temas, atualizar o próprio WordPress e muito mais.

Uma vez que você se sinta confortável com o WP-CLI, você descobrirá que isso geralmente é mais rápido do que fazer a mesma coisa através do navegador da web (e faz você parecer muito legal ao fazê-lo).

Ferramentas de linha de comando como WP-CLI também são ótimas para tarefas repetitivas, como adicionar usuários em massa ou verificar atualizações regularmente. Isso ocorre porque o WP-CLI é fácil de combinar com outras ferramentas e utilitários de linha de comando, como scripts Bash e cron jobs.

As pessoas usam o WP-CLI para uma ampla variedade de tarefas relacionadas ao WordPress. Por exemplo…

Instalando e ativando um plugin:

 $ wp plugin --activate advanced-custom-fields

Adicionando um usuário:

 $ wp user create erik [email protected] --role=subscriber

Atualizando o núcleo do WordPress e o banco de dados:

 $ wp core update && wp core update-db

Tirando um instantâneo do banco de dados:

 $ wp db export /mnt/backups/$(date +%Y%m%d).sql

Adicionar um único usuário, executar backups únicos ou executar verificações de atualização usando a linha de comando pode não ser uma grande vitória sobre o uso das páginas de administração. No entanto, se você tiver 500 usuários para adicionar ou quiser fazer atualizações e backups às 3 da manhã todas as manhãs, ter uma ferramenta de linha de comando se torna realmente útil.

Vamos aprofundar em como tirar o máximo proveito do WP-CLI em um tutorial futuro, incluindo dicas, dicas e truques que a equipe do Delicious Brains aprendeu ao longo dos anos. Mas antes de mais nada, vamos instalar o WP-CLI corretamente.

Como instalar o WP-CLI

Estas instruções são para usuários de Mac e Linux. Clique aqui para ir para as instruções de instalação no Windows.

O Método Oficial

A maneira recomendada de instalar o WP-CLI está documentada no site do WP-CLI. A instalação do WP-CLI em uma máquina Mac ou Linux requer PHP versão 5.6 ou posterior e você deve ter a ferramenta de linha de comando cURL instalada. Abra seu terminal e execute os seguintes comandos.

O primeiro passo é baixar a compilação do Phar:

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

Em seguida, você precisa verificar o arquivo baixado:

 $ php wp-cli.phar --info

Por fim, torne-o executável e mova-o para o seu PATH:

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

Instalando o WP-CLI usando um gerenciador de pacotes

Os desenvolvedores do WP-CLI não estão ativamente envolvidos na manutenção de pacotes para vários gerenciadores de pacotes. As opções para instalar o WP-CLI usando um gerenciador de pacotes variam dependendo de qual gerenciador de pacotes você usa e se algum voluntário interveio e criou um pacote para ele.

Instalando o WP-CLI usando o APT

Tiago Hillebrandt mantém um PPA para instalação do WP-CLI no Debian/Ubuntu e todas as suas variações. Você pode usar o PPA dele assim:

 $ sudo add-apt-repository ppa:tiagohillebrandt/wp-cli $ sudo apt-get update $ sudo apt-get install wp-cli

Instalando o WP-CLI usando o Homebrew

O Homebrew possui uma fórmula para WP-CLI, então basta executar o seguinte comando:

 $ brew install wp-cli

Instalando o WP-CLI usando o Composer

Você também pode usar o Composer para instalar o WP-CLI. Embora o uso mais comum do Composer seja manter dependências dentro do seu projeto PHP, ele também pode ser usado para instalar ferramentas em sua máquina. É possível instalar o WP-CLI apenas para o seu projeto atual se você realmente precisar ter uma versão específica do WP-CLI. É muito raro que um projeto precise de algo além da versão mais recente, então minha recomendação é instalá-lo globalmente. É bom ter o WP-CLI facilmente acessível em todos os lugares e é uma dependência de desenvolvimento a menos em meus projetos. Veja como instalá-lo globalmente:

 $ composer global require wp-cli/wp-cli

Este método de instalação requer que você adicione ~/.composer/vendor/bin à sua variável PATH. Isso funciona de forma diferente dependendo se você estiver usando MacOS, Linux ou Windows. Aqui estão alguns links úteis para usar Bash ou Zsh.

Depois de instalar o WP-CLI globalmente assim, você pode acessá-lo de qualquer pasta do seu computador.

Instalando o WP-CLI via Docker

A comunidade Docker mantém imagens WordPress e WP-CLI. Você pode usar a imagem WP-CLI em seus projetos do Docker especificando a variante CLI como sua imagem do WordPress no arquivo yml criado pelo docker compose .

 image: wordpress:cli

Verificando se o WP-CLI funciona

Independentemente do método de instalação usado, é uma boa ideia verificar se a instalação foi bem-sucedida e o WP-CLI está acessível, independentemente do diretório em que você esteja. Para verificar se as coisas funcionam como deveriam, você pode passar o --info parâmetro:

 $ wp --info

Se estiver instalado corretamente, você deverá ver algo assim:

SO: Darwin 20.6.0 Darwin Kernel Versão 20.6.0: qua 10 de novembro 22:23:07 PST 2021; root:xnu-7195.141.14~1/RELEASE_X86_64 x86_64
Shell: /bin/zsh
Binário PHP: /usr/local/Cellar/[email protected]/7.4.27/bin/php
Versão do PHP: 7.4.27
php.ini usado: /usr/local/etc/php/7.4/php.ini
Binário MySQL: /usr/local/bin/mysql
Versão do MySQL: mysql Ver 8.0.28 para macos11.6 em x86_64 (Homebrew)
Modos SQL:
Diretório raiz WP-CLI: phar://wp-cli.phar/vendor/wp-cli/wp-cli
Diretório do fornecedor WP-CLI: phar://wp-cli.phar/vendor
Caminho de phar WP_CLI: /usr/local/bin
Diretório de pacotes WP-CLI:
Configuração global do WP-CLI:
Configuração do projeto WP-CLI:
Versão WP-CLI: 2.6.0

Como instalar o WP-CLI no Windows

Instalar o WP-CLI no Windows nativo é um pouco diferente de instalá-lo em uma máquina Mac ou Linux. Antes de começarmos, usando o Windows Subsystem for Linux que a Microsoft introduziu há alguns anos, você poderá instalar usando as instruções para MacOS e Linux acima. Se você quiser que funcione no Windows nativo, as etapas a seguir são para você.

Esteja ciente de que o WP-CLI é feito principalmente para sistemas baseados em *nix. Algumas funcionalidades, como acessar sites remotos do WordPress via SSH, podem exigir que você passe por alguns obstáculos. Outros recursos podem não funcionar. Mas é possível obter uma instalação básica do WP-CLI em execução em uma máquina Windows.

Observe que sua conta de usuário do Windows deve ter direitos de administrador para que essas etapas funcionem. Se você não tiver direitos de administrador, precisará pedir a alguém que tenha direitos de administrador ou que o ajude com essas etapas.

Requisitos do Windows

Para começar a instalar a linha de comando do WordPress no Windows, os únicos requisitos reais são que você tenha a linha de comando PHP para Windows instalada e adicionada ao seu PATH para que você possa executar o PHP a partir da linha de comando em qualquer diretório de trabalho. A maneira mais fácil de instalar o WP-CLI é usando cURL. A maioria das instalações do Windows já possui o cURL instalado, pois está incluído no Windows 10 desde 2018.

Hoje comemoramos que o Windows 10 lançou o curl junto com o sistema operacional por exatamente 4 anos.
— Daniel Stenberg (@bagder) 1º de março de 2022

Se você ainda não o tiver em sua máquina, recomendo que você o instale usando um desses métodos sugeridos ou baixando-o da página inicial do cURL antes de continuar.

Baixar e instalar

Primeiro você precisa baixar a versão mais recente do wp-cli.phar do GitHub para uma pasta local. Se você tiver o cURL instalado, poderá fazer isso com três comandos:

 C:\> mkdir C:\wp-cli C:\> cd C:\wp-cli C:\> curl -O https://raw.github.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Se você não tiver cURL e não puder instalá-lo, também poderá criar a pasta C:\wp-cli manualmente no Windows File Explorer, baixar o arquivo usando o link acima e movê-lo para essa pasta.

Depois de baixar o arquivo, é uma boa ideia confirmar se funciona digitando:

 C:> php C:\wp-cli\wp-cli.phar --info

Você deve ver algumas linhas resumindo seu ambiente WP-CLI local.

Digitar o caminho completo para o arquivo phar toda vez que você executa um comando WP-CLI vai ficar velho muito rápido. Então, para tornar a vida um pouco mais fácil, vamos fazer mais duas etapas. Primeiro, adicionamos permanentemente a pasta C:\wp-cli à variável de ambiente PATH. Eu prefiro fazer isso usando o comando setx . Você pode selecionar entre adicioná-lo apenas ao seu ambiente ou adicioná-lo para todos os usuários usando a opção /m .

Para todas as sessões futuras com sua conta de usuário:

 setx PATH "%PATH%;c:\wp-cli"

Apenas para a sessão de terminal atual:

 set PATH "%PATH%;c:\wp-cli"

Ou para todas as sessões futuras, para todos os usuários do sistema:

 setx PATH "%PATH%;c:\wp-cli" /m

Basta adicionar o caminho ao seu próprio ambiente se esta for sua máquina de desenvolvimento local. Se for um servidor onde você potencialmente agendará trabalhos noturnos usando WP-CLI, é melhor adicioná-lo ao ambiente para todos os usuários. Usar setx com a opção /m requer que você abra um terminal CMD com direitos administrativos totais. A maneira mais fácil de fazer isso é procurar cmd.exe no menu Iniciar, clicar com o botão direito do mouse e selecionar Executar como administrador para abri-lo:

Inicie cmd.exe como administrador

Por fim, criamos um arquivo batch do Windows na pasta WP-CLI chamado wp.bat com o seguinte conteúdo:

 @ECHO OFF php "c:\wp-cli\wp-cli.phar" %*

Este arquivo .bat permitirá que você chame run WP-CLI usando o wp mais curto em vez de sempre digitar o nome completo do arquivo phar. Isso economiza um monte de digitação e também é como o WP-CLI é chamado no Mac e no Linux.

Verificando se o WP-CLI funciona no Windows

Com todos os itens acima, agora podemos executar o WP-CLI de qualquer pasta:

 C:\> wp --info

Se estiver instalado corretamente, você deverá ver algo assim:

SO: Windows NT 10.0 compilação 19043 (Windows 10) AMD64
Shell: C:\WINDOWS\system32\cmd.exe
Binário PHP: C:\php\php.exe
Versão do PHP: 7.4.27
php.ini usado:   
Binário MySQL: 
Versão do MySQL:
Modos SQL:
Diretório raiz WP-CLI: phar://wp-cli.phar/vendor/wp-cli/wp-cli
Diretório do fornecedor WP-CLI: phar://wp-cli.phar/vendor
Caminho do phar WP_CLI: C:\wp-cli
Diretório de pacotes WP-CLI:
Configuração global do WP-CLI:
Configuração do projeto WP-CLI:
Versão WP-CLI: 2.6.0

Depois de instalar o WP-CLI

Uma vez que você tenha o WP-CLI funcionando e tenha verificado que ele funciona, é hora de algumas configurações iniciais. Um dos conceitos centrais do WP-CLI são os commands que podem ter subcommands . Cada um desses comandos e subcomandos pode ter várias opções opcionais. Às vezes, você pode acabar digitando strings de comando bem longas. Outro dia precisei inserir um elemento array dentro de uma opção do WordPress e o comando ficou assim:

 $ wp --path=www/testing option patch insert tantan_wordpress_s3 post_meta_version 7

Depois de se familiarizar com o WP-CLI, você sem dúvida aprenderá muitos desses comandos de cor. Mas se isso parece mais digitação do que você gosta de fazer regularmente, deixe-me mostrar algumas coisas que você pode fazer para torná-lo menos assustador e muito mais provável de ser correto na primeira tentativa.

Configurando a conclusão da guia

A primeira coisa que vamos fazer é habilitar o preenchimento de tabulação, que é o mecanismo no shell que sugere automaticamente o que você deve digitar a seguir quando pressionar a tecla TAB . No meu ambiente, apenas digito o início desse comando acima para ver quais subcomandos existem:

 $ wp option [TAB] add delete get list patch pluck update

Configurar o preenchimento de guias é muito fácil para não fazê-lo, mas ajuda saber qual shell de linha de comando você está usando. Se você não tiver certeza, deixe-me mostrar rapidamente como fazer isso verificando a variável de ambiente $SHELL:

 # On older MacOS and on most Linux boxes, we should see /bin/bash $ echo $SHELL /bin/bash # On newer MacOS boxes, we should see /bin/zsh $ echo $SHELL /bin/zsh # Check for Oh My Zsh $ omz Usage: omz <command> [options] Available commands: help Print this help message changelog Print the changelog plugin <command> Manage plugins pr <command> Manage Oh My Zsh Pull Requests reload Reload the current zsh session theme <command> Manage themes update Update Oh My Zsh version Show the version

Se você estiver usando o Oh My Zsh, essa é a coisa mais fácil de todas. Basta digitar o seguinte comando:

 $ omz plugin enable wp-cli omz::plugin::enable: plugins enabled: wp-cli.

Se você estiver usando Bash direto ou Zsh, há apenas mais algumas etapas envolvidas para baixar o script e adicioná-lo ao seu ambiente. Primeiro, mude para sua pasta pessoal e baixe o script para a versão 2.6.0 do WP-CLI:

 $ cd ~/ $ curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/v2.6.0/utils/wp-completion.bash

Em seguida, adicione-o ao seu perfil e recarregue. Os usuários do Bash podem usar estes comandos:

 $ echo "source ~/wp-completion.bash" >> ~/.bash_profile $ source ~/.bash_profile

Os usuários do Zsh, no entanto, devem usar estes:

 $ echo "source ~/wp-completion.bash" >> ~/.zshenv $ source ~/.zshenv

Em um sistema Linux, em vez de obter wp-completion.bash de seu ~/.bash_profile , você precisa fazer isso de seu ~/.bashrc . Certifique-se de que o arquivo wp-completion.bash esteja em seu diretório inicial e execute os seguintes comandos no diretório inicial:

 cat wp-completion.bash >> .bashrc source .bashrc

Embora a conclusão de guias até certo ponto também exista para o Windows, até onde sei, não é possível integrá-lo a ferramentas de terceiros, como WP-CLI, como no Mac ou Linux. Se você conhece uma maneira de adicionar a conclusão da guia WP-CLI no Windows, entre em contato nos comentários abaixo.

Criando um arquivo de configuração WP-CLI

A próxima coisa que sempre faço assim que tenho uma instalação WP-CLI funcionando é adicionar um arquivo de configuração à minha pasta $HOME . Arquivos de configuração são um tópico bastante avançado com muitas funcionalidades interessantes que podem justificar um artigo totalmente separado. Instalar um arquivo de configuração básico é uma ótima maneira de reduzir a quantidade de digitação repetitiva.

Sem um arquivo de configuração, o WP-CLI assumirá que seu diretório de trabalho é o mesmo que o arquivo wp-config.php do site WordPress real. Muitas vezes você não estará nesse diretório. Por exemplo, toda vez que você abre seu terminal, normalmente você estará na sua pasta $HOME . Felizmente, você pode fornecer o parâmetro --path para WP-CLI para fazê-lo parecer na pasta correta:

 $ wp --path=/Users/eriktorsner/src/path/to/wordpress plugin list

Como você pode imaginar, rapidamente se torna um pouco tedioso continuar digitando essa variável de caminho inicial todas as vezes. Para reduzir a quantidade de digitação, você pode adicionar um arquivo de configuração que o WP-CLI usará para obter o path e outros parâmetros importantes.

Para criar este arquivo, abra seu editor de texto favorito e crie um arquivo chamado wp-cli.yml em seu diretório inicial. Adicione a seguinte linha:

 path: /Users/eriktorsner/src/path/to/wordpress

Você precisa ajustar esse caminho para que corresponda onde você tem – ou planeja colocar – sua instalação local do WordPress. Com este arquivo no lugar, o WP-CLI saberá automaticamente onde procurar a instalação do WordPress para que você não precise digitá-lo sempre.

Toda vez que você executar o comando WP-CLI, ele procurará um arquivo de configuração para usar. Existem vários locais possíveis para colocar um arquivo de configuração e há uma prioridade específica que determina qual arquivo de configuração é escolhido, da prioridade mais alta para a mais baixa:

Um arquivo chamado wp-cli.local.yml no diretório de trabalho atual ou superior
Um arquivo chamado wp-cli.yml no diretório de trabalho atual ou superior
Um arquivo chamado wp-cli.yml em sua pasta $HOME

Observe que o “ou para cima” significa que, supondo que você mantenha um arquivo de configuração na raiz da sua instalação do WordPress, o WP-CLI ainda poderá descobrir se você trabalhou em um subdiretório como wp-content/uploads/year/month . Também vale a pena saber que, se você quiser colocar seu arquivo de configuração em outro lugar que não seja sua pasta pessoal, sempre poderá especificar um local usando a variável de ambiente WP_CLI_CONFIG_PATH .

Qualquer parâmetro fornecido por meio do comando typed substituirá os valores coletados de um arquivo de configuração, o que facilita a substituição de valores de um arquivo de configuração quando necessário.

Esta seção mal arranhou a superfície de quão incrivelmente útil o arquivo de configuração WP-CLI pode ser. Em um post futuro, pretendo me aprofundar muito e mostrar como os uso para gerenciar meus ambientes de desenvolvimento locais do WordPress.

Atualizando o WP-CLI

WP-CLI tem a capacidade de auto-atualização. Se você instalou o WP-CLI usando o método recomendado, pode atualizá-lo usando o comando update sub:

 $ sudo wp cli update

Em seu ambiente de desenvolvimento local, você pode experimentar os melhores e mais recentes recursos do WP-CLI e usar a compilação noturna (mas evite isso em servidores de produção):

 $ sudo wp cli update --nightly

Se você instalou o WP-CLI usando um gerenciador de pacotes, você deve sempre atualizar usando o mecanismo de gerenciadores de pacotes. Atualizar diretamente quase certamente funcionará, mas eu não recomendo. Você estaria roubando do gerenciador de pacotes a chance de saber qual versão está instalada no momento. Isso nunca é uma coisa boa. Depois de selecionar seu método de instalação, sugiro que você o mantenha também para atualizações.

Empacotando

Se você acompanhou este post, agora você deve ter uma instalação funcional do WP-CLI configurada com preenchimento de guias e um arquivo de configuração básico no local. Vamos começar a olhar para realmente fazer o trabalho com esta ferramenta investigando o gerenciamento de plugins em um post futuro.

Enquanto isso, você pode querer ler nosso artigo sobre os pacotes WP-CLI sem os quais não podemos viver, ou nossa série sobre como automatizar a configuração local do site WordPress com scripts.

Se você tiver alguma dúvida sobre como instalar o WP-CLI, não hesite em me informar nos comentários abaixo.