SDK, CLI & GitHub Action

Use the @havoptic/sdk TypeScript client, the havoptic CLI, or a GitHub Action that fails CI when an AI coding tool upgrade contains breaking changes.

TypeScript SDK

@havoptic/sdk has types generated from the OpenAPI document and no runtime dependencies. It runs on Node 18+, browsers, Cloudflare Workers, Deno and Bun.

npm install @havoptic/sdk

import { Havoptic, HavopticError } from '@havoptic/sdk';

const havoptic = new Havoptic({
  apiKey: process.env.HAVOPTIC_API_KEY, // optional
  retry: true,     // retry 429s, honoring Retry-After
  etagCache: true, // If-None-Match + replay cached body on 304
});

const latest = await havoptic.tools.latest('openai-codex');

try {
  await havoptic.tools.upgrade('claude-code', { from: 'not-a-version' });
} catch (err) {
  if (err instanceof HavopticError) console.error(err.status, err.type, err.param);
}

Method	Endpoint
`releases.list` / `releases.iterate`	`GET /v1/releases`
`releases.get(id, { expand })`	`GET /v1/releases/{id}`
`changes.list` / `changes.iterate`	`GET /v1/changes`
`tools.list` / `tools.get` / `tools.latest`	`GET /v1/tools…`
`tools.upgrade(id, { from, to })`	`GET /v1/tools/{id}/upgrade`
`digest({ since, tools })`	`GET /v1/digest`
`search({ q })`	`GET /v1/search`
`status()` / `changelog()`	`GET /v1/status`, `GET /v1/changelog`

Errors throw HavopticError with the problem fields (type, title, status, detail, param) and rateLimit. format: "markdown" on upgrade, digest and changelog returns the markdown brief.

CLI

npx havoptic                       # latest releases, last 7 days
npx havoptic cursor                # latest release of one tool
npx havoptic changes --tool claude-code --kind breaking,security --since 7d
npx havoptic upgrade claude-code --from 2.1.150 --markdown
npx -y havoptic mcp                # stdio MCP bridge

Exit code	Meaning
`0`	Success. For `upgrade`: no breaking changes in the range.
`1`	Usage error, or the API or network failed.
`2`	`upgrade` only: the range contains at least one breaking change. The report is still printed.

Options: --json, --markdown, --base-url (env HAVOPTIC_BASE_URL), --api-key (env HAVOPTIC_API_KEY).

GitHub Action: check AI tool upgrades

The example composite action in examples/github-action runs havoptic upgrade, writes the report to the job summary, and fails the job when the range contains a breaking change. An API outage is reported as a warning so it does not block your build.

# .github/workflows/ai-tool-upgrades.yml
name: AI tool upgrade check
on:
  pull_request:
  schedule:
    - cron: '0 9 * * 1' # Mondays

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: scotthavird/havoptic.com/examples/github-action@main
        with:
          tool: claude-code
          from: 2.1.290        # the version you pin today
          # to: 2.1.302        # optional, defaults to latest
          # fail-on-breaking: 'false'  # warn instead of failing

Input	Default	Meaning
`tool`	required	Tool id, e.g. `claude-code`, `cursor`, `openai-codex`.
`from`	required	Your current version (exclusive).
`to`	latest	Target version (inclusive).
`fail-on-breaking`	`true`	Fail the job on breaking changes; `false` only warns.
`fail-on-error`	`false`	Fail the job when the API cannot be reached.
`api-key`	none	Optional Havoptic API key (pass it from a secret).
`base-url`	`https://www.havoptic.com`	API origin.
`cli-version`	`latest`	Version of the `havoptic` npm package to run.

Outputs: breaking (true/false), exit-code, and report (path to the markdown file).

Developer docs · API reference · OpenAPI · Havoptic