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:

```sh
go run ./cmd/releasekit version
```

This prints `releasekit <version>` followed by a newline and exits with status 0.
The version comes from [`buildinfo.Version`](consumers/runtime-version.md).

Check a local candidate:

```sh
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:

```sh
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](release.md) selects the repository profile and gives
the source-release workflow.

Build selected application targets:

```sh
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:

```sh
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 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](consumers/delivery.md) and
[Gitea integration guide](integrations/gitea.md).