# CLI Reference All commands can be run via `bunx @varlock/bumpy ` (or just `bunx bumpy` if installed locally). Alternatively, you can invoke it via a package.json script (e.g., `bun run bumpy `). ## `bumpy init` Initialize the `.bumpy/` config directory. If `.changeset/` is detected, it automatically migrates — renaming the directory to `.bumpy/`, converting config, keeping pending bump files, and offering to uninstall `@changesets/cli`. Also ensures `@varlock/bumpy` is installed as a dev dependency and warns about changeset references in GitHub workflows. ```bash bumpy init bumpy init --force # skip interactive prompts ``` | Flag | Description | | --------- | ------------------------ | | `--force` | Skip interactive prompts | ## `bumpy add` Create a bump file interactively or non-interactively. ```bash bumpy add # interactive bumpy add --packages "core:minor,utils:patch" --message "Added features" # non-interactive bumpy add --empty --name "docs-only-pr" # empty (no releases) bumpy add --none # all changed packages → none ``` | Flag | Description | | ------------------- | ------------------------------------------------------------------------------------- | | `--packages ` | Comma-separated `name:level` pairs | | `--message ` | Changelog description | | `--name ` | Bump file filename (auto-slugified) | | `--empty` | Create an empty bump file (marks a PR as intentionally having no releases) | | `--none` | Set all changed packages to `none` (acknowledge without bumping, for `--strict` mode) | ## `bumpy status` Preview the release plan based on pending bump files. ```bash bumpy status bumpy status --json bumpy status --packages bumpy status --bump major --filter "@myorg/*" bumpy status --verbose ``` | Flag | Description | | ------------------ | -------------------------------------------------------------- | | `--json` | Output the full release plan as JSON | | `--packages` | Output only package names, one per line (useful for scripting) | | `--bump ` | Filter by bump type, e.g. `"major"` or `"minor,patch"` | | `--filter ` | Filter by package name or glob | | `--verbose` | Show bump file details and summaries | | `--channel ` | Channel override (default: inferred from the current branch) | Exits with code `0` if releases are pending, `1` if none. On a [prerelease channel](prereleases.md) branch, status shows the cycle instead: shipped vs pending bump files and the derived `-.N` versions (counters come from the registry; offline they render as `.?`). ## `bumpy version` Consume all pending bump files and apply the release plan: 1. Reads bump files and computes the release plan (including dependency propagation) 2. Updates `package.json` versions 3. Generates CHANGELOG.md entries 4. Deletes consumed bump files 5. Updates the lockfile 6. Optionally commits (with `--commit` flag) ```bash bumpy version bumpy version --commit ``` | Flag | Description | | ------------------ | ------------------------------------------------------------ | | `--commit` | Commit the version changes to git | | `--channel ` | Channel override (default: inferred from the current branch) | On a [prerelease channel](prereleases.md) branch, `bumpy version` does something much smaller: it **moves pending bump files into `.bumpy//`** and writes no versions and no changelogs — prerelease versions are derived at publish time and never committed. ## `bumpy publish` Publish packages that have been versioned but not yet published. For each package, bumpy packs a tarball (resolving `workspace:` and `catalog:` protocols), publishes it, creates a git tag, and after all packages are published, pushes tags and creates GitHub releases. ```bash bumpy publish bumpy publish --dry-run bumpy publish --tag beta bumpy publish --filter "@myorg/*" bumpy publish --snapshot pr-123 ``` | Flag | Description | | ------------------- | ---------------------------------------------------------------------------------------------------- | | `--dry-run` | Preview what would be published without actually doing it | | `--tag ` | npm dist-tag (e.g., `next`, `beta`) | | `--no-push` | Skip pushing git tags to the remote | | `--filter ` | Only publish matching packages (supports globs) | | `--channel ` | Channel override (default: inferred from the current branch) | | `--snapshot ` | Publish a transient [snapshot](snapshots.md#snapshot-releases) (mutually exclusive with `--channel`) | On a [prerelease channel](prereleases.md) branch, publish derives prerelease versions (targets from the cycle's bump files, counters from the registry), transiently writes them into the working tree so pack/build see them, publishes the whole cycle to the channel's dist-tag with exact-pinned inter-cycle deps, then restores the files. Nothing version-shaped is ever committed. With `--snapshot `, publish derives a throwaway prerelease version per pending package (e.g. `1.4.0-pr-123-a1b2c3d`), publishes them to a non-`latest` dist-tag (default: the snapshot name), then restores the working tree. It never consumes bump files, writes changelogs, commits, tags, or creates GitHub releases — it's the private-registry counterpart to [pkg.pr.new](https://pkg.pr.new). Requires pending bump files. See [Snapshot releases](snapshots.md#snapshot-releases). **How bumpy detects unpublished packages:** 1. Custom `checkPublished` command (if configured per-package — see [`allowCustomCommands`](./configuration.md#custom-commands-and-allowcustomcommands)) 2. Git tags (for packages with `skipNpmPublish` or custom `publishCommand`) 3. npm registry query (default) ## `bumpy check` Verify that changed packages on the current branch have corresponding bump files. Compares your branch to the base branch, maps changed files to packages, and checks for matching bump files. By default, exits non-zero only if **no** bump files exist at all (matching changesets behavior). Use `--strict` to require every changed package to be covered, or set [`requireBumpFile`](./configuration.md#requirebumpfile--packages-that-must-always-be-bumped) on specific packages. ```bash bumpy check bumpy check --strict bumpy check --no-fail bumpy check --hook pre-commit bumpy check --hook pre-push ``` | Flag | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `--strict` | Fail if any changed package is not covered by a bump file | | `--no-fail` | Warn only, never exit non-zero (useful for advisory hooks) | | `--hook pre-commit` | Only count staged + committed bump files | | `--hook pre-push` | Only count committed bump files | | `--base ` | Branch to compare against (default: `baseBranch`) — use the channel branch for feature branches targeting a [channel](prereleases.md) | The check is skipped automatically on channel branches and release PR branches (they move/consume bump files by design). ### Hook context By default (no `--hook` flag), bumpy detects all bump files — including untracked and staged files that haven't been committed yet. This is convenient when running `bumpy check` manually. When used as a git hook, `--hook` controls which bump files count: - **`--hook pre-commit`** — staged and committed bump files count. Untracked bump files are warned about (they won't be included in the commit). - **`--hook pre-push`** — only committed bump files count. Staged and untracked bump files are warned about (they won't be included in the push). The output also annotates bump files with their git status (`staged`, `untracked`) so you can see at a glance what's been committed. No GitHub API needed. ## `bumpy generate` Auto-create bump files from commits on the current branch. Works with any commit style — conventional commits get enhanced bump-level detection, while all other commits are mapped to packages via changed file paths (defaulting to `patch`). ```bash bumpy generate bumpy generate --dry-run bumpy generate --from v1.0.0 # override: scan from a specific ref instead of branch base bumpy generate --deps # one patch bump file per package whose dependencies changed ``` | Flag | Description | | --------------- | ------------------------------------------------------------------------------------------- | | `--from ` | Git ref to scan from (default: branch point from `baseBranch` in config) | | `--dry-run` | Preview without creating files | | `--name ` | Bump file filename (with `--deps`: filename suffix, default: current branch) | | `--deps` | Generate from dependency changes instead of commits — see [`bumpy ci deps`](#bumpy-ci-deps) | **How commits are mapped:** 1. **Conventional commits** (`type(scope): description`) use the commit type for bump level and the scope to resolve to a package name: - `feat:` → minor - `fix:`, `perf:`, `refactor:`, `docs:`, `style:`, `test:`, `build:`, `ci:`, `chore:` → patch - `feat!:` or `BREAKING CHANGE:` → major 2. **All other commits** (including scopeless conventional commits) are mapped to packages by detecting which files changed in the commit and matching them to package directories. These default to `patch`. - If the commit changes a **catalog entry** (in `pnpm-workspace.yaml`, `.yarnrc.yml`, or the root `package.json`), every package that references that entry via `catalog:` is included — so a Renovate/Dependabot catalog bump maps to its consumers, matching what `bumpy check` requires. When multiple commits affect the same package, the highest bump level wins. ## `bumpy ci check` CI command for PR checks. Computes the release plan from bump files changed in the current PR and posts/updates a comment on the PR. ```bash bumpy ci check bumpy ci check --strict bumpy ci check --no-fail bumpy ci check --emit-comment ./bumpy-comment ``` | Flag | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `--comment` | Force PR comment on or off (default: auto-detect CI environment) | | `--strict` | Fail if any changed package is not covered by a bump file | | `--no-fail` | Warn only, never exit non-zero | | `--emit-comment ` | Also write the rendered comment to `/comment.md` for a downstream [`ci comment`](#bumpy-ci-comment) to post (the fork-comment split) | Requires `GH_TOKEN` environment variable (automatically available in GitHub Actions). **On channel and promotion PRs:** for a PR targeting a [prerelease channel](prereleases.md) branch, the comment is channel-aware — it shows the prerelease plan (`-.x` versions) and the target dist-tag rather than implying a stable release. For a **promotion PR** (a channel branch → `main`, or a graduation like `alpha` → `beta`), the check reads the cycle's already-shipped bump files from `.bumpy//` and shows the consolidated stable plan, calling out that merging ends the prerelease cycle. (Feature PRs that _target_ a channel branch are checked against that branch, so only the PR's own new bump files count — see [`--base`](#bumpy-check) on the local `check` command for the equivalent locally.) ## `bumpy ci comment` Posts a pre-rendered comment (from `ci check --emit-comment`) to a PR. This is the privileged half of the [fork-comment split](github-actions.md#commenting-on-fork-prs): your `pull_request` check renders the comment as an artifact, and this command — run from a `workflow_run` job — posts it. ```bash bumpy ci comment --body-file ./bumpy-comment/comment.md ``` | Flag | Description | | -------------------- | ------------------------------------------------------------------ | | `--body-file ` | Path to the rendered comment body (required) | | `--pr ` | Target PR number (default: resolved from the `workflow_run` event) | It needs no checkout and no bumpy project — it only posts. Under `workflow_run` it resolves the target PR from the **trusted** event (`head_sha`), never from the artifact, and treats the body as untrusted text. A missing or empty body file is a no-op. Requires `GH_TOKEN`. ## `bumpy ci deps` For dependency-update PRs (Dependabot, Renovate). Writes one patch bump file per package whose `dependencies` / `peerDependencies` / `optionalDependencies` (or [`releaseTriggeringDevDeps`](configuration.md#release-triggering-devdependencies)) changed, as `.bumpy/deps-pr-.md`, then commits and pushes them to the PR branch. Idempotent — re-running rewrites the files and removes stale ones. See [Dependency update PRs](github-actions.md#dependency-update-prs-dependabot--renovate) for the workflow. ```bash bumpy ci deps bumpy ci deps --no-push ``` | Flag | Description | | ----------- | ------------------------------------ | | `--no-push` | Commit the bump files but don't push | ## `bumpy ci plan` CI command that reports what `ci release` would do, without acting. Outputs JSON to stdout and sets GitHub Actions step outputs so you can conditionally run expensive steps (builds, etc.) only when needed. ```bash bumpy ci plan ``` **Output (JSON to stdout):** ```jsonc { "mode": "version-pr", // "version-pr" | "publish" | "nothing" "bumpFiles": [...], // same shape as `bumpy status --json` "releases": [...], "packageNames": ["pkg-a", "pkg-b"] } ``` **Modes:** | Mode | Meaning | `releases` contains | | ------------ | ------------------------------------------------------ | -------------------------------- | | `version-pr` | Bump files exist — would create/update the version PR | Planned releases from bump files | | `publish` | No bump files — unpublished packages detected | Packages that would be published | | `nothing` | No bump files, no unpublished packages — nothing to do | Empty | **GitHub Actions outputs** (set via `$GITHUB_OUTPUT`): | Output | Description | | ---------- | ------------------------------------------------------------- | | `mode` | `version-pr`, `publish`, or `nothing` | | `packages` | JSON array of package names (for `fromJSON()` + `contains()`) | | `json` | Full JSON output (for `fromJSON()`) | When `ci plan` runs before `ci release` in the same workflow, the plan is cached so `ci release` can skip duplicate registry lookups. The cache is validated against the workspace (package names and versions must match) and deleted after use. See [GitHub Actions setup](github-actions.md) for workflow examples. ## `bumpy ci release` CI command for releases. Has two modes: **Version PR mode (default):** If pending bump files exist, creates or updates a "Version Packages" PR with all version bumps and changelog updates. If the current push is the Version Packages PR being merged, publishes the new versions, creates git tags, and creates GitHub releases. **Auto-publish mode (`--auto-publish`):** Versions and publishes directly on merge without an intermediate PR. **Not recommended** — you lose the version-PR preview/review gate, so every merge to main with a bump file ships immediately. It's also incompatible with the [split-job workflow](github-actions.md#release-workflow-recommended-split-jobs) (since both paths happen in one run). The credential surface itself is the same as a single-job non-auto-publish workflow — the cost here is purely the loss of the preview gate. **Snapshot mode (`--snapshot `):** Publishes a transient [snapshot](snapshots.md#snapshot-releases) and, on a PR, posts/updates a comment with the published versions and install instructions. A single self-contained step — no version-PR/publish split, no branch routing — so it can run from any branch (typically a feature PR). Incompatible with `--expect-mode` and `--auto-publish`. ```bash bumpy ci release bumpy ci release --auto-publish bumpy ci release --auto-publish --tag beta bumpy ci release --snapshot pr-123 ``` | Flag | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--expect-mode ` | Assert detected mode: `version-pr` or `publish`. Errors if the detected mode differs. Use to gate split-job workflows so a job can't silently fall into the wrong path. | | `--auto-publish` | Version + publish directly instead of creating a PR | | `--tag ` | npm dist-tag (for `--auto-publish`, or the snapshot dist-tag) | | `--branch ` | Version PR branch name (default: `bumpy/version-packages`) | | `--snapshot ` | Publish a transient [snapshot](snapshots.md#snapshot-releases) and comment install instructions on the PR | Requires `GH_TOKEN`. When `BUMPY_GH_TOKEN` is set, it is automatically used to push the version branch and create/edit the PR so that PR workflows trigger (see [GitHub Actions setup](github-actions.md#token-setup)). **Channel branches:** when run on a branch configured as a [prerelease channel](prereleases.md), `ci release` switches to the channel flow — it publishes the cycle when the triggering push moved bump files into `.bumpy//` (a release PR merge), and creates/updates the file-move release PR when pending bump files exist. When channels are configured and the branch is neither `baseBranch` nor a channel branch, the command exits with an error instead of guessing. ## `bumpy ci setup` Interactive guide to set up `BUMPY_GH_TOKEN` for CI. Walks through creating a fine-grained PAT or GitHub App token and storing it as a repository secret. ```bash bumpy ci setup ```