> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Versioning

## Versions and compatibility

> **Warning**
>
> Do not build an integration on adacli. The output of a command can change at any time. To build an integration, use the [Ada API](/reference/introduction/overview). The Ada API is the only stable interface. It makes a breaking change only in a new [version](/reference/introduction/versioning).

### What the version number covers

adacli uses [semantic versioning](https://semver.org), in the form `MAJOR.MINOR.PATCH`. The version number covers these parts of adacli:

* Command names
* Option names
* Exit codes. To see the exit codes, run `adacli <instance> agent-context`. adacli maps errors from the Ada service to exit codes, so a change to the service can change the exit code that a command returns.

A release that removes or changes one of these parts increases the major version, for example from `1.4.2` to `2.0.0`. The release note lists every breaking change. A release that adds a command or an option increases the minor version. A release that only fixes defects increases the patch version.

### What can change at any time

The version number covers adacli's own binary. Most output comes from the Ada service, so it can change without a new adacli release:

* **`--json` output.** The service can add, rename, or remove a field at any time.
* **Table output.** The values come from the service. A column can be empty, or have different values, after a change to the service. Columns, column order, and formatting can also change in a release.
* **Messages.** Many error messages come from the service. The text of help, prompts, warnings, and errors can change. Use exit codes to check the result of a command.
* **Available commands.** A command appears or disappears when a feature is turned on or off for your Agent. For details, see [Available commands](/adacli/overview#available-commands).

### Supported releases

Only the latest release of adacli is supported. An older release gets no fixes.

* When you use an older release, error messages include a note that tells you to upgrade.
* A release with a known defect can be blocked. A blocked release cannot run commands until you upgrade.

To upgrade, see [Upgrade](/adacli/getting-started#upgrade).

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).