git:20260623.624370c to git:20260623.e806807

1 added, 1 removed. Audit A to A.

---

name: releases-cli

description: Use the `releases` CLI to search, browse, and read the Releases.sh changelog registry from the terminal — the keyless, agent-friendly peer of the Releases MCP. Activate when the user mentions "releases CLI", runs a `releases` command, asks how to install it, or wants to look up releases, sources, orgs, collections, or changelogs from a shell.

---

# releases CLI

The `releases` CLI is a first-class, **keyless** way to query the public changelog registry at [releases.sh](https://releases.sh) — the terminal peer of the Releases MCP. Anyone can search, tail, list, and inspect releases with no account and no API key; it talks to `api.releases.sh` by default with zero configuration. (A separate, invite-only `admin` surface exists for maintainers — see the short note at the end — but reads never need it.)

Reach for the CLI when the user is working in a shell or wants piped/scriptable output; reach for the MCP when you're answering conversationally with typed tools. They cover the same registry.

## Install

```bash

brew install buildinternet/tap/releases # recommended on macOS / Linux

npm install -g @buildinternet/releases # or via npm

npx @buildinternet/releases search "react" # one-off, no install

```

## Reader commands (no auth, no key)

Full reference: **[references/reader.md](references/reader.md)**. The shape is verb-first, and every command takes `--json`.

```bash

releases search "breaking change" # unified search: orgs, catalog, collections, releases

releases tail next-js # latest releases from one source (slug or src_…)

releases tail --org vercel --count 20 # latest across a whole org

releases list --category ai # browse sources (alias: `releases sources`)

releases list --query shadcn # name / slug / url substring

releases get vercel # inspect any entity by id or slug

releases lookup domain vercel.com # resolve a domain/URL to its registry entry

releases collection list # browse curated cross-org playlists

releases collection releases frontier-ai-labs # the feed for one collection

releases stats # registry overview

releases categories # valid --category values (fixed taxonomy)

```

Two commands built for agents specifically:

- `releases agent-context` — emits a versioned JSON document describing every command, argument, and option. When in doubt about exact flags, call this instead of guessing; it's the CLI's machine-readable source of truth.

- `releases skills install` — installs/refreshes the bundled skills (`-g` for user-wide). Symlinked by default, so re-running refreshes atomically.

### Conventions worth knowing (all in the reader reference)

- **IDs and slugs are interchangeable** wherever an identifier is expected (`org_…`, `prod_…`, `src_…`, `rel_…`); IDs are stable across renames. Source/product commands also take an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`), which skips a resolver round-trip.

- - **`--json` everywhere** for stable output. Release readers (`get`, `search`, `tail`) return a **slim** shape by default (core fields + markdown-stripped `excerpt` + `contentTokens` hint, plus `media[]` with R2 `r2Url` when present and a `contentTruncated` flag) to save tokens; pass `--full` for the complete payload. (`list` is the inverse: verbose by default — and carries a per-source `Releases` count column — `--compact` for less.)

+ - **`--json` everywhere** for stable output. Release readers (`get`, `search`, `tail`) return a **slim** shape by default (core fields + markdown-stripped `excerpt` + `contentTokens` hint, plus `media[]` with R2 `r2Url` when present and a `contentTruncated` flag) to save tokens; pass `--full` for the complete payload. (`list` is the inverse: verbose by default — and carries a per-source `Releases` count column — `--compact` for less.) Narrow further with **`--fields id,version,source.slug`** (comma-separated, dot-notation for nested keys) to project the JSON down to just the leaves you need — on `get`/`search`/`tail`, composes with `--full`.

- **`tail`/`latest` row cap:** `--count` (alias `--limit`, clamped `1–100`) sets how many releases to return. Only the `--product` feed is cursor-paginated (`--cursor <token>`); the org-wide/global feeds are count-capped, so `--cursor` without `--product` errors.

- **Piped output is bare TSV** (no headers/color/truncation), so `releases list | cut -f2` works without parsing ANSI — but note release rows repeat the title across several columns, so check the layout or just use `--json` before slicing by column number. `COLUMNS=<n>` overrides detected width.

- **Errors are structured under `--json`.** When a command run with `--json` fails, it prints a parseable `{ "error": { "kind", "message", "status?", "method?", "path?", "field?" } }` to stdout (not a stderr text dump) and exits non-zero — so you can branch on `kind` (`"api"` / `"invalid_input"` / `"error"`) instead of string-matching. Identifiers are also validated before any request: control characters, `..` traversal, `%`/`?`/`#`, and whitespace are rejected with an `invalid_input` error.

### Reading a tracked changelog

`releases get <source> --json` reports `hasChangelogFile` and the `changelogUrl` keyless, so you can tell whether a source maintains a checked-in CHANGELOG.md. To read the **sliced content** keyless, use the MCP's `get_catalog_entry` (with `changelog_tokens` / `nextOffset`) or fetch the `changelogUrl` directly — the CLI's `releases admin source changelog` wrapper is key-gated and won't run without auth.

### Submitting a source (keyless)

`releases submit <url>` suggests a changelog or release-notes URL for the registry — the same review queue the [web submit form](https://releases.sh/submit) feeds, no key required. Scheme is optional (`https://` assumed); `--note` adds context and `--contact` an optional reply email. With no argument in a TTY it prompts; it also reads a piped URL from stdin. Its sibling `releases feedback "<message>"` sends product feedback the same keyless way. Maintainers triage submissions under the key-gated `releases admin recommendations …` (see the admin reference).

## Common Mistakes

- `releases list` lists sources (alias `releases sources`). Do NOT write `releases sources list` — it reads `list` as a source slug and fails with "Source not found: list".

- Default read cap is 200 releases per source; use `--max <n>` or `--all` to override.

- There is **no** `summary` or `compare` command in this CLI, and **no** AI summarization tools on the hosted MCP (`summarize_changes` / `compare_products` do not exist). To summarize or compare, read each entity with `releases get` / `releases tail` (or `--json`) and synthesize the answer yourself.

- Don't reach for `admin` commands to do reads — every read above is keyless. `admin` is only for registry maintenance and requires a key (below).

## Signed-in user commands (`releases login`)

After `releases login` (device flow) or with a stored `relu_` key, you can manage your own account state — no admin key required:

```bash

releases follow vercel # follow an org or product

releases following # list follows

releases feed # personalized release timeline

releases webhook list # your outbound webhook subscriptions

releases webhook add --scope follows --url https://your.app/hook

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

releases webhook test <id> # enqueue a signed test delivery

releases webhook verify --key … # local HMAC check (no auth)

```

Org-scoped webhooks: up to 10 per account (`--org`, optional `--source`, `--product`, `--type feature|rollup`). Follows-scoped: one webhook that tracks your current follow graph (real-time sibling to `feed` + digest email); optional `--type` narrows delivery. `webhook edit` can update filters (`--clear-source`, `--clear-product`, `--clear-type`). Signing keys are shown once on `add` / `rotate-secret`. Operator/admin webhooks (`releases admin webhook …`) are a separate root-key surface.

## Admin surface (invite-only — reads never need it)

`releases admin <noun> <verb>` manages the registry (create/update sources, orgs, products; fetch; discovery; policies). It requires `RELEASES_API_KEY`, and **keys are not self-serve** — there's no public signup. Admin commands fail fast at startup without a key, so don't retry them unauthenticated, and don't fall back to them for read tasks. If a user asks how to get a key, tell them access is currently invite-only and point them at the project repo; don't invent a signup URL. Full operator reference: **[references/admin.md](references/admin.md)**.