CLI 레퍼런스

이 레퍼런스는 명령별로 묶었습니다.

최상위 publish 명령: pubm [version]
init, secrets, sync 같은 관리 명령
pubm changesets ... 아래의 changeset 워크플로 명령
미리보기 및 테스트 릴리스를 위한 pubm snapshot 명령

일상적으로 가장 자주 쓰는 명령은 다음입니다.

pubm

버전 인자 없이 pubm을 실행하면 대화형 경로가 됩니다. 릴리스 파이프라인이 계속되기 전에 터미널에서 다음 버전을 고를 수 있습니다.

명령 개요

명령	용도
`pubm [version]`	release type 또는 명시적 semver를 사용해 publish 파이프라인을 실행합니다.
`pubm snapshot [tag]`	미리보기 및 테스트를 위한 snapshot 버전을 publish합니다.
`pubm init`	대화형 설정 마법사로, 패키지 감지, 설정, changeset, CI 워크플로, 코딩 에이전트 스킬을 처리합니다.
`pubm setup-skills`	코딩 에이전트 스킬을 다운로드하고 설치합니다(Claude Code, Codex, Gemini).
`pubm secrets sync`	로컬에 저장된 토큰을 `gh`를 통해 GitHub Secrets로 밀어 넣습니다.
`pubm sync --discover`	매니페스트 파일 밖의 version 참조를 저장소에서 스캔합니다.
`pubm update`	CLI를 최신 공개 버전으로 자체 업데이트합니다.
`pubm changesets add`	새 changeset을 만듭니다.
`pubm changesets status`	보류 중인 changeset과 bump 영향을 보여줍니다.
`pubm changesets version`	changeset을 소비하고 새 버전을 기록합니다.
`pubm changesets changelog`	보류 중인 changeset에서 changelog 텍스트를 만듭니다.
`pubm changesets migrate`	`.changeset/`에서 `.pubm/`으로 마이그레이션합니다.

최상위 publish 명령

문법

pubm [version] [flags]

[version]은 다음 중 하나일 수 있습니다.

semver bump type: patch, minor, major
pre-release bump type: prepatch, preminor, premajor, prerelease
1.8.0 같은 명시적 버전

버전을 생략하면:

대화형 터미널은 다음 버전을 물을 수 있습니다.
CI 실행은 버전이 비대화형으로 해석되어야 합니다.

대화형 사용

pubm

일반적인 흐름:

pubm을 실행합니다.
patch, minor, major 중 하나를 고릅니다.
pubm이 검사, 빌드, 태깅, publish를 계속 진행하게 둡니다.

일반적인 예시

pubm
pubm --dry-run
pubm 1.8.0
pubm --registry npm,jsr
pubm --tag beta

Publish 플래그

플래그	기본값	설명
`-d, --dry-run`	`false`	Git 상태를 바꾸거나 publish하지 않고 작업 그래프만 보여줍니다.
`--mode <mode>`	`local`	실행 모드입니다. `local`은 대화형, `ci`는 비대화형이고 tag 기반입니다.
`--phase <phase>`	-	파이프라인 단계입니다. `prepare`는 검증과 dry-run, `publish`는 최신 태그에서 publish입니다.
`--release-draft`	`false`	publish된 release 대신 draft GitHub Release를 만듭니다.
`-b, --branch <name>`	`main`	publish 전에 현재 브랜치가 일치해야 합니다.
`-a, --any-branch`	`false`	현재 실행에서 브랜치 가드를 비활성화합니다.
`-t, --tag <name>`	`latest`	`beta`, `next` 같은 특정 dist-tag를 사용합니다.
`-c, --contents <path>`	없음	release pipeline을 실행하기 전에 하위 디렉터리로 이동합니다.
`--registry <registries>`	`npm,jsr`	쉼표로 구분한 대상 registry입니다. `npm`, `jsr`, `crates`, 또는 커스텀 registry URL을 지원합니다.
`--test-script <script>`	`test`	테스트 단계에서 사용할 스크립트 이름입니다.
`--build-script <script>`	`build`	빌드 단계에서 사용할 스크립트 이름입니다.
`--no-save-token`	`false`	지원되는 토큰을 이후 실행을 위해 저장하지 않습니다.
`--dangerously-allow-unpublish`	`false`	비-TTY 환경에서 롤백 중 레지스트리 unpublish/yank를 허용합니다.
`--locale <locale>`	`en`	CLI 출력 언어를 설정합니다. 지원 언어: `en`, `ko`, `zh-cn`, `fr`, `de`, `es`.
`--create-pr`	`false`	직접 push하는 대신 version bump를 위한 pull request를 생성합니다.

파이프라인 제어 플래그

플래그	설명
`--no-pre-check`	branch와 working tree 검증 같은 사전 검사를 생략합니다.
`--no-condition-check`	토큰과 registry 검증 같은 필수 조건 검사를 생략합니다.
`--no-tests`	테스트 단계를 생략합니다.
`--no-build`	빌드 단계를 생략합니다.
`--no-publish`	publish 직전까지 실행하되, 실제로는 artifacts를 publish하지 않습니다.
`--skip-release`	GitHub Release 생성을 생략합니다.

실행 모드

대화형 로컬 실행

로컬 릴리스의 일반 모드입니다.

pubm

동작:

version 인자가 없으면 대화형 version 선택으로 시작합니다.
필요한 정보가 없으면 프롬프트가 표시될 수 있습니다.
생략되지 않았다면 테스트와 빌드를 실행합니다.
versioning, publish, push, GitHub Release 단계가 순서대로 실행됩니다.

Dry-run 모드

pubm --dry-run

부작용 없이 작업 계획을 확인해야 할 때 사용합니다.

CI 준비 모드

pubm --mode ci --phase prepare

CI 준비:

누락된 토큰을 대화형으로 수집할 수 있습니다.
이를 GitHub Secrets로 동기화할 수 있습니다.
CI를 모방하도록 비대화형 동작으로 전환합니다.
사전 조건과 필수 조건 검사를 실행합니다.
설정된 registry에 대해 publish를 dry-run합니다.

CI publish 모드

pubm --mode ci --phase publish

CI publish 모드는 최신 Git tag에서 publish하고 GitHub Release를 API로 생성합니다. version bump와 태깅이 파이프라인의 앞 단계에서 이미 끝났을 때 사용합니다. --release-draft를 넘기면 published release 대신 draft release를 만듭니다.

환경 변수

변수	용도
`NODE_AUTH_TOKEN`	CI에서 npm 인증
`JSR_TOKEN`	jsr 인증
`CARGO_REGISTRY_TOKEN`	crates.io 인증
`PUBM_LOCALE`	CLI 출력 언어 (`en`, `ko`, `zh-cn`, `fr`, `de`, `es`)

프롬프트는 다음 경우 자동으로 비활성화됩니다.

stdin이 TTY가 아닐 때
프로세스가 인식된 CI 플랫폼에서 실행될 때

`pubm snapshot`

미리보기 및 테스트를 위한 snapshot 버전을 publish합니다. 단일 패키지와 모노레포 프로젝트 모두 지원합니다.

pubm snapshot [tag]

옵션	설명
`[tag]`	Snapshot 태그 (기본값: `snapshot`)
`-f, --filter <name>`	이름 또는 경로로 패키지 필터링 (반복 가능)
`-d, --dry-run`	부작용 없이 시뮬레이션
`--no-tests`	테스트 건너뜀
`--no-build`	빌드 건너뜀
`-b, --branch <name>`	대상 브랜치 (기본값: `main`)
`-a, --any-branch`	모든 브랜치에서 publish 허용

예시

# 모든 패키지 snapshot
pubm snapshot

# 커스텀 태그로 snapshot
pubm snapshot beta

# 특정 패키지 snapshot
pubm snapshot --filter @pubm/core --filter pubm

`pubm init`

pubm을 위한 대화형 설정 마법사입니다. TTY가 필요합니다.

pubm init

마법사는 다음 단계를 차례로 진행합니다.

패키지 감지: 저장소에서 매니페스트 파일(package.json, jsr.json, deno.json, deno.jsonc, Cargo.toml)과 워크스페이스 설정을 스캔한 뒤, 감지된 패키지와 레지스트리를 확인합니다.
기본 설정: 릴리스 브랜치와 버전 전략(independent 또는 fixed)을 묻습니다.
릴리스 옵션: changelog 생성과 GitHub Release 초안에 대해 묻습니다.
워크플로 설정: changeset 워크플로 활성화(.pubm/changesets/, .github/workflows/changeset-check.yml 생성 및 .gitignore 업데이트)와 CI 릴리스 워크플로(.github/workflows/release.yml) 생성을 제안합니다.
코딩 에이전트 스킬: Claude Code, Codex CLI, Gemini CLI용 코딩 에이전트 스킬 다운로드 및 설치를 제안합니다. 이는 pubm setup-skills와 같습니다.

선택 사항이 기본값과 다를 때만 pubm.config.ts 파일이 생성됩니다. 모든 값이 기본값과 일치하면 설정 파일은 작성되지 않습니다.

이 명령은 플래그나 옵션을 받지 않습니다. 모든 설정은 대화형으로 수집됩니다.

`pubm setup-skills`

pubm에 사용할 코딩 에이전트 스킬을 다운로드하고 설치합니다.

pubm setup-skills

지원되는 에이전트와 설치 경로:

에이전트	스킬 디렉터리
Claude Code	`.claude/skills/pubm/`
Codex CLI	`.agents/skills/pubm/`
Gemini CLI	`.gemini/skills/pubm/`

스킬은 pubm GitHub 저장소(최신 릴리스 태그, main 브랜치를 폴백으로 사용)에서 다운로드됩니다.

이 명령은 pubm init의 마지막 단계로도 사용할 수 있습니다.

`pubm secrets sync`

gh CLI를 사용해 로컬에 저장된 토큰을 GitHub Secrets로 보냅니다.

pubm secrets sync
pubm secrets sync --registry npm
pubm secrets sync --registry npm,jsr

플래그	기본값	설명
`--registry <registries>`	`npm,jsr,crates`	특정 registry로 secret sync를 제한합니다.

주의:

gh가 설치되고 인증되어 있어야 합니다.
로컬에 저장된 토큰을 사용하므로, 아직 아무것도 저장되지 않았다면 먼저 pubm --mode ci --phase prepare를 실행합니다.

`pubm sync --discover`

매니페스트 파일 밖의 version 참조를 저장소에서 스캔합니다.

pubm sync --discover

이 명령은 version-sync 플러그인 설정을 돕기 위해 만들어졌습니다. 일반적으로 생성되는 디렉터리와 lockfile은 건너뛴 뒤, plugin config에 옮겨 쓸 수 있는 후보 파일과 JSON path 또는 일치하는 라인을 출력합니다.

`pubm update`

설치된 pubm CLI를 최신 공개 버전으로 업데이트합니다.

pubm update

Changeset 명령

모든 changeset 생명주기 명령은 pubm changesets 아래에 있습니다.

`pubm changesets add`

새 changeset을 만듭니다.

pubm changesets add
pubm changesets add --empty
pubm changesets add --packages @acme/core,@acme/react --bump minor --message "Add public metrics API."

플래그	설명
`--empty`	빈 changeset 파일을 만듭니다.
`--packages <list>`	비대화형 생성을 위한 쉼표 구분 패키지 이름입니다.
`--bump <type>`	`patch`, `minor`, `major` 중 하나입니다.
`--message <text>`	changeset 본문과 changelog에 사용할 요약입니다.

`pubm changesets status`

보류 중인 changeset을 확인합니다.

pubm changesets status
pubm changesets status --verbose
pubm changesets status --since origin/main

플래그	설명
`--verbose`	기록된 각 changeset 요약을 출력합니다.
`--since <ref>`	Git ref 이후를 확인합니다.

`pubm changesets version`

changeset을 소비하고, manifest 버전을 업데이트하고, changelog를 쓰고, 결과를 commit합니다.

보류 중인 changeset 파일이 없는 패키지의 경우, pubm changesets version은 bump 타입을 결정하기 위해 conventional commits로 폴백할 수 있습니다. 이 동작은 versionSources 설정 옵션으로 제어됩니다. 자세한 내용은 설정 가이드를 참조합니다.

pubm changesets version
pubm changesets version --dry-run

플래그	설명
`--dry-run`	파일을 쓰지 않고 version과 changelog 계획만 출력합니다.

`pubm changesets changelog`

보류 중인 changeset에서 changelog 텍스트를 생성합니다.

pubm changesets changelog
pubm changesets changelog --dry-run
pubm changesets changelog --version 1.8.0

플래그	설명
`--dry-run`	`CHANGELOG.md`를 쓰지 않고 changelog 출력을 미리 봅니다.
`--version <ver>`	`Unreleased` 대신 특정 섹션 제목을 사용합니다.

`pubm changesets migrate`

보류 중인 파일을 기존 .changeset/ 레이아웃에서 .pubm/으로 옮깁니다.

pubm changesets migrate

종료 코드

pubm은 다음 경우 0이 아닌 종료 코드를 반환합니다.

사전 조건 또는 필수 조건 검사가 실패할 때
version resolution을 끝낼 수 없을 때
어떤 target에서든 publish가 실패할 때
subcommand가 잘못된 입력을 받을 때

일반 publish 모드에서는 가능한 경우 실패 후 롤백도 수행합니다.

예시 명령 패턴

새 저장소에서 첫 로컬 릴리스

pubm init
pubm changesets add
pubm changesets version
pubm --mode ci --phase prepare
pubm --dry-run
pubm

로컬 CI 리허설

pubm --mode ci --phase prepare

CI에서 현재 태그된 릴리스만 publish

pubm --mode ci --phase publish

준비 후 저장된 토큰 동기화

pubm secrets sync