Getting started

Requirements

Verso is distributed as an npm package with native binaries for supported platforms. The repository that you release needs Git, a package manifest, and an upstream branch. Node.js 22.18 or newer is required by the npm package.

Install

Add Verso to the root of the workspace:

pnpm add -D @amamo/verso

Then expose it through the root manifest:

{
  "scripts": {
    "release": "verso"
  }
}

Initialize the config

Run the initializer from the repository root:

pnpm release -- init

The initializer writes verso.toml and detects packages/* when that workspace shape exists. Use --single or --workspace to choose explicitly, and --force only when you intend to replace an existing config.

Validate before releasing

doctor checks config parsing, package discovery, version consistency, changelog and Cargo paths, plus Git upstream readiness:

pnpm release -- doctor

For CI or other automation, use structured output:

pnpm release -- doctor --json

Preview the first release

Always inspect the plan before the first real run:

pnpm release -- --dry-run

The preview shows discovered packages, the resolved current and target versions, files that would change, changelog content, hooks, and Git actions. It does not write files or run mutating Git commands.

When the plan is correct, choose a version interactively:

pnpm release

Or pass an exact semantic version for automation:

pnpm release -- --version 1.4.0 --yes

--yes skips confirmation; it does not choose a version. Without --version, version selection is still interactive.

Next steps

• Adjust package discovery and release hooks in Configuration.
• Review every command and option in the CLI reference.
• Learn what is rolled back in Release workflow.