Cómo instalar WP-CLI en macOS y crear ZIP de plugins WordPress

Como la gran mayoría sabréis (y los que no, no os preocupéis 😉) WP-CLI es una gran herramienta que nos permiteinteractuar con WordPress directamente desde la terminal, sin necesidad de abrir el navegador ni tocar el panel de administración. Su utilidad abarca desde instalar plugins, gestionar usuarios, ejecutar migraciones y muchísimo más, todo con simples comandos.

Pero lo que realmente la hace especial es que también podemos extenderla creando nuestros propios alias en la terminal, adaptándola a nuestras necesidades y flujos de trabajo. Y eso es exactamente lo que vamos a ver hoy.

Entre todas las ventajas que nos ofrece WP-CLI, hay una que es especialmente útil para los desarrolladores de plugins: la posibilidad de generar paquetes de distribución de forma rápida y sencilla, siguiendo los estándares oficiales de WordPress. Sin configuraciones complejas, sin pasos manuales, solo un comando y listo.

Y en este artículo es justo lo que vamos a ver: cómo instalar WP-CLI de forma global en tu Mac, configurar el comando dist-archive y crear un alias en la terminal que empaqueta tus plugins con una sola palabra, detectando automáticamente si el proyecto usa Composer.

Si quieres saber más sobre este comando, David lo hizo con más detalle en su charla.

Requisitos previos

Antes de empezar, necesitas tener instalado lo siguiente:

• Homebrew — el gestor de paquetes imprescindible en macOS. Si no lo tienes, instálalo desde brew.sh
• PHP 7.4 o superior — macOS ya no incluye PHP por defecto desde Monterey, así que si no lo tienes, instálalo con Homebrew: brew install php

Puedes comprobar si tienes PHP instalado y su versión ejecutando en la terminal el comando:

php -v

Si está instalado, verás algo parecido a esto:

PHP 8.3.1 (cli) (built: Jan 10 2024 11:22:33) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.1, Copyright (c) Zend Technologies

Si no está instalado, verás algo como:

zsh: command not found: php

Paso 1: Instalar WP-CLI de forma global

Tienes dos opciones para instalar WP-CLI en macOS: el método manual (recomendado por la documentación oficial) o vía Homebrew.

Opción A: Instalación manual (recomendada)

Descarga el archivo .phar de WP-CLI (un ejecutable de PHP autocontenido) ejecutando el siguiente comando en la terminal:

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

Verifica que funciona correctamente:

php wp-cli.phar --info

Hazlo ejecutable y muévelo a una ubicación global:

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

Opción B: Instalación con Homebrew

Si prefieres gestionar todo con Homebrew, es aún más sencillo:

brew install wp-cli

Verificar la instalación

Independientemente del método que hayas elegido, comprueba que WP-CLI está disponible globalmente:

wp --info

Deberías ver información sobre la versión de WP-CLI, PHP y tu entorno. Si aparece, ya tienes WP-CLI listo para usar desde cualquier directorio.

Paso 2: Instalar el paquete dist-archive

El comando wp dist-archive no viene incluido por defecto en WP-CLI, sino que es un paquete adicional que tenemos que instalar. Para obtenerlo, ejecutamos el siguiente comando en la terminal:

wp package install wp-cli/dist-archive-command:@stable

Este comando se encarga de generar un archivo .zip (o .tar.gz) con todo lo necesario para distribuir tu plugin o tema, excluyendo automáticamente los archivos que no quieres incluir. Esto se controla mediante un archivo .distignore en la raíz del proyecto, donde puedes listar todo lo que debe quedar fuera del paquete final: el historial de git, node_modules, tests, archivos de configuración, etc. Solo el código que realmente necesita el usuario final.

El archivo .distignore

Crea un archivo .distignore en la raíz de tu plugin con los archivos y directorios que no quieras incluir en el zip de distribución:

.distignore
.editorconfig
.git
.gitignore
.github
node_modules
tests
phpcs.xml
composer.json
composer.lock
package.json
package-lock.json
webpack.config.js

Paso 3: Crear la función wdis

Ahora viene la parte que nos ahorra tiempo. En lugar de escribir el comando completo cada vez, vamos a crear una función de shell que además detecta automáticamente si el plugin usa Composer.

¿Bash o Zsh?

Primero, comprueba qué shell usas ejecutando en la terminal:

echo $SHELL

• Si devuelve algo como /bin/zsh o /opt/homebrew/bin/zsh → edita ~/.zshrc
• Si devuelve algo como /bin/bash o /opt/homebrew/bin/bash → edita ~/.bash_profile

Añadir la función

En lugar de un alias simple, vamos a usar una función de shell. La ventaja es que puede recibir parámetros y ejecutar lógica condicional, algo que un alias no permite.

Abre tu archivo de configuración de shell con tu editor favorito:

# Si usas bash:
nano ~/.bash_profile

# Si usas zsh:
nano ~/.zshrc

Y añade esta función al final del archivo:

function wdis {
	local dir="${1:-.}"
	local out_dir="$HOME/proyectos"

	if [ -f "$dir/composer.json" ]; then
		composer install --no-dev --working-dir="$dir" && \
		wp dist-archive "$dir" "$out_dir" --filename-format={name}-{version} && \
		composer install --working-dir="$dir"
	else
		wp dist-archive "$dir" "$out_dir" --filename-format={name}-{version}
	fi
}

Guarda el archivo y recarga la configuración:

# Si usas bash:
source ~/.bash_profile

# Si usas zsh:
source ~/.zshrc

¿Qué hace esta función?

La función recibe opcionalmente la ruta del plugin como argumento (si no se pasa, usa el directorio actual) y actúa de forma inteligente:

1. Comprueba si existe composer.json en el directorio del plugin
2. Si existe, ejecuta el ciclo completo: elimina las dependencias de desarrollo con composer install --no-dev, genera el zip con wp dist-archive, y restaura las dependencias de desarrollo con composer install para que puedas seguir trabajando
3. Si no existe, simplemente empaqueta el plugin directamente con wp dist-archive

En ambos casos, el zip se genera en la carpeta de Google Drive con el formato nombre-plugin-1.2.3.zip, tomando el nombre y la versión del header del plugin automáticamente.

Uso

Una vez configurado, tienes dos formas de usarlo:

Desde la raíz del plugin:

cd ~/proyectos/mi-plugin-wordpress
wdis

Desde cualquier sitio, pasando la ruta:

wdis wp-content/plugins/mi-plugin-wordpress

En ambos casos, el zip aparecerá en tu carpeta de Google Drive con el formato mi-plugin-wordpress-1.2.3.zip, listo para distribuir, subir a WordPress.org o compartir con clientes. Si el plugin usa Composer, las dependencias de desarrollo se excluyen automáticamente del zip y se restauran después.

Actualizar WP-CLI

Para mantener WP-CLI actualizado, simplemente ejecuta:

wp cli update

Y para actualizar el paquete dist-archive:

wp package update

Automatiza el empaquetado de plugins WordPress con WP-CLI

Con WP-CLI instalado de forma global, el paquete dist-archive y una función de shell inteligente, generar el zip de distribución de un plugin pasa de ser un proceso manual y propenso a errores a un comando de cuatro letras. La función se adapta automáticamente a cada proyecto: si usa Composer, limpia las dependencias de desarrollo antes de empaquetar y las restaura después; si no lo usa, empaqueta directamente. Si desarrollas varios plugins, este flujo te va a ahorrar bastante tiempo y te asegura que nunca incluyas archivos innecesarios en el paquete final.