lpm version command reference

Change a package version, preview the change, and optionally create a Git commit and tag.

Change the current package's version before a release.

lpm version [OPTIONS] <BUMP>

Choose a named increment or an exact version. By default, LPM CLI updates package.json, creates a Git commit, and adds a tag.

Quickstart

From a package with version 1.2.3 and a clean Git worktree:

lpm version patch
# package.json: 1.2.4
# Git commit: v1.2.4
# Git tag: v1.2.4

Mode	Result
Default	Update the manifest, commit it, and create a tag
`--no-git-tag-version`	Update the manifest without a Git commit or tag
`--dry-run`	Show the planned version without changing the manifest or Git history

The command does not publish a package or push Git changes. Use lpm publish to publish the new version.

Examples

# Preview a minor release
lpm version minor --dry-run

# Set an exact forward version
lpm version 2.0.0

# Start a prerelease, then increment it
lpm version prepatch
lpm version prerelease

# Customize the commit message and tag prefix
lpm version minor --message "release %s" --tag-prefix "widget-v"

# Let another tool manage Git history
lpm version patch --no-git-tag-version

# Return a machine-readable preview
lpm version patch --dry-run --json

There is no version block in lpm.json. The current package.json supplies the version. Command flags control the increment and Git behavior.

Choose a version

Bump	Behavior	Example
`patch`	Increment the patch, or remove the current prerelease suffix	`1.2.3` → `1.2.4`; `1.2.3-rc.1` → `1.2.3`
`minor`	Increment the minor and reset the patch; promote a prerelease with patch `0`	`1.2.3` → `1.3.0`; `1.3.0-rc.1` → `1.3.0`
`major`	Increment the major and reset minor and patch; promote a prerelease with minor and patch `0`	`1.2.3` → `2.0.0`; `2.0.0-rc.1` → `2.0.0`
`prepatch`	Increment the patch and append `-0`	`1.2.3` → `1.2.4-0`
`preminor`	Increment the minor, reset the patch, and append `-0`	`1.2.3` → `1.3.0-0`
`premajor`	Increment the major, reset minor and patch, and append `-0`	`1.2.3` → `2.0.0-0`
`prerelease`	Increment the rightmost numeric prerelease identifier; append `.0` if none exists	`1.2.3-alpha.1.beta` → `1.2.3-alpha.2.beta`
An exact version	Set a version with higher SemVer precedence	`1.2.3` → `2.0.0`

From a stable version, prerelease starts the next patch prerelease: 1.2.3 becomes 1.2.4-0.

Named increments remove build metadata. Exact versions preserve build metadata, including leading zeros such as 1.3.0+001. A build-metadata change alone does not increase version precedence.

Existing versions can have an optional v prefix. New versions omit that prefix. Numeric overflow returns an error before a manifest change.

Git behavior

The default mode requires an existing Git commit and a clean worktree. This includes unrelated staged changes and untracked files.

Before the manifest changes, LPM CLI checks the tag name and refuses an existing tag. The default tag prefix is v. The resulting tag cannot start with -.

The default commit message is v%s. Every %s in --message becomes the new version. A message without %s stays literal.

Git hooks run normally. Git signing configuration also applies: commit.gpgSign controls commit signing, and tag.gpgSign requests a signed tag. Otherwise, the tag is lightweight.

The command does not run the preversion, version, or postversion package scripts. To run a script named version, use lpm run version.

Preview a change

lpm version major --dry-run --json

A preview reads the current manifest and takes the project lock. It can create internal lock files. It does not edit the manifest, run Git hooks, commit, or tag.

A preview does not check Git cleanliness, signing, or tag availability. A successful preview does not guarantee that the Git step will succeed.

Workspaces

Run the command from the package directory:

cd packages/widget
lpm version patch --no-git-tag-version

Only that package's package.json changes. Sibling versions, dependency ranges, and lockfiles stay unchanged. For coordinated workspace releases, use lpm release.

Workspace members share the workspace transaction lock. LPM CLI refuses a changed project directory, workspace boundary, or lock directory during the operation.

Automation

The command needs no confirmation prompt. Use --json to read the result from a script:

lpm version patch --no-git-tag-version --json

Normal success includes success, dry_run, git_tag_version, commit, tag, and plan. The plan lists old and new versions and affected files. Without Git mode, commit and tag are null.

A completed-operation retry returns a shorter result with success, recovered, git_tag_version, and tag.

Recover from a failure

If Git cannot create the expected commit or tag, LPM CLI restores its verified changes. This includes the manifest and its staged entry.

If a hook creates unexpected history or includes other files in the commit, LPM CLI preserves that history and the recovery record. Inspect git status and git log before retrying. Keep the recovery record until you resolve the reported mismatch.

After an interrupted process, run the same command again. An identical retry recognizes a completed operation and does not increment twice. An incomplete operation rolls back before a new plan starts.

A pending interrupted operation blocks previews. Run the original mutating command to recover it first.

Flags

Flag	Description
`--dry-run`	Show the version plan without changing the manifest, creating a commit, or adding a tag.
`--no-git-tag-version`	Update `package.json` without a Git commit or tag.
`--tag-prefix <TAG_PREFIX>`	Set the tag prefix. Default: `v`.
`-m, --message <MESSAGE>`	Set the commit message. `%s` becomes the new version. Default: `v%s`.
`--json`	Return a structured plan or recovery result.

See global flags for shared options.

lpm version