Getting started
This tutorial cuts a real release of a small repo using only tarsi-serve — install, wire check, plan, dry-run, release, verify. The repo should use conventional commits.
1. Install tarsi-serve
There is no tarsi CLI — the surface is tarsi-serve, an ndjson ops binary with a one-shot front door. It ships as a tamias pack (libraries/tarsi, type: files declaring tarsi-serve as a tools/bin/<triple>/ payload bin):
# From a tarsi checkout:
cargo xtask pack # release-build → libraries/tarsi/tools/bin/<triple>/
tamias install ./libraries/tarsi # deploys `tarsi-serve` onto PATHDev shortcut without tamias: cargo xtask install puts a release tarsi-serve in ~/.local/bin.
2. Check the wire
tarsi-serve manifest
# → {"name":"tarsi-serve","version":"…","ops":["manifest","profiles","plan","changelog","notes","release"]}Two modes: no args = ndjson JSON-lines loop on stdio ({"op": …, "params": …} in, {"ok": …, "result"|"error"} out); tarsi-serve <op> [--dir D] [--set k=v]… [--yes|--dry-run] = one-shot argv — --yes maps to dry_run: false, --dry-run forces the default. See Drive tarsi-serve ops for the full surface.
3. Prepare the repo
The repo needs a tarsi.toml. The minimal useful one:
# tarsi.toml
[publish.crates]
enabled = false
[publish.ghreleases]
enabled = falseTag-only releases are the org convention (ADR-0004); without the enabled = false lines both publish targets default to on. Units default to cargo workspace members — for a non-cargo repo, declare them explicitly (see Write a tarsi.toml).
Make sure the history you want released is conventional:
git log --oneline
# feat(api): add retries → minor bump
# fix(core): handle empty body → patch bump
# chore: tidy imports → no release on its own4. Plan
tarsi-serve plan --dir .Read the result. Each unit in plan.units carries:
spec— resolved unit (name, path, tag format, publish targets)bump—major/minor/patch/nonenew_version— the version the bump would writetag— e.g.my-unit-v1.2.0releases— whether this unit actually releaseschangelog_markdown— the rendered changelog sectioncommits— how many commits were attributed
plan.unattributed lists commits that matched no unit's paths — repo-root files land there. plan.steps is the mutation sequence release would run.
Nothing has been written. This is the review gate — always plan before release.
5. Preview the notes
tarsi-serve changelog --dir . # per-unit {unit, version, tag, markdown}
tarsi-serve notes --dir . # concatenated release notes6. Dry-run the release
tarsi-serve release --dir .release is dry-run by default — this executes the full plan and runs every publish target in dry-run mode, reporting what would happen, and writes nothing. Equivalently over ndjson:
{"op":"release","params":{"dir":".","dry_run":true}}7. Release for real
Only after the plan looks right and a human approves:
tarsi-serve release --dir . --yes--yes is dry_run:false. The mutation phase, in order:
- Write
CHANGELOG.mdsections per releasing unit (created files are tracked for rollback). - Bump versions in manifests via
toml_edit(comments preserved). - Stage only the touched files —
CHANGELOG.md/Cargo.tomlper unit plus root manifests — nevergit add -A. - Commit
chore(release): bump versions. - Tag each releasing unit (
{unit}-v{version}). - Push branch + tags before publishing — GitHub Releases auto-creates tags at remote HEAD otherwise.
- Run publish targets (crates.io, GitHub Releases) against the pushed commit.
The result reports steps_run, per-target publish reports, and — on failure — rolled_back or a manual-cleanup note for partial publishes.
8. Verify
git tag -l '*-v*' | tail
git log --oneline -3
tarsi-serve plan --dir . # now: nothing to releaseThe latest-tag-per-unit range means a second plan finds no new commits since the tags you just pushed.
What you now know
tarsi-serveis the whole surface: one-shot argv ops plus an ndjson loop, dry-run by default.planis the review gate — per-unit bump, version, tag, changelog, and the exact mutation sequencereleasewould run.release --yesmutates in order: changelogs → manifest bumps → staged commit → tags → push → publish — with rollback reporting.- Re-running
planafter a release finds nothing new: latest-tag- per-unit ranges are the idempotency boundary.
Next steps
- Layer org conventions with a profile — Author a release profile pack
- Tune attribution and overrides — Write a tarsi.toml
- Script it from an agent — Drive tarsi-serve ops