Este artículo se basa en el README.md y el UPGRADE.md de laravel/cpx. El contenido corresponde a la v2.0.0 (lanzada el 24 de julio de 2026).
Qué es cpx
cpx es una herramienta que permite ejecutar los comandos contenidos en un paquete de Composer sin instalarlos. Se entiende bien si lo piensas como la versión para Composer delnpx de npm.
Por qué es necesario
El método de instalar herramientas individuales concomposer global require tiene los siguientes inconvenientes.
- Las dependencias globales entran en conflicto entre sí (ocurre con facilidad en herramientas que usan dependencias comunes como
nikic/php-parserosymfony/console). - Quieres cambiar entre distintas versiones de la misma herramienta según el proyecto.
- En operaciones a largo plazo se olvida actualizar los paquetes globales.
- No quieres instalar globalmente una herramienta que solo vas a usar una vez.
Reescritura completa en la v2.0
Con la v2.0, cpx se ha reescrito por completo y ahora se distribuye como un PHAR autocontenido. Se mantienen el uso básico (cpx <package-name> <command> [arguments]) y el directorio de caché ~/.cpx. El desarrollo de la 1.x está congelado y no habrá futuras releases, ni siquiera correcciones de bugs o de seguridad.
Para actualizar basta con reinstalarlo globalmente.
Novedades de la v2.0
Ejecución prioritaria de binarios locales
Igual que npx, si ya hay un binario instalado en el proyecto se ejecuta ese antes de instalar una copia aislada. Se recorre hacia arriba desde el directorio actual hasta encontrar el proyecto Composer más cercano y se ejecuta el binario coincidente que se encuentre envendor/bin (el bin-dir por defecto).
--skip-local.
Ejecución directa desde un directorio de paquete local
Puedes indicar directamente un directorio de un paquete Composer en desarrollo para ejecutar sus binarios.composer.json válido y las dependencias deben estar previamente instaladas en vendor/autoload.php. En este caso, cpx no ejecuta Composer ni copia ni cachea el paquete.
cpx exec y cpx tinker
Hay varias formas de ejecutar rápidamente código PHP.
Dentro de un proyecto Laravel,
cpx exec arranca la aplicación en su totalidad —incluidos config, facades y .env— (con $app disponible), y cpx tinker ejecuta el propio php artisan tinker del proyecto (si laravel/tinker está instalado). Fuera de estos casos se lanza el shell de PsySH.
Dentro de los scripts puedes autocargar paquetes al vuelo con cpx_require('vendor/package') (renombrado desde composer_require() de la 1.x).
Alias
Puedes definir tus propios atajos para no tener que recordar nombres de paquete largos.Modo no interactivo y salida JSON
cpx detecta automáticamente los entornos no interactivos gracias a laravel/agent-detector para la detección de agentes de IA, la redirección de la entrada estándar y las banderas--no-interaction/-n. En modo no interactivo, los comandos administrativos propios de cpx —como installed, aliases, alias, unalias, clean o update— devuelven JSON en una sola línea en lugar de texto formateado. Desde un terminal interactivo puedes obtener la misma salida pasando --json.
Principales cambios respecto a la 1.x (comandos)
Páginas relacionadas
La caché del directorio~/.cpx y los paquetes de versiones antiguas se migran automáticamente al nuevo formato, pero los paquetes que se ejecutaban con restricciones de versión se gestionan con un nuevo nombre de directorio, por lo que en la primera ejecución se reinstalan. Puedes eliminar con cpx clean las copias de la 1.x que ya no necesites.
Repositorio de laravel/cpx
El código fuente y el README más reciente están aquí.
Guía de actualización a cpx 2.0
Procedimiento detallado de migración de la 1.x a la 2.x.