> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# cpx 2.0 — Composer Package Executor totalmente reescrito

> Presentación de laravel/cpx, una herramienta que ejecuta paquetes de Composer sin instalarlos, al estilo de npx. En la v2.0 se reescribió por completo como un PHAR autocontenido, incorporando ejecución prioritaria de binarios locales, ejecución desde Gist, alias, etc.

<Info>
  Este artículo se basa en el README.md y el UPGRADE.md de [laravel/cpx](https://github.com/laravel/cpx). El contenido corresponde a la v2.0.0 (lanzada el 24 de julio de 2026).
</Info>

## Qué es cpx

[cpx](https://github.com/laravel/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 del `npx` de npm.

```bash theme={null}
composer global require cpx/cpx
cpx friendsofphp/php-cs-fixer fix ./src
```

Internamente instala el paquete en un directorio aislado y lo ejecuta desde allí, así que no colisiona con las dependencias de Composer del proyecto ni con las globales. En las ejecuciones posteriores se reutiliza el paquete ya instalado, por lo que son rápidas.

## Por qué es necesario

El método de instalar herramientas individuales con `composer 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-parser` o `symfony/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.

El propio cpx es autocontenido como PHAR y no tiene dependencias de Composer en tiempo de ejecución, así que aunque se instale globalmente no causa conflictos.

## 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.

```bash theme={null}
composer global require cpx/cpx:^2.0
```

La v2.0 requiere PHP 8.3 o superior.

## 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 en `vendor/bin` (el `bin-dir` por defecto).

```bash theme={null}
cpx pint                 # si existe vendor/bin/pint, lo ejecuta
cpx phpunit --filter=Foo # si existe vendor/bin/phpunit, lo ejecuta
cpx laravel/pint:^2.0    # usa el local solo si la versión instalada cumple la restricción
```

Si quieres forzar la copia aislada, usa `--skip-local`.

```bash theme={null}
cpx --skip-local laravel/pint --version
```

### Ejecución directa desde un directorio de paquete local

Puedes indicar directamente un directorio de un paquete Composer en desarrollo para ejecutar sus binarios.

```bash theme={null}
cpx /absolute/path/to/package --version
cpx ../path/to/package --version
```

El directorio de destino debe contener un `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.

| Comando               | Descripción                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `cpx exec <file.php>` | Ejecuta un archivo PHP (esta es la única forma de ejecutar archivos) |
| `cpx exec -r <code>`  | Ejecuta directamente código PHP                                      |
| `cpx exec <gist url>` | Descarga y ejecuta un Gist de GitHub                                 |
| `cpx tinker`          | Abre un REPL interactivo                                             |

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.

```bash theme={null}
cpx alias laravel/pint pint
cpx aliases      # lista los alias definidos
cpx unalias pint # elimina un alias
```

La lista de alias incorporados para paquetes populares que traía la 1.x se ha eliminado, así que si los necesitas debes definirlos tú mismo.

### Modo no interactivo y salida JSON

cpx detecta automáticamente los entornos no interactivos gracias a [laravel/agent-detector](https://github.com/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)

| 1.x                                             | 2.x                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `cpx list` (lista de instalados)                | Cambiado a `cpx installed` (`list` muestra la lista de comandos)             |
| Lista de alias integrados                       | Eliminada. Defínelos tú con `cpx alias`                                      |
| `cpx check` / `cpx format` / `cpx test`         | Eliminados. Ejecuta directamente `cpx pint`, `cpx phpstan`, `cpx pest`, etc. |
| `cpx version` / `-v`                            | Eliminado. Usa `cpx --version`                                               |
| `cpx script.php` (ejecución directa de archivo) | Eliminado. Se requiere `cpx exec script.php`                                 |
| `composer_require()`                            | Renombrado a `cpx_require()`                                                 |

## 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.

<Card title="Repositorio de laravel/cpx" icon="github" href="https://github.com/laravel/cpx">
  El código fuente y el README más reciente están aquí.
</Card>

<Card title="Guía de actualización a cpx 2.0" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  Procedimiento detallado de migración de la 1.x a la 2.x.
</Card>


## Related topics

- [Gestión de la compatibilidad de versiones de paquetes](/es/advanced/package-versioning.md)
- [Laravel Pennant](/es/pennant.md)
- [Actualización de Laravel — Junio de 2026](/es/blog/changelog/202606.md)
- [Configuración](/es/configuration.md)
- [Actualización de Laravel 9 a 10](/es/blog/upgrade-9-to-10.md)