ReleaseKit/docs/cli.md

Command line

ReleaseKit currently provides five commands. The exit statuses below belong to the native executable. go run examples are convenient for source execution, but the Go driver maps a nonzero child exit status to 1. Use the built executable or ./scripts/release for publication when distinct statuses are needed.

Print the executable version:

go run ./cmd/releasekit version

This prints releasekit <version> followed by a newline and exits with status 0. The version comes from buildinfo.Version.

Check a local candidate:

go run ./cmd/releasekit check [--repo DIR] [--config FILE] VERSION

VERSION must use stable vMAJOR.MINOR.PATCH syntax. Options must precede the version. The repository defaults to the current directory, and the profile defaults to <repository>/releasekit.json. A successful command prints the captured local commit and version. It checks the committed release note, local Git state, runs the standard offline Go test suite, and then runs any configured additional checks in profile order. It does not inspect remote availability or publish a tag.

check writes errors and diagnostics to standard error. It returns status 0 after local validation, 1 after a candidate validation failure, and 2 for usage, profile, or invalid-version errors. Unsupported argument sequences print usage to standard error.

Publish a source tag:

go run ./cmd/releasekit publish [--repo DIR] [--config FILE] VERSION

publish reads the same product, remote, and additional-check settings as check. It checks the authoritative remote and validates the candidate: the standard offline Go test suite runs first, followed by configured checks in profile order. It then creates an annotated local tag and pushes only its exact tag object. It prints the confirmed version, candidate commit, and tag object on success. Validation progress and failed publication state, including the captured publication endpoint for recovery, are written to standard error. A signal cancels the active operation; if it arrives during a push, the library's bounded reconciliation determines whether the exact tag was accepted.

The command returns status 0 for confirmed publication, 1 for a known publication failure or conflict, 2 for usage, profile, or invalid-version errors, and 3 when the push outcome remains unknown. Unknown status must be resolved against the authoritative remote before retrying. The maintainer procedure selects the repository profile and gives the source-release workflow.

Build selected application targets:

go run ./cmd/releasekit build [--repo DIR] [--config FILE] [--output DIR] VERSION

build requires a build object in the profile. It compiles the selected targets with the requested version injected, checks the native version invocation, and writes binaries plus the private .releasekit-build.json receipt into dist by default. --output selects a different directory; relative paths are resolved from the repository. Selected artifact filenames are regenerated while unrelated files are preserved. A complete nonempty build writes a receipt only after compilation and smoke checking succeed. On partial failure, standard error lists completed outputs and prior receipts in that output directory are invalidated; no new receipt is written. An empty target list returns the source commit without building or writing a receipt.

The command returns status 0 on completion, 1 for build or output failure, and 2 for usage, profile, or invalid-version errors. It builds the current source tree and does not perform candidate validation or remote publication. check and publish run the same configured build after their one candidate validation, using temporary output outside the worktree.

Deliver a tagged source release to Gitea:

go run ./cmd/releasekit deliver [--repo DIR] [--config FILE] [--assets DIR] VERSION

deliver requires a delivery profile object and its configured token environment variable, which defaults to RELEASEKIT_GITEA_TOKEN. It verifies the local tag, clean tagged checkout, hosted tag, and committed release note, then creates or finds the release page and reports delivery state separately from source publication. Historical lightweight tags and detached checkouts are supported when HEAD is the selected tag commit; delivery does not require the former remote main to match.

When the profile has build targets and --assets is omitted, deliver builds the tagged source into temporary storage and uploads its binaries and complete SHA256SUMS. When --assets DIR is supplied, that directory must contain the private .releasekit-build.json receipt and matching unchanged artifacts. Profiles without targets use page-only delivery and need no receipt, binary build, or manifest. deliver never runs candidate checks or publishes a tag.

The command returns 0 for complete delivery, 1 for a known failure, conflict, or partial delivery, 2 for usage, profile, or missing-credential errors, and 3 when a remote write remains uncertain. The result lists matching, uploaded, pending, conflicting, and uncertain assets as available. Retry the same version with the same tagged source and destination; matching content is kept and only missing assets are added. See the delivery consumer guide and Gitea integration guide.