CLI reference

`verso [OPTIONS] [COMMAND]`

Running without a subcommand plans or executes a full release. Global options may appear before or after a subcommand.

Option	Default	Meaning
`--dry-run`	`false`	Render an exact plan without writes, hooks, or mutating Git commands
`--json`	`false`	Render a dry-run, doctor report, or transaction status as JSON
`--version <SEMVER>`	interactive	Use an exact valid SemVer target for a release or `bump`
`--config <PATH>`	`verso.toml`	Use another group config; its parent becomes the release root
`--group <NAME>`	-	Select `verso.NAME.toml`; conflicts with `--config`
`--yes`	`false`	Accept release or bump confirmations; does not select a version
`-V`, `--tool-version`	-	Print the installed Verso version and exit
`--help`	-	Print command help

Shell

verso --dry-run --version 2.0.0-rc.0verso --group core --version 2.0.0 --yesverso doctor --group core --jsonverso --tool-version

--json requires --dry-run for a release or bump. doctor --json and status --json do not need --dry-run.

Interactive release version selection

Without --version, a full release offers patch, minor, major, alpha, beta, rc, and custom SemVer choices. When the current version is a prerelease, the corresponding stable version is offered too.

Alpha, beta, and rc selections ask for a patch, minor, major, or custom base. Repeating the same channel on the same base increments its numeric suffix; changing the channel or base starts at .0. For example, selecting beta + minor from 1.3.0-beta.0 yields 1.3.0-beta.1.

An exact target may be equal to or lower than the current version. That requires a separate default-no confirmation unless --yes is set. When stdin or stdout is not a terminal, the same choices use plain-text prompts.

Exact dry-run plans

Dry-run performs the real planning transformation in memory. Text output includes the operation, release group, changed-file tree, and the actual full-file before/after diff for every planned change. It executes no hooks, writes no files, and runs no mutating Git command.

JSON adds a fileChanges array whose entries contain path, kind, before, after, and diff. The complete object contains operation, group, currentVersion, targetVersion, packageFiles, extraVersionFiles, versionFiles, changelogFile, fileChanges, commitMessage, tagName, hooks, warnings, and gitCommands. Paths are relative to the release root. Release Git commands use tag-object, commit-OID, and upstream placeholders rather than contacting a remote; bump plans have no changelog or Git commands.

`verso bump`

Shell

verso bump patchverso bump minor --dry-runverso bump major --group coreverso bump --version 2.0.0

Exactly one bump level (patch, minor, or major) or --version <SEMVER> is required. The command updates discovered package manifests, configured Cargo manifests, and matching entries in the nearest Cargo lockfiles. It does not update the changelog, create a commit or tag, or push. Only before_version and after_version hooks apply.

Release groups

One config is one release group, and every member of that group must start at the same version. --group core is shorthand for --config verso.core.toml; the two options are mutually exclusive. Use separate configs for groups that version independently, and run one group per command.

Group names must start with an ASCII letter or digit and may otherwise contain ASCII letters, digits, -, and _.

`verso init`

Shell

verso [--config <PATH>] init [--single | --workspace] [--force]

Option	Meaning
`--single`	Write a single-package starter
`--workspace`	Write a `packages/*` workspace starter
`--force`	Replace an existing config file

Without a mode, only packages/*/package.json is used for detection. Parent directories for a custom config path are created as needed.

`verso doctor`

Shell

verso [--config <PATH> | --group <NAME>] doctor [--json]

The report checks release root resolution, config, discovered packages, current and consistent versions, configured Cargo versions, changelog writability, and Git upstream readiness. Text output uses PASS / FAIL; JSON returns:

JSON

{  "ok": true,  "checks": [{ "name": "config", "status": "pass", "message": "..." }],  "packageCount": 3,  "currentVersion": "1.4.0"}

A failed doctor report exits with status 1 even when JSON was written successfully.

Transaction recovery

Shell

verso [--config <PATH> | --group <NAME>] status [--json]verso [--config <PATH> | --group <NAME>] resume [--retry-hook | --skip-hook]verso [--config <PATH> | --group <NAME>] abort [--force]

status shows the active operation, group, stage, version pair, interrupted hook, and changed-file count. With --json, it also reports canAbort, canForceAbort, pushStarted, and pushFailed; when no transaction exists, it returns { "active": false }.

resume verifies the persisted plan, skips completed work, and continues from the recorded stage. If a hook was interrupted, inspect its side effects and choose exactly one of --retry-hook or --skip-hook.

abort rolls back only state still owned by the transaction and refuses to overwrite later edits. After manual recovery, abort --force discards only the journal and leaves files and refs unchanged.

See Release workflow for the exact stage model, reconciliation rules, and failure matrix.

Verso exits with 0 on success and 1 for validation, cancellation, hook, Git, transaction, or launch errors.