CLI commands

Versionary exposes a single versionary binary. All commands operate on the current repository and read configuration from versionary.jsonc (preferred) or versionary.json.

versionary <command> [flags]

If no command is given, run is used.

Command	Purpose
run	Auto-dispatch: prepare/update a release PR, or publish a release.
verify	Validate config and repository shape.
ci	Decide whether CI should run checks, without changing the repository.
plan	Print the computed release plan as JSON.
changelog	Print or write the next release's changelog section.
pr	Prepare the release PR commit and branch.
release	Publish release metadata for a release commit.

run

The recommended CI entrypoint. In review-mode: "direct", it prepares a release commit on the triggering branch, pushes it, and publishes the release in one invocation. A failed branch push stops publishing.

In the default pr mode, it reads the last commit and dispatches:

• if the last commit is a release commit, it publishes the release;
• otherwise it computes a plan and, if there are releasable commits, prepares or updates the release PR/branch; if there are none, it closes any stale release PR and exits.

See Release workflows for what counts as a release commit.

With release-mode: "external", run emits release-ready on a merged release commit and release-waiting on later commits until its expected tags exist. releaseTargets includes the saved sha and notes for each untagged target. Both actions set releaseCreated: false and leave tagNames empty. See Julia packages for an integration example.

Flags

• --json — emit a machine-readable result instead of human text.
• --dry-run — report what would happen without pushing, opening PRs, or creating tags/releases.

JSON output

{
  "action": "pr-prepared",       // see table below
  "message": "Prepared release PR branch versionary/release",
  "releaseCreated": false,
  "tagNames": [],
  "reviewUrl": "https://github.com/owner/repo/pull/42", // when a PR is opened
  "branch": "versionary/release",
  "title": "chore(release): v1.3.0",
  "reviewRequests": [             // all PRs in separate-release-prs mode
    {
      "packagePaths": ["packages/api"],
      "branch": "versionary/release-api-0123456789ab",
      "title": "chore(release): api-v1.3.0",
      "reviewUrl": "https://github.com/owner/repo/pull/42",
      "status": "prepared",
      "targets": [
        { "path": "packages/api", "tag": "api-v1.3.0", "version": "1.3.0" }
      ]
    }
  ],
  "targets": [                    // present for dry-run / multi-target flows
    { "tag": "v1.3.0", "version": "1.3.0" }
  ]
}

releaseTargets is present for release-dry-run and release-published results:

[
  {
    "path": "crates/parser",
    "version": "0.4.0",
    "tag": "parser-v0.4.0",
    "dependencies": []
  },
  {
    "path": "crates/formatter",
    "version": "0.3.0",
    "tag": "formatter-v0.3.0",
    "dependencies": ["crates/parser"]
  }
]

Entries are ordered so every target appears after the targets in its dependencies array. Dependencies are configured package paths in the same release set. If those dependencies form a cycle, the cyclic targets fall back to package-path order and Versionary logs a warning; the release itself still proceeds. This is a handoff for external registry-publishing automation; Versionary does not publish registry artifacts.

reviewRequests is the authoritative array when separate-release-prs is enabled. reviewUrl, branch, and title remain as compatibility projections of the first entry.

action is one of:

Value	Meaning
noop	No releasable commits; nothing to do.
pr-prepared	Release PR branch prepared and pushed.
pr-up-to-date	Release PR branch already current.
pr-dry-run	Would prepare a release PR (dry run).
release-skipped	Release skipped (e.g. nothing to publish).
release-dry-run	Would publish a release (dry run).
release-published	Release published.

ci

Evaluates release-pr-checks and the GitHub event context without changing the repository or contacting the SCM provider. It needs configuration but no version files, release token, or Git history. Both the run and skip decisions exit 0; invalid configuration exits 1.

versionary ci --json

{
  "action": "ci-evaluated",
  "message": "Skipping checks for Versionary release PR versionary/release.",
  "runChecks": false,
  "isReleasePr": true
}

Without --json, the command prints the message. The GitHub Action exposes the same decision through command: ci, with run_checks and is_release_pr outputs.

The command reads GITHUB_EVENT_NAME, GITHUB_EVENT_PATH, and GITHUB_REPOSITORY. For pull_request and pull_request_target, it recognizes the configured release branch and generated separate package branches only when both PR repositories match the workflow repository. Other events, including post-merge pushes and merge queues, keep checks enabled. Missing, unreadable, or incomplete event data also keeps checks enabled. See the CI workflow recipe.

verify

Validates configuration and basic repository shape. Checks are grouped into Config, Paths, and Version files, each printed as OK/FAIL with details and remediation hints.

Exits 0 when all checks pass and 1 otherwise—use it as a CI gate.

versionary verify

plan

Computes the release plan and prints it as pretty JSON, without changing anything. The plan includes the next version, the release branch prefix, the changelog file and format, any per-package targets, and the grouped commits.

versionary plan

If there are no releasable commits, the plan's nextVersion is null.

When commit overrides are configured, the plan also includes commitOverrides. Each entry shows its hash, originalMessage, override, and the packages where it still applies. An empty packages array identifies an override consumed by earlier releases.

exclude and correct

Record release metadata for an existing commit without changing Git history:

versionary exclude a1b2c3d --reason "Fixes an unreleased regression"
versionary correct e4f5a6b --message "perf: cache commit lookups"

exclude removes the commit's contribution to version bumps and generated release notes. Its code remains in the release. correct uses the supplied Conventional Commit message for both the bump and notes. The supplied message replaces the complete original message, including any body and footers.

Both commands accept an optional --reason. correct requires --message. SHAs may be abbreviated to at least four hexadecimal characters, provided the prefix is unambiguous. Versionary resolves the full SHA and writes it under commit-overrides in the existing configuration file, preserving JSONC comments. Commit that change to share it with CI. The commands do not create Git commits.

The target must be in the current branch's history and in at least one configured package's unreleased commit window. Ambiguous or unknown SHAs, invalid replacement messages, and already-released targets fail without editing the configuration. In a monorepo, an override applies only to packages where the target is still unreleased, using the target's original changed files.

changelog

Renders the next release's changelog section.

• Without flags, prints the section to stdout.
• With --write, prepends the section to the configured changelog file and folds in any release highlights.

versionary changelog            # preview
versionary changelog --write    # update CHANGELOG.md (or NEWS.md)

pr

Prepares the release PR: it computes the plan, updates version files, changelog, and any extra files, commits a chore(release): v* commit on the release branch, pushes it, and opens or updates the review request through the SCM provider.

Flags

• --dry-run — report what would happen without pushing or opening a request.

versionary pr

If there are no releasable commits, it closes any stale release PR and exits.

With separate-release-prs, this command prepares, pushes, and reconciles all currently releasable package or cohort PRs.

release

Publishes release metadata (tags and the GitHub Release) for a release commit. This is the publish path that run dispatches to automatically; you rarely need to call it directly.

Flags

• --dry-run — report what would be published without creating tags or releases.

versionary release

Publishing is idempotent by tag and recovers from partial failures; see Idempotency, retries, and recovery.