이 기사는 laravel/cpx의 README.md와 UPGRADE.md를 기반으로 하는 정보입니다. v2.0.0(2026년 7월 24일 릴리스) 시점의 내용입니다.
cpx란
cpx는 Composer 패키지에 포함된 명령을 설치하지 않고 실행할 수 있는 도구입니다. npm의npx의 Composer 버전이라고 생각하면 이해하기 쉽습니다.
왜 필요한가
composer global require로 개별 도구를 설치하는 방법에는 다음 과제가 있습니다.
- 전역 의존 관계끼리 충돌한다 (
nikic/php-parser나symfony/console등 공통 의존을 사용하는 도구에서 발생하기 쉬움) - 같은 도구의 다른 버전을 프로젝트마다 전환하고 싶다
- 장기 운용 시 전역 패키지의 업데이트를 잊는다
- 한 번만 사용할 도구를 전역 설치하고 싶지 않다
v2.0에서의 전면 재작성
cpx는 v2.0에서 전면적으로 다시 작성되어, 자체 완결형 PHAR로 배포되게 되었습니다. 기본적인 사용법(cpx <package-name> <command> [arguments])이나 ~/.cpx 캐시 디렉터리는 그대로 유지되고 있습니다. 1.x는 개발이 동결되었고, 버그 수정·보안 수정을 포함해 향후 릴리스는 없습니다.
업그레이드는 전역 설치를 다시 하기만 하면 됩니다.
v2.0의 새로운 기능
로컬 바이너리 우선 실행
npx와 마찬가지로 프로젝트에 이미 설치된 바이너리가 있다면 분리 복사본을 설치하기 전에 그쪽을 우선하여 실행합니다. 현재 디렉터리에서 위로 거슬러 올라가 가장 가까운 Composer 프로젝트를 찾아vendor/bin(기본 bin-dir) 내의 일치하는 바이너리를 실행합니다.
--skip-local을 사용합니다.
로컬 패키지 디렉터리의 직접 실행
개발 중인 Composer 패키지의 디렉터리를 직접 지정하여 그 바이너리를 실행할 수 있습니다.composer.json이 필요하며, 의존 관계는 사전에 vendor/autoload.php에 설치되어 있어야 합니다. cpx는 이 경우 Composer 실행이나 패키지의 복사·캐싱을 하지 않습니다.
cpx exec와 cpx tinker
PHP 코드를 빠르게 실행하는 여러 방법이 준비되어 있습니다.
Laravel 프로젝트 내에서는
cpx exec가 config·파사드·.env를 포함하여 애플리케이션을 완전히 부트($app을 사용 가능)하며, cpx tinker는 프로젝트 자신의 php artisan tinker를 실행합니다(laravel/tinker가 설치된 경우). 그 외의 곳에서는 PsySH 셸이 시작됩니다.
스크립트 내에서는 cpx_require('vendor/package')(1.x의 composer_require()에서 이름 변경)로 패키지를 즉석에서 오토로드할 수 있습니다.
별칭 기능
긴 패키지명을 외우지 않아도 되도록 자체 단축키를 정의할 수 있습니다.비대화 모드와 JSON 출력
cpx는 laravel/agent-detector에 의한 AI 에이전트 감지, 표준 입력 리다이렉트,--no-interaction/-n 플래그에서 비대화 환경을 자동 감지합니다. 비대화 모드에서는 installed·aliases·alias·unalias·clean·update 등 cpx 자체의 관리 명령이 정형화된 텍스트 대신 한 줄의 JSON을 반환합니다. 대화형 터미널에서도 --json을 전달하면 같은 출력을 얻을 수 있습니다.
v1.x에서의 주요 변경점 (명령)
관련 페이지
~/.cpx 디렉터리의 캐시나 구버전 패키지는 자동으로 새 형식으로 이행되지만, 버전 제약 포함으로 실행되던 패키지는 새 디렉터리명으로 관리되므로 처음에만 재설치됩니다. 필요 없어진 1.x 시절 복사본은 cpx clean으로 삭제할 수 있습니다.
laravel/cpx 리포지토리
소스 코드와 최신 README는 여기.
cpx 2.0 업그레이드 가이드
1.x에서 2.x로의 자세한 마이그레이션 절차.