ReleaseKit/docs/cli.md

Command line

ReleaseKit currently provides six 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 argument defaults to the current directory. ReleaseKit resolves its containing Git checkout root before selecting the module or profile; the profile defaults to <repository-root>/releasekit.json. A successful command prints the captured module, version, full tag, and commit. It checks the committed release note and local Git state, runs the standard offline Go test suite (with -race when validation.go.race is true), and runs a separate go vet -mod=readonly ./... pass after successful tests when validation.go.full_vet is true. It then runs selected package compilation and committed Go formatting, followed by configured additional checks in profile order. It does not inspect remote availability or publish a tag.

The profile's optional module_dir selects a repository-relative physical module directory; omission selects the root module. Validation and configured product checks use that module selection. Additional check commands run with the selected module as their working directory and receive RELEASEKIT_VERSION, RELEASEKIT_CANDIDATE, RELEASEKIT_REPOSITORY_DIR, RELEASEKIT_MODULE_DIR, RELEASEKIT_MODULE_PATH, and RELEASEKIT_TAG in their environment. These values are added to each child environment without changing the ReleaseKit process environment.

When validation.go.compile_targets is selected, check compiles all packages for each configured GOOS/GOARCH pair after tests and full vet, using static mode with cgo disabled. This check produces no artifacts and does not execute target binaries. Compilation failures use the package-compile identity and show the selected target. When validation.go_format is true, check examines regular committed Go files with the Go formatter after tests, vet, and package compilation. It uses the selected module and shared-file inputs, including vendored source, and ignores the worktree and symlink blobs, and reports unformatted paths as go-format without modifying files. When validation.module_distribution.workspace_files is true, check reports committed go.work and go.work.sum blobs in those inputs, including symlink entries, as workspace-files. Automatic file inputs stop at independent nested modules. This inspection is independent of GOWORK and ignores uncommitted files. Any artifact build selected by the separate build setting runs after shared validation and configured checks. When validation.markdown is a non-null object, check checks committed local Markdown destinations and supported heading fragments after file-size inspection. An empty object enables the check; omission or null disables it. Outside-checkout links are written as out-of-scope observations to standard error by default. Setting validation.markdown.enforce_checkout_boundary to true makes those links fail; submodule-content observations remain nonfailures. Failures use the markdown-links identity with the source location and target.

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. Shared validation failures identify the failed check and retain useful findings and cause context in one diagnostic; separate full-vet failures use the go-vet identity. Unsupported argument sequences print usage to standard error.

Publish a source tag:

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

publish reads the same product, remote, validation, and additional-check settings as check. It checks the authoritative remote and validates the candidate: the single standard offline Go test suite runs first, with -race when validation.go.race is true. When validation.go.full_vet is true, test-time vet is disabled and go vet -mod=readonly ./... runs after successful tests. Selected package compilation and committed Go formatting follow. The selected file checks then run in order: workspace files, local replacements, file size, and Markdown. Configured checks run afterward in profile order. It then creates an annotated local tag and pushes only its exact full tag object. It prints the confirmed semantic version, full tag, 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. Shared validation failures use the same check and finding presentation as check, alongside publication state and phase.

When validation.go.compile_targets is selected, package compilation runs after tests and full vet and before configured checks. Each failure is reported as package-compile with its selected target; this does not create build artifacts or execute target binaries. When validation.go_format is true, committed Go formatting runs after package compilation and before configured checks. The selected workspace-file check then reports committed go.work and go.work.sum paths as workspace-files. Formatting failures are reported as go-format with affected paths and preserve parser or source-inspection causes.

When validation.module_distribution.local_replacements is true, the command parses committed go.mod declarations in the selected module after workspace-file inspection. Vendored contents remain in scope, while automatic inputs stop at independently released nested modules. Explicit shared files join the file-check inputs without expanding Go scope. Filesystem replacements use the local-replacements identity and include the declaration path, source line, and target; versioned replacements are permitted. Committed module symlinks are resolved within the candidate, regardless of GOWORK. When validation.file_size is a non-null object, the command checks each committed blob after module-distribution checks. An omitted or null object disables the check; an empty object enables the 1,000,000 decimal-byte default. Oversized files use the file-size identity and report their path and measured size against the limit. See the configuration reference for literal exclusions and the current-candidate scope. When validation.markdown is a non-null object, publish checks committed Markdown destinations after file-size inspection and before configured checks. It reports outside-checkout links to standard error unless boundary enforcement is selected; submodule contents remain out of scope. Markdown failures stop publication before product checks or tag creation.

--expected-module DIR optionally checks a launcher's selected physical module against the profile's module_dir before candidate work. Both paths are normalized relative to the repository; the profile remains the source of module selection. The root selection is ..

The optional profile field expected_push_url applies only to publish. A nonempty value must exactly match the effective push URL resolved by Git; mismatches fail during preflight before Go validation or tag creation. Git URL rewrites are resolved first, and the push URL is used when fetch and push URLs differ. check ignores this field.

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 selected module directory. 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 passes the configured build directly to the public delivery facade. The facade builds the tagged source into temporary storage, removes it when the operation ends, 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; this keeps the caller's original bytes available for retries. Relative --assets paths use the selected module directory, matching build --output; absolute paths retain their supplied base. Profiles without targets use page-only delivery and need no receipt, binary build, or manifest. deliver never runs candidate checks or publishes a tag.

Use one deliver invocation for the normal workflow. To build without delivery credentials, or to retain build output across retries, run build --output DIR first and then run deliver --assets DIR with the token available. The ordinary deliver command does not download application dependencies or change the checkout.

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 disjoint current observations; early failures may leave some declared assets unreported. On failure, the CLI prints state-based recovery guidance. Fix local or preflight failures before retrying; fix the reported cause before retrying partial delivery; resolve an unknown remote state before retrying; and investigate conflicts, using a new version if the source or published contents need correction. If rebuilding could change asset bytes already on the server, retain the original build artifacts and retry with --assets DIR. Matching content is kept and only known missing assets are added. See the delivery consumer guide and Gitea integration guide.

Prepare a tagged CI checkout and deliver it:

releasekit ci-deliver [--repo DIR] [--config FILE] [--remote NAME] [--prepared] [--expected-module DIR] --commit OID TAG

TAG is the complete Git tag name, including any module path prefix. Its last path component must be a stable semantic version; other commands continue to take a semantic VERSION. By default, ci-deliver fetches the exact TAG from the selected Git remote (default origin), requires its peeled commit to match the required full --commit object ID, checks out that commit detached, then verifies the tag, HEAD, and clean worktree. With --prepared, it performs those checks read-only against the existing checkout and does not fetch or check out. In either mode, it loads the profile from the verified source. --expected-module optionally checks that the profile selects the module chosen by a launcher; module selection itself remains profile-owned. The command validates delivery settings and the configured token, then downloads application dependencies only when the profile selects build targets. Binary profiles are built and delivered through the same facade path as deliver; source-only profiles skip dependency downloads and binary builds. --config follows the existing profile path rules: relative paths are resolved from --repo, and absolute paths are used as-is. The default mode prepares and changes the selected checkout; --prepared reuses a verified checkout. Ordinary deliver continues to operate on already prepared source without fetching, checking out, or downloading dependencies.

In Woodpecker, pass CI_WORKSPACE, CI_COMMIT_SHA, and CI_COMMIT_TAG as the repository, expected commit, and full tag arguments. The CLI does not read provider-specific environment variable names. Checkout and dependency preparation failures return status 1; usage, profile, credential, and invalid version errors return status 2. Final delivery uses the same statuses as deliver: 0 for complete, 1 for known failure, conflict, or partial delivery, and 3 for uncertain remote state.

The maintained module-based tag workflow verifies and checks out the event tag before resolving the consumer module. It builds the ReleaseKit version already selected by that tagged go.mod, using temporary alternate module files outside the source checkout. This tool bootstrap is separate from ci-deliver's application dependency preparation for binary profiles. ReleaseKit's own source workflow self-bootstraps ./cmd/releasekit; consumers without a declared ReleaseKit module dependency can use the separately installed-tool command. See the delivery guide for compatible Go environments, retries, and preparation details.