> ## 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 전면 재작성

> laravel/cpx 소개. npx처럼 Composer 패키지를 설치하지 않고 실행할 수 있는 도구. v2.0에서 자체 완결형 PHAR로 전면 재작성되었으며, 로컬 바이너리 우선 실행이나 Gist 실행, 별칭 기능 등이 추가되었습니다.

<Info>
  이 기사는 [laravel/cpx](https://github.com/laravel/cpx)의 README.md와 UPGRADE.md를 기반으로 하는 정보입니다. v2.0.0(2026년 7월 24일 릴리스) 시점의 내용입니다.
</Info>

## cpx란

[cpx](https://github.com/laravel/cpx)는 Composer 패키지에 포함된 명령을 설치하지 않고 실행할 수 있는 도구입니다. npm의 `npx`의 Composer 버전이라고 생각하면 이해하기 쉽습니다.

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

내부적으로는 패키지를 분리된 디렉터리에 설치하여 실행하므로, 프로젝트나 전역 Composer 의존 관계와 충돌하지 않습니다. 두 번째 이후 실행은 같은 설치된 패키지를 재사용하기 때문에 빠릅니다.

## 왜 필요한가

`composer global require`로 개별 도구를 설치하는 방법에는 다음 과제가 있습니다.

* 전역 의존 관계끼리 충돌한다 (`nikic/php-parser`나 `symfony/console` 등 공통 의존을 사용하는 도구에서 발생하기 쉬움)
* 같은 도구의 다른 버전을 프로젝트마다 전환하고 싶다
* 장기 운용 시 전역 패키지의 업데이트를 잊는다
* 한 번만 사용할 도구를 전역 설치하고 싶지 않다

cpx 자체는 PHAR로 자체 완결되어 있고 런타임의 Composer 의존을 갖지 않기 때문에, 전역 설치해도 충돌 원인이 되지 않습니다.

## v2.0에서의 전면 재작성

cpx는 v2.0에서 전면적으로 다시 작성되어, **자체 완결형 PHAR**로 배포되게 되었습니다. 기본적인 사용법(`cpx <package-name> <command> [arguments]`)이나 `~/.cpx` 캐시 디렉터리는 그대로 유지되고 있습니다. 1.x는 개발이 동결되었고, 버그 수정·보안 수정을 포함해 향후 릴리스는 없습니다.

업그레이드는 전역 설치를 다시 하기만 하면 됩니다.

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

v2.0은 PHP 8.3 이상이 필요합니다.

## v2.0의 새로운 기능

### 로컬 바이너리 우선 실행

npx와 마찬가지로 프로젝트에 이미 설치된 바이너리가 있다면 분리 복사본을 설치하기 전에 그쪽을 우선하여 실행합니다. 현재 디렉터리에서 위로 거슬러 올라가 가장 가까운 Composer 프로젝트를 찾아 `vendor/bin`(기본 `bin-dir`) 내의 일치하는 바이너리를 실행합니다.

```bash theme={null}
cpx pint                 # vendor/bin/pint가 존재하면 그것을 실행
cpx phpunit --filter=Foo # vendor/bin/phpunit이 존재하면 그것을 실행
cpx laravel/pint:^2.0    # 설치된 버전이 제약을 충족하는 경우에만 로컬을 사용
```

분리 복사본을 강제하고 싶다면 `--skip-local`을 사용합니다.

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

### 로컬 패키지 디렉터리의 직접 실행

개발 중인 Composer 패키지의 디렉터리를 직접 지정하여 그 바이너리를 실행할 수 있습니다.

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

대상 디렉터리에는 유효한 `composer.json`이 필요하며, 의존 관계는 사전에 `vendor/autoload.php`에 설치되어 있어야 합니다. cpx는 이 경우 Composer 실행이나 패키지의 복사·캐싱을 하지 않습니다.

### cpx exec와 cpx tinker

PHP 코드를 빠르게 실행하는 여러 방법이 준비되어 있습니다.

| 명령                    | 설명                      |
| --------------------- | ----------------------- |
| `cpx exec <file.php>` | PHP 파일 실행(파일 실행은 이 방법뿐) |
| `cpx exec -r <code>`  | PHP 코드를 직접 실행           |
| `cpx exec <gist url>` | GitHub Gist를 다운로드하여 실행  |
| `cpx tinker`          | 인터랙티브 REPL 열기           |

Laravel 프로젝트 내에서는 `cpx exec`가 config·파사드·`.env`를 포함하여 애플리케이션을 완전히 부트(`$app`을 사용 가능)하며, `cpx tinker`는 프로젝트 자신의 `php artisan tinker`를 실행합니다(`laravel/tinker`가 설치된 경우). 그 외의 곳에서는 PsySH 셸이 시작됩니다.

스크립트 내에서는 `cpx_require('vendor/package')`(1.x의 `composer_require()`에서 이름 변경)로 패키지를 즉석에서 오토로드할 수 있습니다.

### 별칭 기능

긴 패키지명을 외우지 않아도 되도록 자체 단축키를 정의할 수 있습니다.

```bash theme={null}
cpx alias laravel/pint pint
cpx aliases      # 정의된 별칭 목록
cpx unalias pint # 별칭 삭제
```

1.x에 내장되어 있던 인기 패키지용 내장 별칭 목록은 폐지되었으므로, 필요하다면 스스로 정의할 필요가 있습니다.

### 비대화 모드와 JSON 출력

cpx는 [laravel/agent-detector](https://github.com/laravel/agent-detector)에 의한 AI 에이전트 감지, 표준 입력 리다이렉트, `--no-interaction`/`-n` 플래그에서 비대화 환경을 자동 감지합니다. 비대화 모드에서는 `installed`·`aliases`·`alias`·`unalias`·`clean`·`update` 등 cpx 자체의 관리 명령이 정형화된 텍스트 대신 한 줄의 JSON을 반환합니다. 대화형 터미널에서도 `--json`을 전달하면 같은 출력을 얻을 수 있습니다.

## v1.x에서의 주요 변경점 (명령)

| 1.x                                     | 2.x                                             |
| --------------------------------------- | ----------------------------------------------- |
| `cpx list` (설치된 목록)                     | `cpx installed`로 변경 (`list`는 명령 목록 표시)          |
| 내장 별칭 목록                                | 폐지. `cpx alias`로 직접 정의                          |
| `cpx check` / `cpx format` / `cpx test` | 폐지. `cpx pint`·`cpx phpstan`·`cpx pest` 등 직접 실행 |
| `cpx version` / `-v`                    | 폐지. `cpx --version` 사용                          |
| `cpx script.php` (파일 직접 실행)             | 폐지. `cpx exec script.php` 필요                    |
| `composer_require()`                    | `cpx_require()`로 이름 변경                          |

## 관련 페이지

`~/.cpx` 디렉터리의 캐시나 구버전 패키지는 자동으로 새 형식으로 이행되지만, 버전 제약 포함으로 실행되던 패키지는 새 디렉터리명으로 관리되므로 처음에만 재설치됩니다. 필요 없어진 1.x 시절 복사본은 `cpx clean`으로 삭제할 수 있습니다.

<Card title="laravel/cpx 리포지토리" icon="github" href="https://github.com/laravel/cpx">
  소스 코드와 최신 README는 여기.
</Card>

<Card title="cpx 2.0 업그레이드 가이드" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  1.x에서 2.x로의 자세한 마이그레이션 절차.
</Card>


## Related topics

- [GitHub Actions의 핀 고정과 보안](/ko/advanced/github-actions-pinning.md)
- [Testbench Workbench로 패키지 개발 진행하기](/ko/advanced/package-workbench.md)
- [패키지 자동 감지의 내부 구조](/ko/advanced/package-discovery.md)
- [Crypto — AT Protocol 암호화](/ko/packages/laravel-bluesky/crypto.md)
- [Laravel MCP](/ko/mcp.md)