> ## 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 gets a full rewrite
> Introducing laravel/cpx, a tool that runs Composer package binaries without installing them, like npx. v2.0 is a full rewrite as a self-contained PHAR with local binary preference, Gist execution, aliases, and more.
This article is based on the README.md and UPGRADE.md of [laravel/cpx](https://github.com/laravel/cpx), as of v2.0.0 (released July 24, 2026).
## What is cpx
[cpx](https://github.com/laravel/cpx) lets you run commands bundled in a Composer package without installing them. Think of it as the Composer equivalent of npm's `npx`.
```bash theme={null}
composer global require cpx/cpx
cpx friendsofphp/php-cs-fixer fix ./src
```
Under the hood, cpx installs the package into an isolated directory and runs it from there, so it never conflicts with your project's or global Composer dependencies. Subsequent runs reuse the same installed package, so they're fast.
## Why it's needed
Installing individual tools with `composer global require` has some drawbacks:
* Global dependencies can conflict with each other (common with tools that share dependencies like `nikic/php-parser` or `symfony/console`)
* You may want to switch between different versions of the same tool per project
* It's easy to forget to update global packages over time
* You don't want to globally install a tool you'll only use once
cpx itself is a self-contained PHAR with no runtime Composer dependencies, so installing it globally never becomes a source of conflicts.
## A full rewrite in v2.0
cpx was completely rewritten in v2.0 and is now distributed as a **self-contained PHAR**. The basic usage (`cpx [arguments]`) and the `~/.cpx` cache directory remain unchanged. 1.x is now frozen — there will be no further releases, including bug fixes or security patches.
Upgrading is just a matter of reinstalling globally.
```bash theme={null}
composer global require cpx/cpx:^2.0
```
v2.0 requires PHP 8.3 or later.
## What's new in v2.0
### Local binary preference
Like npx, if a binary is already installed in your project, cpx prefers running that one over installing an isolated copy. It walks up from the current directory to find the nearest Composer project and runs the matching binary inside `vendor/bin` (the default `bin-dir`).
```bash theme={null}
cpx pint # runs vendor/bin/pint if it exists
cpx phpunit --filter=Foo # runs vendor/bin/phpunit if it exists
cpx laravel/pint:^2.0 # only uses the local copy if the installed version satisfies the constraint
```
Use `--skip-local` to force an isolated copy instead.
```bash theme={null}
cpx --skip-local laravel/pint --version
```
### Running a local package directory directly
You can point cpx at a Composer package directory you're developing and run its binary directly.
```bash theme={null}
cpx /absolute/path/to/package --version
cpx ../path/to/package --version
```
The target directory needs a valid `composer.json`, and dependencies must already be installed into `vendor/autoload.php`. In this mode, cpx doesn't run Composer or copy/cache the package.
### cpx exec and cpx tinker
Several ways to quickly run PHP code are available.
| Command | Description |
| --------------------- | ---------------------------------------------------- |
| `cpx exec ` | Runs a PHP file (this is the only way to run a file) |
| `cpx exec -r ` | Runs PHP code directly |
| `cpx exec ` | Downloads and runs a GitHub Gist |
| `cpx tinker` | Opens an interactive REPL |
Inside a Laravel project, `cpx exec` fully boots the application — including config, facades, and `.env` (`$app` is available) — and `cpx tinker` runs the project's own `php artisan tinker` (if `laravel/tinker` is installed). Elsewhere, a PsySH shell is launched instead.
Within scripts, `cpx_require('vendor/package')` (renamed from 1.x's `composer_require()`) autoloads a package on the fly.
### Alias support
Define your own shortcuts so you don't have to remember long package names.
```bash theme={null}
cpx alias laravel/pint pint
cpx aliases # list defined aliases
cpx unalias pint # remove an alias
```
The built-in list of aliases for popular packages that shipped with 1.x has been removed, so you'll need to define your own if you want them.
### Non-interactive mode and JSON output
cpx automatically detects non-interactive environments via [laravel/agent-detector](https://github.com/laravel/agent-detector) AI agent detection, redirected stdin, and the `--no-interaction`/`-n` flags. In non-interactive mode, cpx's own management commands — `installed`, `aliases`, `alias`, `unalias`, `clean`, `update`, and others — return a single line of JSON instead of formatted text. You can get the same output from an interactive terminal by passing `--json`.
## Key command changes from v1.x
| 1.x | 2.x |
| --------------------------------------- | ---------------------------------------------------------------------- |
| `cpx list` (installed packages) | Renamed to `cpx installed` (`list` now shows the command list) |
| Built-in alias list | Removed. Define your own with `cpx alias` |
| `cpx check` / `cpx format` / `cpx test` | Removed. Run directly with `cpx pint`, `cpx phpstan`, `cpx pest`, etc. |
| `cpx version` / `-v` | Removed. Use `cpx --version` |
| `cpx script.php` (run a file directly) | Removed. Use `cpx exec script.php` instead |
| `composer_require()` | Renamed to `cpx_require()` |
## Related pages
Cached packages from older versions in the `~/.cpx` directory are migrated to the new format automatically, but packages that were run with a version constraint are managed under a new directory name, so they'll be reinstalled once. You can remove copies left over from the 1.x era with `cpx clean`.
Source code and the latest README.
Detailed migration steps from 1.x to 2.x.
## Related topics
- [Rewrite User Dict Word](/en/packages/laravel-voicevox/engine-api/user-dictionary/rewrite-user-dict-word.md)
- [Laravel FullFeed](/en/packages/laravel-fullfeed.md)
- [Getting started with Laravel testing using Pest PHP](/en/blog/pest-introduction.md)
- [Getting started - VOICEVOX for Laravel](/en/packages/laravel-voicevox/getting-started.md)
- [⚡ Getting started with Livewire 4 — reactive UIs without JavaScript](/en/blog/livewire-introduction.md)