Skip to main content
This article is based on the README.md and UPGRADE.md of laravel/cpx, as of v2.0.0 (released July 24, 2026).

​
What is cpx

cpx lets you run commands bundled in a Composer package without installing them. Think of it as the Composer equivalent of npm’s npx.
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 <package-name> <command> [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.
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).
Use --skip-local to force an isolated copy instead.

​
Running a local package directory directly

You can point cpx at a Composer package directory you’re developing and run its binary directly.
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. 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.
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 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

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.

laravel/cpx repository

Source code and the latest README.

cpx 2.0 upgrade guide

Detailed migration steps from 1.x to 2.x.
Last modified on July 30, 2026

Related topics

Rewrite User Dict WordLaravel FullFeedGetting started with Laravel testing using Pest PHPGetting started - VOICEVOX for Laravel⚡ Getting started with Livewire 4 — reactive UIs without JavaScript