CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
The pubm CLI is a tool designed to streamline the publishing of packages to multiple registries simultaneously, including npm, JSR, and crates.io. It provides a unified interface for managing versions, changesets, and CI/CD workflows, ensuring consistency across different ecosystems like JavaScript/TypeScript and Rust. Sources: CLAUDE.md:6-8, packages/core/src/i18n/locales/en.json:281-282
The CLI is built using the commander library and supports various operational modes, including interactive local usage and headless CI environments. It handles preflight checks, build/test execution, version bumping, and automated rollbacks on failure. Sources: packages/pubm/src/cli.ts:110-115, CLAUDE.md:6-8
Core Global Options
Every pubm execution supports a set of global configuration options that modify the behavior of the tool regardless of the specific command or argument provided.
| Option | Description |
|---|---|
--config <path> | Specifies a custom path to the pubm.config.ts file. |
--no-color | Disables colored output in the terminal. |
--locale <locale> | Sets the output language (e.g., en, ko, fr). |
--version | Displays the current version of the pubm utility. |
Sources: packages/pubm/src/cli.ts:117-123, packages/core/src/i18n/locales/en.json:282-284
Primary Commands
Default Command: Publish
Running pubm [version] without a specific subcommand initiates the publishing pipeline. It accepts an optional version argument (e.g., patch, 1.2.3) and supports extensive flags for controlling the release lifecycle.
Publishing Options:
--mode <local|ci>: Defines the environment context. Sources: packages/pubm/src/cli.ts:223--phase <prepare|publish>: Splits the pipeline into token collection (prepare) and actual distribution (publish). Sources: packages/pubm/src/cli.ts:225--dry-run: Validates the process without applying side effects. Sources: packages/pubm/src/cli.ts:153--registry <registries>: Overrides auto-detected registries (comma-separated). Sources: packages/pubm/src/cli.ts:167-170--create-pr: Creates a pull request for the version bump instead of pushing directly. Sources: packages/core/src/i18n/locales/en.json:299
init
Initializes pubm in a new or existing project through an interactive wizard. It detects the project structure (monorepo vs. single package), configures versioning strategies, and sets up CI workflows. Sources: packages/pubm/src/commands/init.ts:35-50
version
Consumes pending changesets or conventional commits to calculate the next version for packages and update manifest files (e.g., package.json, Cargo.toml). Sources: packages/pubm/src/commands/version-cmd.ts:37-45, packages/core/src/i18n/locales/en.json:344
Key Logic:
- Analyze Sources: Gathers recommendations from
.pubm/changesetsor Git history. Sources: packages/pubm/src/commands/version-cmd.ts:50-70 - Apply Groups: Enforces
fixedorlinkedversioning groups defined in the config. Sources: packages/pubm/src/commands/version-cmd.ts:98-118 - Write Manifests: Updates ecosystem-specific files and generates
CHANGELOG.mdentries. Sources: packages/pubm/src/commands/version-cmd.ts:154-165 - Git Commit: Creates a standardized release commit (e.g., "Version Packages"). Sources: packages/pubm/src/commands/version-cmd.ts:175-185
Workspace and Ecosystem Commands
sync
Manages version synchronization across non-manifest files. Use pubm sync --discover to scan the project for hardcoded version strings in READMEs or configuration files. Sources: packages/core/src/i18n/locales/en.json:348-353
inspect
Provides transparency into the detected project structure.
pubm inspect packages: Lists all detected packages, their current versions, and their target registries. Sources: packages/core/src/i18n/locales/en.json:360-365--json: Outputs the inspection data in JSON format for programmatic use. Sources: packages/core/src/i18n/locales/en.json:362
Lifecycle Management Commands
secrets
Manages registry authentication tokens.
pubm secrets sync: Synchronizes locally stored tokens to GitHub Secrets for use in CI/CD pipelines. Sources: packages/core/src/i18n/locales/en.json:369-370
snapshot
Publishes temporary "snapshot" versions for testing or preview purposes, typically using a specific dist-tag (default: snapshot). Sources: packages/core/src/i18n/locales/en.json:390-391
migrate
Automates the transition from other release tools (e.g., semantic-release, release-it, changesets) to pubm by converting their configurations into a pubm.config.ts file. Sources: packages/core/src/i18n/locales/en.json:376-382
Summary of Commands
| Command | Purpose | Files Involved |
|---|---|---|
init | Interactive project setup | pubm.config.ts, .github/workflows/ |
version | Calculate bumps & update manifests | package.json, Cargo.toml, CHANGELOG.md |
add | Create new changeset | .pubm/changesets/*.md |
status | View pending changesets | .pubm/changesets/ |
snapshot | Temporary preview release | Registry specific |
update | Update pubm CLI | Global install |
Sources: packages/core/src/i18n/locales/en.json:315-392, packages/pubm/src/commands/init.ts:130-150