@buildinternet/releases

Releases CLI

releases.sh  ·  Backend monorepo →  ·  Install  ·  Usage  ·  Authentication

The changelog & release-notes registry for developers and AI agents — a lean HTTP client for releases.sh. Search and browse release notes from GitHub, RSS/Atom/JSON feeds, and product changelog pages, with no local infrastructure.

This repo is the CLI only. The backend that powers api.releases.sh — the API worker, MCP server, web frontend, and ingest pipeline — is open source in its own repo: buildinternet/releases.

The CLI talks to the hosted registry at api.releases.sh. Search and browse work out of the box — no account or config. Sign in with releases login to follow orgs and products, get a personalized feed, and manage outbound webhooks; it mints a personal read-only API key (and earns you higher rate limits as those roll out). Write/admin access (releases admin …) is a separate, closed beta — open an issue for early access.

Install

brew install buildinternet/tap/releases          # Homebrew (macOS / Linux)
npm install -g @buildinternet/releases           # npm (macOS / Linux / Windows)
curl -fsSL https://releases.sh/install | bash    # shell installer (macOS / Linux)

Or run without installing: npx @buildinternet/releases@latest search react — always pin @latest, since bare npx @buildinternet/releases caches the first-fetched version forever. Signed, precompiled binaries for every platform are on the Releases page (with checksums) for air-gapped installs or version pinning.

Homebrew installs shell completions automatically. On every other path, enable them once with releases completion install (auto-detects $SHELL).

Usage

releases search "authentication"
releases search "slack integration" --since 90d   # bound release hits by publish date
releases tail next-js                              # latest releases; `tail -f` to follow
releases list --category ai
releases get vercel                                # org, product, or source
releases org overview vercel                       # full AI-generated org overview
releases stats
releases changelog                                 # recent product updates from releases.sh
releases submit https://acme.dev/changelog         # suggest a source for the registry
releases feedback "great tool — here's an idea…"   # message the maintainers

Identifiers are interchangeable: every command accepts a slug, a typed ID (org_…, prod_…, src_…, rel_…), or an org/slug coordinate (e.g. vercel/next-js). IDs are stable across renames. search, tail/latest, and feed take --since / --until to bound releases by date — an ISO date (2026-01-01) or relative shorthand (90d, 4w, 6m, 2y).

Add --json to any reader command for machine-readable output — list commands emit a { items, pagination } envelope. Release readers return a slim shape by default (id, version, title, summary, excerpt, url, dates, plus any media with its r2Url); pass --full for the complete payload. tail/latest take --count (alias --limit, 1–100). Run releases <command> --help for per-command flags.

Following & personalized feed

Follow orgs and products to build a personalized feed. These act on your own account, so sign in first (releases login):

releases follow vercel              # org slug, org/product coordinate, or typed ID
releases following                  # list what you follow
releases feed                       # your release timeline (--json, --page, --limit)
releases unfollow vercel

Following an organization includes all of its products.

Outbound webhooks

Receive signed release.created POSTs in real time — for everything you follow or a single org:

releases webhook add --scope follows --url https://your.app/hook
releases webhook add --org vercel --url https://your.app/hook --description "prod"
releases webhook list
releases webhook test <id>
releases webhook verify --key … --signature … --timestamp … --body-file capture.json

Org-scoped: up to 10 (--org, optional --source, --product, --type feature|rollup). Follows-scoped: one webhook (--scope follows) that tracks your current follow graph; optional --type narrows delivery. Signing keys are shown once on add / rotate-secret. You can also manage webhooks in the browser at releases.sh/account/notifications. Operator/admin webhooks (releases admin webhook …) are a separate root-key surface.

Add --workspace <id-or-slug> to list, add, show, edit, remove, test, or rotate-secret to manage a shared workspace webhook instead of your own — see one you belong to, and its role and id, with releases workspace list:

releases workspace list
releases webhook add --workspace acme --org vercel --url https://your.app/hook
releases webhook list --workspace acme

Workspace webhooks are org-scoped only (--scope follows isn't supported with --workspace). Only workspace owners and admins can create, edit, rotate, or delete them; any member can list, view, and test.

Contribute to the registry

None of these need an account or API key:

releases submit https://acme.dev/changelog       # suggest a changelog / release-notes URL
releases feedback "tail -f reconnects slowly"     # report a bug or share an idea
releases json validate releases.json              # check a releases.json manifest before publishing

submit and feedback both prompt interactively when run with no argument, accept input on stdin, and take --dry-run --json to preview the payload without sending. feedback --type is bug / idea / other; submit --note carries extra context (product name, repo, feed quirks). Submissions feed the same review queue as the web submit form.

json validate is a read-only manifest check: it validates a releases.json v2 file against the published schema (pass a path or - for stdin) and adds --json for machine-readable output — no network, no submission.

MCP & Claude Code

Point any MCP-compatible agent at the hosted server:

npx mcp-remote https://agents.releases.sh/mcp

This repo is also a Claude Code marketplace with the releases plugin — hosted MCP tools, a /releases lookup command, and auto-trigger skills:

/plugin marketplace add buildinternet/releases-cli
/plugin install releases@releases

Operator/maintainer skills (source onboarding, parsing, playbooks) live with the backend in the releases monorepo — its .claude/skills/ tree is picked up automatically in a checkout.

Or install just the skills into any agent (Cursor, Codex, Gemini CLI, Windsurf, …):

releases skills install        # or, without the CLI: npx skills add buildinternet/releases-cli

Authentication

Search and browse need no auth. Signing in powers the personal surfaces — follows, feed, and outbound webhooks — and mints a personal read-only key (it can't write to the catalog or run admin commands; it identifies you for /v1/me/* account routes). The easiest way in is your browser — nothing to copy or paste:

releases login              # opens your browser to approve, then saves the key
releases login --no-browser # print the URL + code to open yourself (headless / SSH)

This uses the OAuth 2.0 Device Authorization Grant (RFC 8628): approve a short code at releases.sh/device in a signed-in browser, and a read-only key is saved to ~/.releases/credentials (0600) — the browser session itself is never saved, only that key. Manage keys with releases keys list / create / revoke; each of those opens its own fresh browser approval and signs out again once the command finishes, rather than reusing a stored session (add --no-browser to print the URL + code instead, same as login).

If you've verified ownership of a source's domain, mint a publish-token scoped to that one source. The publish-changelog GitHub Action and releases publish both read it as RELEASES_API_TOKEN. Like releases keys, this opens its own browser approval each time:

releases publish-token create --source src_… | gh secret set RELEASES_API_TOKEN
releases publish-token list
releases publish-token revoke <id>

Already issued a token (e.g. a write/admin key during the closed beta)? Store it without the browser flow via releases auth login (interactive, --token <token>, or --token - for stdin); it's verified before being saved. releases auth status shows the current state (whoami is an alias). RELEASES_API_KEY in the environment overrides any stored credential — handy for CI.

Publish from any CI

releases publish pushes changelog updates with POST /v1/sources/…/releases/batch (mode: upsert-content) — the same request as the publish-changelog GitHub Action, for GitLab CI, Buildkite, or a local docs build.

releases publish --source src_… --dry-run
releases publish --source acme/docs --changelog CHANGELOG.md --since "$CI_COMMIT_BEFORE_SHA" \
  --url-template "https://gitlab.com/acme/app/-/blob/main/CHANGELOG.md#{key}"
releases publish --source src_… --glob "changelog/**/*.mdx"

--dry-run prints the batch body and does not call the API (no token required). A real publish reads RELEASES_API_TOKEN and exits if it is missing. --since <sha> limits the plan to entries changed since that commit; omit it, or pass an all-zero first-push SHA, to publish every parsed entry. Repeating a publish is safe: unchanged bodies are not written again.

Single-file mode parses versioned ## headings (Keep a Changelog, conventional-changelog) and ## Month D, YYYY sections. --glob switches to one MDX or Markdown file per release, with metadata in YAML frontmatter (draft: true is skipped). Deleted files are reported and left in the index.

The commit you pass to --since has to be in the local clone (fetch-depth: 0 on GitHub, or GitLab's default full clone). --url-template accepts {key}, {version}, {date}, {path}, and {slug}. When GITHUB_REPOSITORY is set and the template is omitted, the URL falls back to the file's GitHub blob URL, same as the Action.

# .gitlab-ci.yml
publish-changelog:
  image: node:22
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [CHANGELOG.md]
  script:
    - npm install -g @buildinternet/releases
    - |
      releases publish \
        --source "$RELEASES_SOURCE" \
        --since "$CI_COMMIT_BEFORE_SHA" \
        --url-template "https://gitlab.com/${CI_PROJECT_PATH}/-/blob/${CI_COMMIT_REF_NAME}/CHANGELOG.md#{key}"

Environment

Reader access requires nothing. Useful overrides:

• RELEASES_API_KEY — Bearer token for write endpoints; overrides stored credentials.
• RELEASES_API_TOKEN — write-scoped publish token for releases publish (see Publish from any CI).
• RELEASES_API_URL — override the default https://api.releases.sh (e.g. staging).
• RELEASES_TELEMETRY_DISABLED=1 — opt out of anonymous usage pings (DO_NOT_TRACK=1 also honored).

See .env.example for the full list.

Custom CA certificates (TLS-intercepting proxies)

The compiled binary ships with the standard Mozilla CA store. If your network re-terminates TLS with its own CA (corporate proxy, sandboxed agent environment), point the standard Node/OpenSSL variables at the proxy's CA certificate — the binary honors both:

NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.pem releases search "bun"
# or
SSL_CERT_FILE=/path/to/proxy-ca.pem releases search "bun"

No --ca-bundle flag is needed; certificate errors from the CLI include this hint.

Exit codes

Code	Meaning
0	Success
1	Application error (network, API, unexpected state)
2	Usage / provider error (bad arguments or upstream rejection)
130	Cancellation (SIGINT)

Contributing

Build, test, and release instructions live in CONTRIBUTING.md.

License

MIT