{"id":48910013,"url":"https://github.com/buildinternet/releases-cli","last_synced_at":"2026-06-09T02:03:38.512Z","repository":{"id":351880965,"uuid":"1212896347","full_name":"buildinternet/releases-cli","owner":"buildinternet","description":"Agent-friendly CLI for searching public product releases","archived":false,"fork":false,"pushed_at":"2026-05-22T00:52:39.000Z","size":923,"stargazers_count":1,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T10:16:55.286Z","etag":null,"topics":["agent-skills","changelogs","cli","release-notes"],"latest_commit_sha":null,"homepage":"https://releases.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buildinternet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-16T20:55:03.000Z","updated_at":"2026-05-22T00:51:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"5df122e4-d457-49eb-822d-08070f9a732b","html_url":"https://github.com/buildinternet/releases-cli","commit_stats":null,"previous_names":["buildinternet/releases-cli"],"tags_count":123,"template":false,"template_full_name":null,"purl":"pkg:github/buildinternet/releases-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildinternet%2Freleases-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildinternet%2Freleases-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildinternet%2Freleases-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildinternet%2Freleases-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buildinternet","download_url":"https://codeload.github.com/buildinternet/releases-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildinternet%2Freleases-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33497930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","changelogs","cli","release-notes"],"created_at":"2026-04-16T23:03:20.374Z","updated_at":"2026-06-09T02:03:38.498Z","avatar_url":"https://github.com/buildinternet.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Releases CLI\n\n[![npm](https://img.shields.io/npm/v/@buildinternet/releases?color=cb3837\u0026label=npm\u0026logo=npm)](https://www.npmjs.com/package/@buildinternet/releases)\n[![Release](https://github.com/buildinternet/releases-cli/actions/workflows/release.yml/badge.svg)](https://github.com/buildinternet/releases-cli/actions/workflows/release.yml)\n[![Test](https://github.com/buildinternet/releases-cli/actions/workflows/test.yml/badge.svg)](https://github.com/buildinternet/releases-cli/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![skills.sh](https://skills.sh/b/buildinternet/releases-cli)](https://skills.sh/buildinternet/releases-cli)\n\nThe changelog \u0026 release-notes registry for developers and AI agents. A lean HTTP client for [releases.sh](https://releases.sh) — search and browse release notes from GitHub, RSS/Atom/JSON feeds, and product changelog pages without any local infrastructure.\n\nThe CLI talks to the hosted registry at `api.releases.sh`. Reader commands work out of the box with no configuration.\n\n\u003e **Reader access is open; admin access is closed beta.** Search and browse need no account. You can mint a personal **read-only** API key with `releases login` (browser sign-in — see [Authentication](#authentication)). `releases admin …` commands need a **write/admin** key, which isn't self-serve yet — open an issue for early access. Everything below the install section assumes reader-only use unless stated otherwise.\n\n## Install\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew install buildinternet/tap/releases\n```\n\n### npm (macOS, Linux, Windows)\n\n```bash\nnpm install -g @buildinternet/releases\n```\n\nOr run without installing:\n\n```bash\nnpx @buildinternet/releases@latest search \"react\"\n```\n\nAlways include the `@latest` tag — bare `npx @buildinternet/releases` caches the first-fetched version forever and won't pick up updates.\n\n### Shell installer (macOS, Linux)\n\n```bash\ncurl -fsSL https://releases.sh/install | bash\n```\n\nDownloads the matching platform binary from npm. Respects `RELEASES_INSTALL_DIR` (default: `/usr/local/bin`). Windows users should use npm or the GitHub Releases archive below.\n\n### Precompiled binaries (GitHub Releases)\n\nEvery version publishes signed archives for each platform on the [Releases page](https://github.com/buildinternet/releases-cli/releases) — `releases-{darwin-arm64,darwin-x64,linux-arm64,linux-x64}.gz` and `releases-windows-x64.zip`, each with a matching `.sha256` and a top-level `checksums.txt`. Useful for air-gapped installs, version pinning, or platforms where npm and Homebrew aren't an option.\n\n### Shell completion\n\n**Homebrew installs bash, zsh, and fish completions automatically** — nothing extra to do. For every other install path (npm, the `curl | bash` installer, and the raw GitHub binaries), enable completions once:\n\n```bash\nreleases completion install          # auto-detects $SHELL\nreleases completion install zsh      # or pick explicitly\n```\n\n`install` writes to the conventional location (`~/.zsh/completions/_releases`, `~/.local/share/bash-completion/completions/releases`, or `~/.config/fish/completions/releases.fish`) and prints any rc-file lines you may need to add. The bash and fish paths honor `$XDG_DATA_HOME` and `$XDG_CONFIG_HOME` respectively, so the file lands wherever those point if set. Pass `--path \u003cfile\u003e` to override the destination. To pipe the script somewhere yourself:\n\n```bash\nreleases completion zsh \u003e /path/to/_releases\n```\n\nOn an interactive terminal, a persistent, self-resolving notice on the landing screen and `--help` reminds you to run this until shell completion is detected — and stops on its own once completions are set up (including the automatic Homebrew install). Set `RELEASES_NO_COMPLETION_HINT=1` to silence it.\n\n## Usage\n\n```bash\nreleases search \"authentication\"\nreleases search \"slack integration\" --since 90d   # filter release hits by publish date\nreleases tail next-js                    # or `releases tail -f` to follow new releases\nreleases tail src_abc123                 # IDs work everywhere a slug does\nreleases tail --since 30d                # only releases from the last 30 days\nreleases list --category ai\nreleases get vercel                      # org, product, or source\nreleases get org_abc123                  # typed IDs are accepted\nreleases org overview vercel             # full AI-generated overview for an org\nreleases stats\nreleases submit https://acme.dev/changelog        # suggest a source for the registry\nreleases feedback \"great tool, here's an idea…\"   # send feedback to the maintainers\n```\n\nEvery command that takes an org / product / source / release identifier accepts the typed ID form (`org_…`, `prod_…`, `src_…`, `rel_…`) interchangeably with the slug. IDs are stable across renames; slugs are friendlier when typing. Sources and products also accept the `org/slug` coordinate form (e.g. `vercel/next-js`).\n\n`search` and `tail`/`latest` accept `--since` and `--until` to bound releases by publish date — an ISO date (`2026-01-01`) or relative shorthand (`90d`, `4w`, `6m`, `2y`). On `search` the window applies to release hits only.\n\nEvery reader command supports `--json` for machine-readable output. List commands emit a `{ items, pagination }` envelope — parse with `jq '.items[]'`, and check `.pagination.hasMore` before assuming you've seen every row. Nested `metadata` fields are returned as parsed objects (no `fromjson` needed). `org get` includes a short overview preview (with a stale warning when more than 30 days old); `org overview \u003cidentifier\u003e` prints the full body.\n\nThe release reader commands (`get`, `search`, `tail`/`latest`) return a **slim** release shape by default — `id`, `version`, `title`, `summary`, a markdown-stripped `excerpt`, `url`, `publishedAt`, nested `source`/`org`, and `contentChars`/`contentTokens` size hints — so agents aren't billed tokens for storage/pipeline internals. Pass `--full` to recover the complete payload (`content`, `contentHash`, `composition`, the `title*` variants, …). Note this is the inverse of the catalog `list` command, which is verbose by default and opts _into_ a lightweight shape with `--compact`.\n\nTabular reader commands fit themselves to the terminal width when stdout is a TTY (column truncation with `…`) and switch to bare TSV when piped — no headers, no color, no truncation — so `releases org list | cut -f2` works without parsing ANSI. `COLUMNS=\u003cn\u003e` overrides the detected width. For complete, parseable output prefer `--json`. The `search` / `tail`/`latest` human view is a single aligned row per release (identity · description · relative age · dimmed `rel_…`); `search` adds a cleaned, markdown-stripped excerpt under each hit.\n\n### Following \u0026 personalized feed\n\nFollow organizations and products to build a personalized release feed. These act on your own account, so they need a signed-in CLI — run `releases login` first (or set `RELEASES_API_KEY`).\n\n```bash\nreleases follow vercel              # an org slug…\nreleases follow vercel/next-js      # …an org/product coordinate…\nreleases follow prod_abc123         # …or a typed ID\nreleases following                  # list what you follow\nreleases feed                       # your personalized release timeline\nreleases feed --limit 50 --page 2   # paginate (also --json)\nreleases unfollow vercel\n```\n\nFollowing an organization includes all of its products. `feed` renders like `tail` (one aligned row per release, `--json` for machine output) and is page-paginated.\n\n### Feedback\n\nTell the maintainers about a bug, an idea, or anything else. No API key or account required:\n\n```bash\nreleases feedback \"tail -f reconnects slowly on flaky wifi\"   # one-shot message\nreleases feedback --type bug                                  # prompt for the text (interactive)\necho \"longer write-up…\" | releases feedback                   # pipe from stdin\nreleases feedback \"love the tool\" --contact you@example.com   # optional reply-to\nreleases feedback \"draft\" --dry-run --json                    # preview the payload, send nothing\n```\n\nWith no message argument in an interactive terminal, `feedback` prompts for the text (and an optional contact); otherwise pass it inline or pipe via stdin. `--type` accepts `bug`, `idea`, or `other`. Maintainers with admin access review submissions via `releases admin feedback list` (filter by `--type` / `--status`, `--include-archived`, paginate with `--cursor`) and triage them: `releases admin feedback triage \u003cid\u003e --status closed`, `releases admin feedback archive \u003cid\u003e` (`--undo` to restore), and `releases admin feedback delete \u003cid\u003e` (permanent — type the id to confirm, or pass `--yes`).\n\n### Submit a source\n\nSuggest a changelog or release-notes URL for the registry — the same review queue the [web submit form](https://releases.sh/submit) feeds. No API key or account required:\n\n```bash\nreleases submit https://acme.dev/changelog                       # one-shot\nreleases submit acme.dev/changelog                               # scheme optional — https:// is assumed\nreleases submit                                                  # prompt for the URL (interactive)\necho \"https://acme.dev/releases\" | releases submit               # pipe from stdin\nreleases submit https://acme.dev/changelog --note \"GitHub: acme/acme\" --contact you@example.com\nreleases submit https://acme.dev/changelog --dry-run --json      # preview the payload, send nothing\n```\n\nIndex pages, changelogs, GitHub releases, and feed URLs are all ideal. `--note` carries extra context (product name, GitHub repo, feed quirks) and `--contact` is an optional email to notify once it's reviewed. With no URL argument in an interactive terminal, `submit` prompts for it (and the optional note/contact); otherwise pass it inline or pipe via stdin. Maintainers with admin access review the queue via `releases admin recommendations list` (filter by `--status` / `--type`, `--include-archived`, paginate with `--cursor`) and triage them: `releases admin recommendations triage \u003cid\u003e --status closed`, `releases admin recommendations archive \u003cid\u003e` (`--undo` to restore), and `releases admin recommendations delete \u003cid\u003e` (permanent — type the id to confirm, or pass `--yes`).\n\n### MCP\n\nPoint Claude Code (or any MCP-compatible agent) at the hosted MCP server:\n\n```bash\nnpx mcp-remote https://mcp.releases.sh/mcp\n```\n\nOr run a local stdio bridge that proxies the same tools to `api.releases.sh`:\n\n```bash\nreleases admin mcp serve\n```\n\n### Claude Code plugins\n\nThis repo is a Claude Code marketplace named `releases` that publishes two plugins. Add the marketplace once, then install whichever surfaces you want:\n\n```bash\n/plugin marketplace add buildinternet/releases-cli\n\n# Reader surface — search and look up releases:\n/plugin install releases@releases\n\n# Admin surface — onboard and maintain sources (requires admin API access):\n/plugin install releases-admin@releases\n```\n\nOr point at a local clone for development:\n\n```bash\nclaude --plugin-dir .\n```\n\n**`releases` (reader)** — for anyone querying the registry:\n\n- **Hosted MCP connection** to `mcp.releases.sh` — search, lookup, and changelog slicing tools.\n- **`/releases \u003cproduct\u003e [query]`** command for manual lookups.\n- **Auto-trigger skills:**\n  - `releases-mcp` — activates on questions about releases, changelogs, or breaking changes (\"what's new in Next.js 15?\").\n  - `releases-cli` — activates when a user mentions or runs the `releases` CLI.\n  - `analyzing-releases` — competitive intel across multiple companies.\n  - `finding-changelogs` — discovering and evaluating changelog URLs.\n\n**`releases-admin`** — for maintainers running their own registry or contributing back:\n\n- **Agents** — `discovery` (finds and onboards sources) and `worker` (executes fetches).\n- **Auto-trigger skills:**\n  - `managing-sources` — CRUD on sources, ignored/blocked URLs, validation.\n  - `parsing-changelogs` — fetch and parse pipeline reference.\n  - `classify-media-relevance` — release-image classification helper.\n  - `seeding-playbooks` — bulk playbook authoring across orgs.\n\n\u003e Claude Code plugins install atomically — there is no Claude Code–native flow for grabbing a single skill without the rest of the plugin. See the next section for an agent-neutral install path.\n\n### Standalone skills (any agent)\n\nThe bundled skills are also available as a standalone package. The fastest way to install them is via the CLI:\n\n```bash\nreleases skills install                       # detected agent, current project\nreleases skills install --global              # user-wide instead of project\nreleases skills install --agent cursor        # override detection\nreleases skills install releases-mcp          # just the user-facing lookup skill\n```\n\nThis is a thin wrapper around the [`skills`](https://github.com/vercel-labs/skills) CLI from the open agent-skills ecosystem (`vercel-labs/skills`), which auto-detects ~50 supported agents (Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Windsurf, GitHub Copilot, …) and writes to the right per-agent skills directory. If you'd rather skip the `releases` CLI entirely, the underlying command is:\n\n```bash\nnpx skills add buildinternet/releases-cli\n```\n\nUse this path when you only want the skill behavior (auto-triggering on release/CLI questions) without also registering the hosted MCP connection, agents, and `/releases` command that the plugin provides. Skills are symlinked by default, so re-running `releases skills install` (or `npx skills update releases-cli`) refreshes everything atomically.\n\n## Authentication\n\nMost commands are reader-only and need no auth. The easiest way to get a personal API key is to sign in through your browser — no token to copy or paste:\n\n```bash\nreleases login              # opens your browser to approve, then saves the key\nreleases login --no-browser # print the URL + code to open yourself (headless / SSH)\n```\n\nThis uses the OAuth 2.0 Device Authorization Grant (RFC 8628): the CLI shows a short code, you approve it at [releases.sh/device](https://releases.sh/device) in a signed-in browser, and a **read-only** key is minted and saved to `~/.releases/credentials`. Sign up / sign in to the web app first if you haven't. A read-only key is all that's self-serve today; write/admin keys are closed beta (see above).\n\n### Managing keys\n\nList, create, and revoke your personal API keys without leaving the terminal:\n\n```bash\nreleases keys list                                  # your keys (id, scope, prefix, created, expiry)\nreleases keys create --name \"ci-bot\"                # mints a read-only key, shown once\nreleases keys create --name \"ci-bot\" --expires-in-days 90\nreleases keys revoke \u003cid\u003e                            # delete a key (confirm, or pass --yes)\n```\n\nKeys created here are **read-only** (write/admin are not self-serve). The created key string is shown exactly once — store it then. These commands reuse the session from `releases login`, re-prompting the browser approval only when it has expired; the session is bound to the API environment it was issued against, so switching `RELEASES_API_URL` re-authenticates rather than reusing a key from another environment.\n\n### Storing a token directly\n\nIf you've been issued a token (for example a write/admin key during the closed beta), store it without the browser flow using the `auth` namespace, so you don't need `RELEASES_API_KEY` in your shell every time:\n\n```bash\nreleases auth login                     # interactive prompt (masked input)\nreleases auth login --token \u003ctoken\u003e     # pass directly\nreleases auth login --token -           # read from stdin (pipe-friendly)\n```\n\nThe token is verified against `GET /v1/tokens/me` before being saved. If verification fails, nothing is written.\n\n```bash\nreleases auth status                    # show current auth state\nreleases auth status --json             # machine-readable (authenticated, source, scopes, …)\nreleases auth status --verify           # re-check the token against the API live\nreleases auth token                     # print the raw token (for scripts)\nreleases auth logout                    # remove the stored token\n```\n\n`whoami` is an alias for `auth status`.\n\n**Credential precedence:** if `RELEASES_API_KEY` is set in the environment it takes priority over any stored credential — useful for CI or per-command overrides.\n\n**Storage:** credentials are written to `~/.releases/credentials` with `0600` permissions (owner read/write, rw-------). The file is JSON and contains the token, name, scopes, the API URL the token was verified against, and a `savedAt` timestamp.\n\n## Environment\n\nNothing is required for reader access. For admin operations (closed beta — see above):\n\n- `RELEASES_API_KEY` — Bearer token for write endpoints. Overrides any stored credential from `releases login` / `releases auth login`. Required for any `releases admin …` command that mutates state if no stored credential is present. Write/admin keys are not self-serve yet; a personal **read-only** key is available via `releases login`.\n- `RELEASES_API_URL` — Override the default `https://api.releases.sh` endpoint (useful for staging).\n- `RELEASES_TELEMETRY_DISABLED=1` — Opt out of anonymous usage pings. `DO_NOT_TRACK=1` is also honored.\n- `RELEASES_DISABLE_SKILL_UPDATE_CHECK=1` — Silence the \"skills are behind, run `releases skills install`\" stderr nag that fires (at most once per 24h) when the GitHub `skills/` tree has moved since your last install.\n- `RELEASES_RUN_DIR` — When set, every `releases admin …` write appends one JSONL line (`{timestamp, command, target, result}`) to `$RELEASES_RUN_DIR/mutations.jsonl` — an audit trail for agent-driven maintenance batches. Unset → no-op. Also the default destination for managed-session traces (`--trace-dir` / `--save` override it). Part of the `~/.releases/work/` maintenance workspace.\n\nCopy `.env.example` to `.env` to configure these locally.\n\n## Contributing\n\nBuild, test, and release instructions live in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Exit codes\n\n| Code  | Meaning                                                                          |\n| ----- | -------------------------------------------------------------------------------- |\n| `0`   | Success — session completed or command finished cleanly                          |\n| `1`   | Application error — our-side failure (network, API, unexpected state)            |\n| `2`   | Usage / provider error — bad arguments or upstream provider rejected the request |\n| `130` | Cancellation — session was cancelled (mirrors the SIGINT convention)             |\n\nDefined in [`src/cli/commands/fetch-wait.ts`](./src/cli/commands/fetch-wait.ts) (`TerminalSummary.exitCode`).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildinternet%2Freleases-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuildinternet%2Freleases-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildinternet%2Freleases-cli/lists"}