PHPackages cpx/cpx - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cpx/cpx ActiveProject[Utility & Helpers](/categories/utility) cpx/cpx ======= Run any command from any composer package, even if it's not installed in your project. v2.0.0(3w ago)44721.4k↑159.8%17[9 issues](https://github.com/laravel/cpx/issues)[5 PRs](https://github.com/laravel/cpx/pulls)1MITPHPPHP ^8.3 Since Oct 1Pushed 1mo ago4 watchersCompare [ Source](https://github.com/laravel/cpx)[ Packagist](https://packagist.org/packages/cpx/cpx)[ GitHub Sponsors](https://github.com/imliam)[ RSS](/packages/cpx-cpx/feed)WikiDiscussions main Synced 1w ago READMEChangelog (6)Dependencies (12)Versions (20)Used By (1) [![Run Composer packages, efortlessly.](./banner-v2.png)](./banner-v2.png) cpx - Composer Package Executor =============================== [](#cpx---composer-package-executor) Run any command from any composer package, even if it's not installed in your project. cpx is to Composer what npx is to npm. > Note: Upgrading from cpx 1.x? The 1.x series is frozen and no longer supported — see the [upgrade guide](./UPGRADE.md) to move to 2.x. Installation ------------ [](#installation) Install cpx globally with Composer: ``` composer global require cpx/cpx ``` Make sure Composer's global `bin` directory is on your `PATH` (you can find it with `composer global config bin-dir --absolute`) so you can run `cpx` from anywhere. Upgrade to the latest release at any time by running: ``` composer global update cpx/cpx ``` Usage ----- [](#usage) You can run a command using cpx by passing through the package name and the command you want to run: > Note: A package name is what you'd use to require the package in your `composer.json` file, e.g. `friendsofphp/php-cs-fixer`You can also use constraints to specify a version, e.g. `friendsofphp/php-cs-fixer:^3.0` ``` cpx [arguments] # Example: cpx friendsofphp/php-cs-fixer php-cs-fixer fix ./src ``` If the package only has one command, or the command name is the same as the package's name, you can omit the command from the end: ``` cpx [arguments] # Example: cpx friendsofphp/php-cs-fixer fix ./src ``` Behind the scenes, cpx will install the package into a separate directory and run the command, keeping it separate from both your project and global Composer dependencies (unless the package is already installed in your project — see below). Subsequent runs of the same package will use the same installation and run quickly, unless you specify a different version or there is an update to the package available. ### Local package directories [](#local-package-directories) When developing a Composer package locally, pass its directory to run its declared binary directly from the source checkout: ``` cpx /absolute/path/to/package --version cpx ~/path/to/package --version cpx ./path/to/package --version cpx ../path/to/package --version ``` The directory must contain a valid `composer.json` and its dependencies must already be installed at `vendor/autoload.php`. For packages with multiple binaries, pass the binary name after the directory just as you would after a package name: ``` cpx ../package binary-name --flag ``` cpx does not run Composer, copy the package, cache it, or include it in package maintenance commands when an explicit local directory is used. Run `composer install` in the package directory yourself whenever its dependencies need to be installed. ### Local project binaries [](#local-project-binaries) Like `npx`, cpx prefers a binary that is already installed in your project. Before installing an isolated copy, cpx finds the nearest Composer project (walking up from the current directory) and runs the matching binary from its configured `bin-dir` (`vendor/bin` by default): ``` cpx pint # runs vendor/bin/pint when the project has it installed cpx phpunit --filter=Foo # runs vendor/bin/phpunit when present cpx laravel/pint:^2.0 # uses the local pint only when the installed version satisfies ^2.0 ``` This keeps cpx aligned with the versions your project pins. When no matching local binary is found, cpx falls back to installing and running an isolated copy. To skip the local binary and force the isolated copy, pass `--skip-local` before the package: ``` cpx --skip-local laravel/pint --version ``` --- ### cpx alias [](#cpx-alias) `cpx alias` lets you create your own shortcut for a package, so you don't have to remember or type its full vendor/package name every time. ``` cpx alias laravel/pint pint ``` Both arguments are optional — if you leave either one out, cpx will prompt you for it. Leaving out the name defaults it to the package's short name, so `cpx alias laravel/pint` alone is enough to create the `pint` alias above. Your aliases are saved under `~/.cpx/` and can be listed with `cpx aliases`. Use `cpx unalias ` to remove one of your aliases, e.g. `cpx unalias pint`. Leave off the name and cpx will prompt you for it. ### cpx installed [](#cpx-installed) `cpx installed` shows all the packages you have run via cpx and have installed. Running `cpx` with no arguments (or `cpx list`) shows every available cpx command. ### cpx update [](#cpx-update) While cpx will automatically check for updates to a Composer package when you run a command, you can also manually update packages. `cpx update` will update the local version of all packages run via cpx to the latest version, according to their version constraints. `cpx update ` or `cpx update /` will update only the specified packages. ### cpx clean [](#cpx-clean) `cpx clean` will remove all the packages you have run via cpx but haven't used recently. `cpx clean --all` will remove all packages regardless of when they have run. ### cpx exec and cpx tinker [](#cpx-exec-and-cpx-tinker) cpx gives you multiple ways to run PHP code quickly, perfect for running scratch files or quickly running code in your project. - `cpx exec ` will run a plain PHP file. This is the only way to run a file — a bare `cpx ` is not routed to exec. - `cpx exec -r ` will execute the given PHP code. - `cpx exec ` will download a GitHub gist (like `https://gist.github.com/user/id`) and run it, similar to how npx can run gists. For gists with multiple PHP files, cpx asks which one to run — or append the file's anchor from the gist page (like `#file-my-script-php`) to skip the prompt. You can pin a specific revision by appending its SHA to the URL (like `/5c30e34c...`), and set a `GITHUB_TOKEN` environment variable to authenticate if you hit GitHub's rate limit. Raw gist links (the gist page's "Raw" button, like `https://gist.githubusercontent.com/user/id/raw/.../script.php`) also work and are downloaded exactly as pinned. The script executes against your current directory, so autoloading and framework bootstrapping still apply. - `cpx tinker` will open an interactive REPL in the terminal for your project. When using these commands, you get the following benefits: - **Automatic Autoloaders** - When running a PHP file, it will automatically detect and use Composer's autoloader if it exists in the current or a parent directory - **Class Aliasing** - If a class is used in the file but the namespace isn't imported, cpx will try to find an appropriate one to alias. - **Framework Bootstrapping** - In a Laravel project, cpx fully boots the application (config, facades, and `.env` all work, with `$app` in scope). In a Symfony project, it boots the kernel and exposes `$kernel` and `$container`. Pass `--no-boot` to skip the framework boot. - **The right REPL** - In a Laravel project with `laravel/tinker` installed, `cpx tinker` runs your project's own `php artisan tinker` (extra arguments like `--execute` are forwarded). Everywhere else it opens a PsySH shell with your project booted. - **Process isolation** - Your code runs in its own PHP process, so it never collides with cpx's bundled dependencies, and `exit()` codes pass through. - **cpx\_require()** - You can use the function like `cpx_require('vendor/package')` in the executed script and those packages will be autoloaded into the file. The function is also available inside `cpx tinker`, including when it proxies to your project's own `artisan tinker`. ### cpx help [](#cpx-help) `cpx help` shows usage information, and `cpx help ` shows help for a specific command. ### Non-interactive mode and JSON output [](#non-interactive-mode-and-json-output) cpx detects when it is not running in an interactive terminal — inside an AI agent (via [laravel/agent-detector](https://github.com/laravel/agent-detector)), with stdin redirected, or when `--no-interaction`/`-n` is passed. In non-interactive mode: - Child processes never get a TTY. - Prompts fall back to their defaults instead of waiting for input — pass positional arguments and `--bin` to control everything explicitly. Overwriting an existing alias with `cpx alias` requires the `--force` option and fails otherwise. - cpx's own commands (`installed`, `aliases`, `alias`, `unalias`, `clean`, and `update`) respond with a single line of JSON instead of formatted text: ``` { "success": true, "errors": [], "summary": { "packages": [ { "name": "laravel/pint", "last_run": "2024-01-02 03:04:05" } ] } } ``` Package runs stream only the tool's own output — cpx's progress rendering is suppressed — and cpx-level failures (an unrecognised command, a package that cannot be installed, missing or ambiguous binaries) are reported as JSON. You can also pass `--json` to any of the commands above to get the same JSON output from an interactive terminal. FAQ: ---- [](#faq) ### Why not just install every tool with global composer? [](#why-not-just-install-every-tool-with-global-composer) Installing individual tools with `composer global require` works, but it has some downsides: - You can get conflicts with other global dependencies (especially tooling using common dependencies like `nikic/php-parser` and `symfony/console`) - You might need to switch between versions of the package between runs, but can only have one version installed globally - You need to remember to update your global packages if you are using them long-term - You might only use a package's command once, and don't want to install it globally cpx itself is safe to install with `composer global require` because it has no runtime Composer dependencies of its own — it ships as a self-contained PHAR (see below), so it doesn't add to the global dependency conflict surface. ### What kind of one-off commands might I want to run with cpx? [](#what-kind-of-one-off-commands-might-i-want-to-run-with-cpx) There are a few reasons you might want to run a one-off command with cpx: - Applying code-style fixes using a tool like `php-cs-fixer` or `rector` - Running analysis of your codebase using a tool like `phploc` or `phpstan` - Creating files or stubs using a tool like `laravel/installer` ### Can I use multiple different versions of a tool with cpx? [](#can-i-use-multiple-different-versions-of-a-tool-with-cpx) Yes, cpx will manage the package versions for you, so you can run any version of the package you want. ### Does cpx conflict with my project or global Composer dependencies? [](#does-cpx-conflict-with-my-project-or-global-composer-dependencies) No. cpx ships as a self-contained PHAR with its own runtime dependencies bundled and isolated inside it, kept separate from both your project and your global Composer setup. Avoiding those conflicts is one of the problems cpx is built to solve. Credits ------- [](#credits) - [Liam Hammett](https://github.com/imliam) - [All Contributors](https://github.com/laravel/cpx/contributors) ### Health Score 60 — FairBetter than 98% of packages Maintenance93 Actively maintained with recent releases Popularity48 Moderate usage in the ecosystem Community20 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 94.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~111 days Recently: every ~166 days Total 7 Last Release 18d ago Major Versions v1.0.4 → v2.0.02026-07-24 PHP version history (2 changes)1.0.0PHP ^8.2 v2.0.0PHP ^8.3 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/463230?v=4)[Taylor Otwell](/maintainers/taylorotwell)[@taylorotwell](https://github.com/taylorotwell) ![](https://www.gravatar.com/avatar/8cc9e697c220afa4ac18184d1aaab004e2da9448ac251a74e6031eec48b21601?d=identicon)[joetannenbaum](/maintainers/joetannenbaum) ![](https://www.gravatar.com/avatar/3e8a14b9f997cf85aacea7d39da9dc33c38cc05fe03360578327ea9bcb25f4d9?d=identicon)[ImLiam](/maintainers/ImLiam) --- Top Contributors [![imliam](https://avatars.githubusercontent.com/u/4326337?v=4)](https://github.com/imliam "imliam (18 commits)")[![tyamahori](https://avatars.githubusercontent.com/u/21966964?v=4)](https://github.com/tyamahori "tyamahori (1 commits)") --- Tags composercpxpackagesphpcomposerpackageruncommand ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/cpx-cpx/health.svg) ``` [![Health](https://phpackages.com/badges/cpx-cpx/health.svg)](https://phpackages.com/packages/cpx-cpx) ``` ### Alternatives [jean85/pretty-package-versions A library to get pretty versions strings of installed dependencies 1.3k325.7M89](/packages/jean85-pretty-package-versions)[composer/satis Simple Repository Generator 3.3k1.5M19](/packages/composer-satis)[fxp/composer-asset-plugin NPM/Bower Dependency Manager for Composer 8874.8M41](/packages/fxp-composer-asset-plugin)[consolidation/cgr Safer alternative to 'composer global require'. 449215.1k](/packages/consolidation-cgr)[foxy/foxy Fast, reliable, and secure NPM/Yarn/pnpm bridge for Composer 176291.9k27](/packages/foxy-foxy)[veewee/composer-run-parallel Run composer tasks in parallel 92829.4k21](/packages/veewee-composer-run-parallel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)