Releases

agents-cli follows Semantic Versioning 2.0.0 and Conventional Commits 1.0.0.

Versioning

A version is MAJOR.MINOR.PATCH:

Bump	When
`MAJOR`	Backwards-incompatible change to the CLI surface, on-disk layout, audit-log schema, or installer contract.
`MINOR`	New feature, fully backwards compatible.
`PATCH`	Bug fix, internal refactor, doc/CI change. No behaviour change for users.

The version is enforced by a CI guard against the commit history: a feat!: or BREAKING CHANGE footer requires a major bump; a feat: requires at least a minor bump.

Commits

All commits on main use Conventional Commits:

<type>(<scope>): <imperative summary>

<body explaining why>

<trailers>

Type	Use for
`feat`	New feature for users.
`fix`	Bug fix.
`docs`	Documentation only.
`refactor`	Code change without behaviour change.
`test`	Adding or updating tests.
`chore`	Maintenance, deps, config.
`perf`	Performance improvement.
`ci`	CI/CD config.

Breaking changes use ! after the type (feat!:) and an explicit BREAKING CHANGE: footer with the migration steps.

Changelog

Every release adds a section to CHANGELOG.md following Keep a Changelog 1.1.0. The next release's section lives under ## [Unreleased] until the bump.

Where to find releases

Surface	URL
Release notes (canonical)	GitLab Releases
Installer + binaries	`https://acli.chagbrasil.com/install/...`
This site (current)	`https://acli.chagbrasil.com/docs/`
Changelog	`CHANGELOG.md`

Pinning a specific version

The installer accepts a --version flag:

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh -s -- --version v3.2.0

Or set the AGENTS_CLI_VERSION environment variable. See reference.

Pre-release versions

Pre-releases use SemVer pre-release suffixes (v3.3.0-rc.1). Tags with suffixes do not trigger the release pipeline — to publish a pre-release, push a final tag (v3.3.0-rc.1 → v3.3.0).