@buildinternet/releases 0.60.0 → 0.62.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -198
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -6,270 +6,122 @@
|
|
|
6
6
|
[](./LICENSE)
|
|
7
7
|
[](https://skills.sh/buildinternet/releases-cli)
|
|
8
8
|
|
|
9
|
-
The changelog & release-notes registry for developers and AI agents
|
|
9
|
+
The changelog & 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, with no local infrastructure.
|
|
10
10
|
|
|
11
|
-
The CLI talks to the hosted registry at `api.releases.sh`.
|
|
12
|
-
|
|
13
|
-
> **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.
|
|
11
|
+
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 and get a personalized feed; 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.
|
|
14
12
|
|
|
15
13
|
## Install
|
|
16
14
|
|
|
17
|
-
### Homebrew (macOS / Linux)
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
brew install buildinternet/tap/releases
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
### npm (macOS, Linux, Windows)
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
npm install -g @buildinternet/releases
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Or run without installing:
|
|
30
|
-
|
|
31
15
|
```bash
|
|
32
|
-
|
|
16
|
+
brew install buildinternet/tap/releases # Homebrew (macOS / Linux)
|
|
17
|
+
npm install -g @buildinternet/releases # npm (macOS / Linux / Windows)
|
|
18
|
+
curl -fsSL https://releases.sh/install | bash # shell installer (macOS / Linux)
|
|
33
19
|
```
|
|
34
20
|
|
|
35
|
-
|
|
21
|
+
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](https://github.com/buildinternet/releases-cli/releases) (with checksums) for air-gapped installs or version pinning.
|
|
36
22
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
curl -fsSL https://releases.sh/install | bash
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Downloads 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.
|
|
44
|
-
|
|
45
|
-
### Precompiled binaries (GitHub Releases)
|
|
46
|
-
|
|
47
|
-
Every 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.
|
|
48
|
-
|
|
49
|
-
### Shell completion
|
|
50
|
-
|
|
51
|
-
**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:
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
releases completion install # auto-detects $SHELL
|
|
55
|
-
releases completion install zsh # or pick explicitly
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
`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 <file>` to override the destination. To pipe the script somewhere yourself:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
releases completion zsh > /path/to/_releases
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
On 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.
|
|
23
|
+
Homebrew installs shell completions automatically. On every other path, enable them once with `releases completion install` (auto-detects `$SHELL`).
|
|
65
24
|
|
|
66
25
|
## Usage
|
|
67
26
|
|
|
68
27
|
```bash
|
|
69
28
|
releases search "authentication"
|
|
70
|
-
releases search "slack integration" --since 90d #
|
|
71
|
-
releases tail next-js
|
|
72
|
-
releases tail src_abc123 # IDs work everywhere a slug does
|
|
73
|
-
releases tail --since 30d # only releases from the last 30 days
|
|
29
|
+
releases search "slack integration" --since 90d # bound release hits by publish date
|
|
30
|
+
releases tail next-js # latest releases; `tail -f` to follow
|
|
74
31
|
releases list --category ai
|
|
75
|
-
releases get vercel
|
|
76
|
-
releases
|
|
77
|
-
releases org overview vercel # full AI-generated overview for an org
|
|
32
|
+
releases get vercel # org, product, or source
|
|
33
|
+
releases org overview vercel # full AI-generated org overview
|
|
78
34
|
releases stats
|
|
79
|
-
releases submit https://acme.dev/changelog
|
|
80
|
-
releases feedback "great tool
|
|
35
|
+
releases submit https://acme.dev/changelog # suggest a source for the registry
|
|
36
|
+
releases feedback "great tool — here's an idea…" # message the maintainers
|
|
81
37
|
```
|
|
82
38
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
`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.
|
|
86
|
-
|
|
87
|
-
Every 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 <identifier>` prints the full body.
|
|
39
|
+
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`).
|
|
88
40
|
|
|
89
|
-
|
|
41
|
+
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.
|
|
90
42
|
|
|
91
|
-
|
|
43
|
+
### Following & personalized feed
|
|
92
44
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
Tell the maintainers about a bug, an idea, or anything else. No API key or account required:
|
|
45
|
+
Follow orgs and products to build a personalized feed. These act on your own account, so sign in first (`releases login`):
|
|
96
46
|
|
|
97
47
|
```bash
|
|
98
|
-
releases
|
|
99
|
-
releases
|
|
100
|
-
|
|
101
|
-
releases
|
|
102
|
-
releases feedback "draft" --dry-run --json # preview the payload, send nothing
|
|
48
|
+
releases follow vercel # org slug, org/product coordinate, or typed ID
|
|
49
|
+
releases following # list what you follow
|
|
50
|
+
releases feed # your release timeline (--json, --page, --limit)
|
|
51
|
+
releases unfollow vercel
|
|
103
52
|
```
|
|
104
53
|
|
|
105
|
-
|
|
54
|
+
Following an organization includes all of its products.
|
|
106
55
|
|
|
107
|
-
###
|
|
56
|
+
### Contribute to the registry
|
|
108
57
|
|
|
109
|
-
|
|
58
|
+
Neither needs an account or API key:
|
|
110
59
|
|
|
111
60
|
```bash
|
|
112
|
-
releases submit https://acme.dev/changelog
|
|
113
|
-
releases
|
|
114
|
-
releases submit # prompt for the URL (interactive)
|
|
115
|
-
echo "https://acme.dev/releases" | releases submit # pipe from stdin
|
|
116
|
-
releases submit https://acme.dev/changelog --note "GitHub: acme/acme" --contact you@example.com
|
|
117
|
-
releases submit https://acme.dev/changelog --dry-run --json # preview the payload, send nothing
|
|
61
|
+
releases submit https://acme.dev/changelog # suggest a changelog / release-notes URL
|
|
62
|
+
releases feedback "tail -f reconnects slowly" # report a bug or share an idea
|
|
118
63
|
```
|
|
119
64
|
|
|
120
|
-
|
|
65
|
+
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](https://releases.sh/submit).
|
|
121
66
|
|
|
122
|
-
### MCP
|
|
67
|
+
### MCP & Claude Code
|
|
123
68
|
|
|
124
|
-
Point
|
|
69
|
+
Point any MCP-compatible agent at the hosted server:
|
|
125
70
|
|
|
126
71
|
```bash
|
|
127
72
|
npx mcp-remote https://mcp.releases.sh/mcp
|
|
128
73
|
```
|
|
129
74
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
releases admin mcp serve
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
### Claude Code plugins
|
|
137
|
-
|
|
138
|
-
This repo is a Claude Code marketplace named `releases` that publishes two plugins. Add the marketplace once, then install whichever surfaces you want:
|
|
75
|
+
This repo is also a Claude Code marketplace with two plugins — `releases` (reader: hosted MCP tools, a `/releases` lookup command, and auto-trigger skills) and `releases-admin` (source onboarding + maintenance; needs admin access):
|
|
139
76
|
|
|
140
77
|
```bash
|
|
141
78
|
/plugin marketplace add buildinternet/releases-cli
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
/plugin install releases@releases
|
|
145
|
-
|
|
146
|
-
# Admin surface — onboard and maintain sources (requires admin API access):
|
|
147
|
-
/plugin install releases-admin@releases
|
|
79
|
+
/plugin install releases@releases # reader
|
|
80
|
+
/plugin install releases-admin@releases # admin
|
|
148
81
|
```
|
|
149
82
|
|
|
150
|
-
Or
|
|
83
|
+
Or install just the skills into any agent (Cursor, Codex, Gemini CLI, Windsurf, …):
|
|
151
84
|
|
|
152
85
|
```bash
|
|
153
|
-
|
|
86
|
+
releases skills install # or, without the CLI: npx skills add buildinternet/releases-cli
|
|
154
87
|
```
|
|
155
88
|
|
|
156
|
-
**`releases` (reader)** — for anyone querying the registry:
|
|
157
|
-
|
|
158
|
-
- **Hosted MCP connection** to `mcp.releases.sh` — search, lookup, and changelog slicing tools.
|
|
159
|
-
- **`/releases <product> [query]`** command for manual lookups.
|
|
160
|
-
- **Auto-trigger skills:**
|
|
161
|
-
- `releases-mcp` — activates on questions about releases, changelogs, or breaking changes ("what's new in Next.js 15?").
|
|
162
|
-
- `releases-cli` — activates when a user mentions or runs the `releases` CLI.
|
|
163
|
-
- `analyzing-releases` — competitive intel across multiple companies.
|
|
164
|
-
- `finding-changelogs` — discovering and evaluating changelog URLs.
|
|
165
|
-
|
|
166
|
-
**`releases-admin`** — for maintainers running their own registry or contributing back:
|
|
167
|
-
|
|
168
|
-
- **Agents** — `discovery` (finds and onboards sources) and `worker` (executes fetches).
|
|
169
|
-
- **Auto-trigger skills:**
|
|
170
|
-
- `managing-sources` — CRUD on sources, ignored/blocked URLs, validation.
|
|
171
|
-
- `parsing-changelogs` — fetch and parse pipeline reference.
|
|
172
|
-
- `classify-media-relevance` — release-image classification helper.
|
|
173
|
-
- `seeding-playbooks` — bulk playbook authoring across orgs.
|
|
174
|
-
|
|
175
|
-
> 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.
|
|
176
|
-
|
|
177
|
-
### Standalone skills (any agent)
|
|
178
|
-
|
|
179
|
-
The bundled skills are also available as a standalone package. The fastest way to install them is via the CLI:
|
|
180
|
-
|
|
181
|
-
```bash
|
|
182
|
-
releases skills install # detected agent, current project
|
|
183
|
-
releases skills install --global # user-wide instead of project
|
|
184
|
-
releases skills install --agent cursor # override detection
|
|
185
|
-
releases skills install releases-mcp # just the user-facing lookup skill
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
This 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:
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
npx skills add buildinternet/releases-cli
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Use 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.
|
|
195
|
-
|
|
196
89
|
## Authentication
|
|
197
90
|
|
|
198
|
-
|
|
91
|
+
Search and browse need no auth. Signing in is what powers the personal touches — **following orgs/products and your customized feed** — and mints a personal **read-only** key (it can't write or administer anything; it just identifies you, and unlocks higher rate limits as those land). The easiest way in is your browser — nothing to copy or paste:
|
|
199
92
|
|
|
200
93
|
```bash
|
|
201
94
|
releases login # opens your browser to approve, then saves the key
|
|
202
95
|
releases login --no-browser # print the URL + code to open yourself (headless / SSH)
|
|
203
96
|
```
|
|
204
97
|
|
|
205
|
-
This uses the OAuth 2.0 Device Authorization Grant (RFC 8628):
|
|
206
|
-
|
|
207
|
-
### Managing keys
|
|
208
|
-
|
|
209
|
-
List, create, and revoke your personal API keys without leaving the terminal:
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
releases keys list # your keys (id, scope, prefix, created, expiry)
|
|
213
|
-
releases keys create --name "ci-bot" # mints a read-only key, shown once
|
|
214
|
-
releases keys create --name "ci-bot" --expires-in-days 90
|
|
215
|
-
releases keys revoke <id> # delete a key (confirm, or pass --yes)
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
Keys 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.
|
|
219
|
-
|
|
220
|
-
### Storing a token directly
|
|
221
|
-
|
|
222
|
-
If 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:
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
releases auth login # interactive prompt (masked input)
|
|
226
|
-
releases auth login --token <token> # pass directly
|
|
227
|
-
releases auth login --token - # read from stdin (pipe-friendly)
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
The token is verified against `GET /v1/tokens/me` before being saved. If verification fails, nothing is written.
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
releases auth status # show current auth state
|
|
234
|
-
releases auth status --json # machine-readable (authenticated, source, scopes, …)
|
|
235
|
-
releases auth status --verify # re-check the token against the API live
|
|
236
|
-
releases auth token # print the raw token (for scripts)
|
|
237
|
-
releases auth logout # remove the stored token
|
|
238
|
-
```
|
|
98
|
+
This uses the OAuth 2.0 Device Authorization Grant (RFC 8628): approve a short code at [releases.sh/device](https://releases.sh/device) in a signed-in browser, and a read-only key is saved to `~/.releases/credentials` (`0600`). Manage keys with `releases keys list` / `create` / `revoke`.
|
|
239
99
|
|
|
240
|
-
`whoami` is an alias for
|
|
100
|
+
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.
|
|
241
101
|
|
|
242
|
-
|
|
102
|
+
## Environment
|
|
243
103
|
|
|
244
|
-
|
|
104
|
+
Reader access requires nothing. Useful overrides:
|
|
245
105
|
|
|
246
|
-
|
|
106
|
+
- `RELEASES_API_KEY` — Bearer token for write endpoints; overrides stored credentials.
|
|
107
|
+
- `RELEASES_API_URL` — override the default `https://api.releases.sh` (e.g. staging).
|
|
108
|
+
- `RELEASES_TELEMETRY_DISABLED=1` — opt out of anonymous usage pings (`DO_NOT_TRACK=1` also honored).
|
|
247
109
|
|
|
248
|
-
|
|
110
|
+
See [`.env.example`](./.env.example) for the full list.
|
|
249
111
|
|
|
250
|
-
|
|
251
|
-
- `RELEASES_API_URL` — Override the default `https://api.releases.sh` endpoint (useful for staging).
|
|
252
|
-
- `RELEASES_TELEMETRY_DISABLED=1` — Opt out of anonymous usage pings. `DO_NOT_TRACK=1` is also honored.
|
|
253
|
-
- `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.
|
|
254
|
-
- `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.
|
|
112
|
+
## Exit codes
|
|
255
113
|
|
|
256
|
-
|
|
114
|
+
| Code | Meaning |
|
|
115
|
+
| ----- | ------------------------------------------------------------ |
|
|
116
|
+
| `0` | Success |
|
|
117
|
+
| `1` | Application error (network, API, unexpected state) |
|
|
118
|
+
| `2` | Usage / provider error (bad arguments or upstream rejection) |
|
|
119
|
+
| `130` | Cancellation (SIGINT) |
|
|
257
120
|
|
|
258
121
|
## Contributing
|
|
259
122
|
|
|
260
123
|
Build, test, and release instructions live in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
261
124
|
|
|
262
|
-
## Exit codes
|
|
263
|
-
|
|
264
|
-
| Code | Meaning |
|
|
265
|
-
| ----- | -------------------------------------------------------------------------------- |
|
|
266
|
-
| `0` | Success — session completed or command finished cleanly |
|
|
267
|
-
| `1` | Application error — our-side failure (network, API, unexpected state) |
|
|
268
|
-
| `2` | Usage / provider error — bad arguments or upstream provider rejected the request |
|
|
269
|
-
| `130` | Cancellation — session was cancelled (mirrors the SIGINT convention) |
|
|
270
|
-
|
|
271
|
-
Defined in [`src/cli/commands/fetch-wait.ts`](./src/cli/commands/fetch-wait.ts) (`TerminalSummary.exitCode`).
|
|
272
|
-
|
|
273
125
|
## License
|
|
274
126
|
|
|
275
127
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@buildinternet/releases",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.62.0",
|
|
4
4
|
"description": "The changelog & release-notes registry for developers and AI agents",
|
|
5
5
|
"bin": {
|
|
6
6
|
"releases": "bin/releases"
|
|
@@ -13,11 +13,11 @@
|
|
|
13
13
|
"README.md"
|
|
14
14
|
],
|
|
15
15
|
"optionalDependencies": {
|
|
16
|
-
"@buildinternet/releases-darwin-arm64": "0.
|
|
17
|
-
"@buildinternet/releases-darwin-x64": "0.
|
|
18
|
-
"@buildinternet/releases-linux-x64": "0.
|
|
19
|
-
"@buildinternet/releases-linux-arm64": "0.
|
|
20
|
-
"@buildinternet/releases-windows-x64": "0.
|
|
16
|
+
"@buildinternet/releases-darwin-arm64": "0.62.0",
|
|
17
|
+
"@buildinternet/releases-darwin-x64": "0.62.0",
|
|
18
|
+
"@buildinternet/releases-linux-x64": "0.62.0",
|
|
19
|
+
"@buildinternet/releases-linux-arm64": "0.62.0",
|
|
20
|
+
"@buildinternet/releases-windows-x64": "0.62.0"
|
|
21
21
|
},
|
|
22
22
|
"keywords": [
|
|
23
23
|
"changelog",
|