CLI Reference

This reference is grouped by command:

the top-level publish command: pubm [version]
management commands such as init, secrets, and sync
changeset workflow commands under pubm changesets ...
the pubm snapshot command for preview and testing releases

For most day-to-day use, the main command is:

pubm

Running pubm without a version argument follows the interactive path. You choose the next version in the terminal before the release pipeline continues.

Command overview

Command	Purpose
`pubm [version]`	Run the publish pipeline using a release type or explicit semver.
`pubm snapshot [tag]`	Publish snapshot versions for preview and testing.
`pubm init`	Interactive setup wizard for package detection, config, changesets, CI workflows, and coding agent skills.
`pubm setup-skills`	Download and install coding agent skills (Claude Code, Codex, Gemini).
`pubm secrets sync`	Push locally stored tokens into GitHub Secrets through `gh`.
`pubm sync --discover`	Scan the repository for version references outside manifest files.
`pubm update`	Self-update the CLI to the latest published version.
`pubm changesets add`	Create a new changeset.
`pubm changesets status`	Show pending changesets and their bump impact.
`pubm changesets version`	Consume changesets and write new versions.
`pubm changesets changelog`	Render changelog text from pending changesets.
`pubm changesets migrate`	Migrate from `.changeset/` to `.pubm/`.

Top-level publish command

Syntax

pubm [version] [flags]

[version] can be:

a semver bump type: patch, minor, major
a pre-release bump type: prepatch, preminor, premajor, prerelease
an explicit version such as 1.8.0

If you omit the version:

interactive terminals can prompt for the next version
CI runs require the version to be resolved non-interactively

Interactive usage

pubm

Typical flow:

run pubm
choose patch, minor, or major
let pubm continue through checks, build, tagging, and publish

Common examples

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

Publish flags

Flag	Default	Description
`-d, --dry-run`	`false`	Show the task graph without mutating Git state or publishing.
`--mode <mode>`	`local`	Execution mode: `local` (interactive) or `ci` (non-interactive, tag-based).
`--phase <phase>`	-	Pipeline phase: `prepare` (validate and dry-run) or `publish` (publish from latest tag).
`--release-draft`	`false`	Create a draft GitHub Release instead of a published one.
`-b, --branch <name>`	`main`	Require the current branch to match before releasing.
`-a, --any-branch`	`false`	Disable the branch guard for the current run.
`-t, --tag <name>`	`latest`	Use a specific dist-tag such as `beta` or `next`.
`-c, --contents <path>`	none	Change into a subdirectory before running the release pipeline.
`--registry <registries>`	`npm,jsr`	Comma-separated target registries. Supports `npm`, `jsr`, `crates`, or custom registry URLs.
`--test-script <script>`	`test`	Script name used for the test step.
`--build-script <script>`	`build`	Script name used for the build step.
`--no-save-token`	`false`	Do not persist supported tokens for later runs.
`--dangerously-allow-unpublish`	`false`	Allow registry unpublish/yank during rollback in non-TTY environments.
`--locale <locale>`	`en`	Set CLI output language. Supported: `en`, `ko`, `zh-cn`, `fr`, `de`, `es`.
`--create-pr`	`false`	Create a pull request for the version bump instead of pushing directly.

Pipeline-control flags

Flag	Description
`--no-pre-check`	Skip prerequisite checks such as branch and working tree validation.
`--no-condition-check`	Skip required-condition checks such as token and registry validation.
`--no-tests`	Skip the test step.
`--no-build`	Skip the build step.
`--no-publish`	Run the pipeline up to publish, but do not actually publish artifacts.
`--skip-release`	Skip GitHub Release creation.

Execution modes

Interactive local run

The normal mode for local releases:

pubm

Behavior:

starts with interactive version selection when no version argument is provided
prompts can be shown when required information is missing
tests and build run unless skipped
versioning, publish, push, and GitHub Release steps run in order

Dry-run mode

pubm --dry-run

Use dry-run mode when you need to inspect the task plan without side effects.

CI prepare mode

pubm --mode ci --phase prepare

CI prepare mode:

collects missing tokens interactively
can sync them to GitHub Secrets
switches into non-interactive behavior to mimic CI
runs prerequisite and condition checks
dry-runs publish for configured registries

CI publish mode

pubm --mode ci --phase publish

CI publish mode publishes from the latest Git tag and creates a GitHub Release via API. Use it when the version bump and tagging already happened earlier in the pipeline. Pass --release-draft to create a draft release instead of a published one.

Environment variables

Variable	Used for
`NODE_AUTH_TOKEN`	npm authentication in CI
`JSR_TOKEN`	jsr authentication
`CARGO_REGISTRY_TOKEN`	crates.io authentication
`PUBM_LOCALE`	CLI output language (`en`, `ko`, `zh-cn`, `fr`, `de`, `es`)

Prompts are disabled automatically when:

stdin is not a TTY
the process is running on a recognized CI platform

`pubm snapshot`

Publish snapshot versions for preview and testing. Supports single-package and monorepo projects.

pubm snapshot [tag]

Option	Description
`[tag]`	Snapshot tag (default: `snapshot`)
`-f, --filter <name>`	Filter packages by name or path (repeatable)
`-d, --dry-run`	Simulate without side-effects
`--no-tests`	Skip tests
`--no-build`	Skip build
`-b, --branch <name>`	Target branch (default: `main`)
`-a, --any-branch`	Allow publishing from any branch

Examples

# Snapshot all packages
pubm snapshot

# Snapshot with custom tag
pubm snapshot beta

# Snapshot specific packages
pubm snapshot --filter @pubm/core --filter pubm

`pubm init`

Interactive setup wizard for pubm. Requires a TTY.

pubm init

The wizard walks through these stages:

Package Detection: scans the repository for manifest files (package.json, jsr.json, deno.json, deno.jsonc, Cargo.toml) and workspace configuration, then confirms the detected packages and registries.
Basic Configuration: prompts for the release branch and versioning strategy (independent or fixed).
Release Options: asks about changelog generation and GitHub Release drafts.
Workflow Setup: offers to enable the changesets workflow (creates .pubm/changesets/, .github/workflows/changeset-check.yml, and updates .gitignore) and generate CI release workflows (.github/workflows/release.yml).
Coding Agent Skills: offers to download and install coding agent skills for Claude Code, Codex CLI, or Gemini CLI. This matches pubm setup-skills.

A pubm.config.ts file is only created when your choices differ from the defaults. If every value matches the default, no config file is written.

This command accepts no flags or options. All configuration is collected interactively.

`pubm setup-skills`

Download and install coding agent skills for use with pubm.

pubm setup-skills

Supported agents and their installation paths:

Agent	Skill directory
Claude Code	`.claude/skills/pubm/`
Codex CLI	`.agents/skills/pubm/`
Gemini CLI	`.gemini/skills/pubm/`

Skills are downloaded from the pubm GitHub repository (latest release tag, with a fallback to the main branch).

This command is also available as the final step of pubm init.

`pubm secrets sync`

Push locally stored tokens into GitHub Secrets using the gh CLI.

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

Flag	Default	Description
`--registry <registries>`	`npm,jsr,crates`	Limit secret sync to specific registries.

Notes:

requires gh to be installed and authenticated
uses locally stored tokens, so run pubm --mode ci --phase prepare first if nothing has been saved yet

`pubm sync --discover`

Scan the repository for version references outside of manifest files.

pubm sync --discover

This command is intended to help set up version-sync plugins. It skips common generated directories and lockfiles, then prints candidate files and JSON paths or matching lines that you can adapt into plugin config.

`pubm update`

Update the installed pubm CLI to the latest published version.

pubm update

Changesets commands

All changeset lifecycle commands live under pubm changesets.

`pubm changesets add`

Create a new changeset.

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

Flag	Description
`--empty`	Create an empty changeset file.
`--packages <list>`	Comma-separated package names for non-interactive creation.
`--bump <type>`	One of `patch`, `minor`, `major`.
`--message <text>`	Summary used in the changeset body and changelog.

`pubm changesets status`

Inspect pending changesets.

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

Flag	Description
`--verbose`	Print each recorded changeset summary.
`--since <ref>`	Check since a Git ref.

`pubm changesets version`

Consume changesets, update manifest versions, write changelogs, and commit the result.

For packages that have no pending changeset files, pubm changesets version can fall back to conventional commits to determine the bump type. This behavior is controlled by the versionSources config option. See the Configuration guide for details.

pubm changesets version
pubm changesets version --dry-run

Flag	Description
`--dry-run`	Print the version and changelog plan without writing files.

`pubm changesets changelog`

Generate changelog text from pending changesets.

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

Flag	Description
`--dry-run`	Preview changelog output without writing `CHANGELOG.md`.
`--version <ver>`	Use a specific section header instead of `Unreleased`.

`pubm changesets migrate`

Move pending files from the legacy .changeset/ layout into .pubm/.

pubm changesets migrate

Exit codes

pubm returns a non-zero exit code when:

a prerequisite or condition check fails
version resolution cannot be completed
publish fails on any target
a subcommand encounters invalid input

In normal publish mode, failures also trigger rollback behavior where possible.

Example command patterns

First local release on a new repository

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

Local CI rehearsal

pubm --mode ci --phase prepare

Publish only the current tagged release in CI

pubm --mode ci --phase publish

Sync stored tokens after preparation

pubm secrets sync