Releases CLI

Minor Changes

• ca636fa: Improve the release-reader ergonomics for get, latest/tail, and list (#303, #304):
  • get <id> --json now surfaces media[] (with the R2-mirrored r2Url) when a release has media, plus a contentTruncated: true hint so callers know the body was projected to an excerpt and --full exists. Previously the slim shape dropped media entirely with no signal it existed, forcing a round-trip to --full or the raw API to verify media presence. --full is unchanged.
  • latest/tail gain --limit (an alias for the existing --count) so the absence of --limit — which works on other commands — no longer errors with "unknown option". Both clamp to the server's [1, 100] window, and a one-shot listing that fills the requested window now prints a truncation hint to stderr (raise --limit, narrow with --since/--until/--source/--org, or for --product feeds, page with the surfaced --cursor).
  • latest --product is cursor-paginated; a new --cursor flag pages through it deterministically (the global latest feed has no cursor — it is count-capped — so --cursor errors there).
  • releases list now shows a Releases per-source count column in the text table, so "how many releases does this source have?" is answerable without dropping to --json (which already carried releaseCount) or the raw API.

Patch Changes

• e045fe0: Trim the README to a leaner npm landing page (291 → ~130 lines): merge the install paths, condense the shell-completion and output-format prose into pointers to --help, drop the closed-beta admin-triage detail, and consolidate the auth sections. Reframe sign-in messaging around its present-day value — following orgs/products and a personalized feed — with read-only keys explicitly non-write/non-admin (and a path to higher rate limits), rather than leading with the closed-beta write/admin caveat.

Minor Changes

• 695039d: Add personalized follows + feed verbs: releases follow <org|product>, releases unfollow <org|product>, releases following (list), and releases feed (your personalized release timeline). They act on the signed-in user's account via the API's /v1/me/* routes — sign in with releases login (or set RELEASES_API_KEY) first. follow/unfollow accept an org slug, an org/product coordinate, or an org_…/prod_… id; feed reuses the same renderer as releases tail and is page-paginated (--page / --limit, --json). Requires @buildinternet/releases-api-types ≥ 0.32.0 for the follows wire types.
• de9ce26: Add releases source fetch <source> --dry-run: probe a single source without writing to D1 or dispatching (billing) the managed agent. For a client-rendered scrape source (crawlEnabled/renderRequired) it renders the index once via Browser Rendering and reports how many candidate release links were found — the cheap "can the steady-state cron render actually see releases here, or is it hitting an empty JS shell?" check that onboarding previously had no way to answer. For a feed/GitHub source it reports candidate releases parsed. Single source only; --json supported.

Minor Changes

• 5d191ea: Add releases admin webhook commands for managing outbound webhook subscriptions: add, list, show, edit, remove, test, rotate-secret, and deliveries. These wrap the existing root-key-gated /v1/webhooks API routes so Phase-A operators can manage subscriptions without raw API calls.

  The subscriber-facing webhook verify (local signature check, no auth) moves from admin webhook verify to top-level webhook verify.

• 313ffb0: Rename the local stdio MCP server's tools (releases admin mcp serve) to mirror the canonical names served by the hosted server at mcp.releases.sh: search_releases → search (now returns the full unified result — orgs, catalog, and releases — with an optional type section filter), list_sources + list_products → list_catalog (org-scoped via GET /v1/orgs/:slug/catalog; global path folds products + standalone sources), and get_product → get_catalog_entry (dispatches product vs. source on the identifier prefix). get_source / get_source_changelog are unchanged.

Minor Changes

• 639d0cd: feat(admin): releases admin oauth client … verbs

  Add CLI verbs to register and manage "Sign in with Releases" OAuth clients, wrapping the root-key-gated /v1/admin/oauth/clients routes from buildinternet/releases#1482. create (with --redirect-uri/--scope repeatable, --trusted, --public/PKCE, --no-pkce) prints the reloc_ secret once; list/get are secret-free; disable/enable toggle the reversible kill switch; trust/untrust toggle consent-screen skipping; rotate-secret issues a new secret once; delete is a hard removal.

• d3581d0: feat(admin): releases admin user set-role | get-role | list-roles (#288)

  Add CLI verbs to manage user roles — the OAuth scope-entitlement source of truth (user→read, curator→read+write, admin→read+write+admin) — wrapping the root-key-gated /v1/admin/users/role routes from buildinternet/releases#1485. set-role shows previousRole → role; get-role reads one user; list-roles lists curator/admin users. Backfills the changeset omitted when #288 merged.

Minor Changes

• 67ff782: Add releases keys verbs (create/list/revoke) for self-serve, read-only user API keys. Authenticated via the device-flow session token persisted at login, with transparent re-auth on expiry.

Minor Changes

• 1f92ee4: feat(cli): releases login — device authorization (RFC 8628) (#282)

  Add a top-level releases login command that authenticates the CLI via the OAuth 2.0 Device Authorization Grant (RFC 8628): it requests a device/user code, opens the verification URL in the browser (with a headless copy-paste fallback), polls for approval, then exchanges the device session for a durable read-only relu_ API key minted via POST /v1/api-keys and stores it through the existing credential path. Backfills the changeset omitted when #282 merged.

• 8a6c994: feat(org): admin org avatar <org> --from <source> — one-step avatar ingest (#1406)

  Resolve an image, mirror it to R2, and set the org avatar in a single command. --from accepts an https:// URL, or a shortcut derived from the org's own data (no fuzzy matching): github (the org's linked GitHub handle → github.com/{handle}.png), favicon (the org domain's apple-touch-icon), or appstore (the org's App Store source → iTunes 1024px artwork). Resolution runs CLI-side; the server fetches, validates it's a square raster, and stores it — CF credentials stay server-side. Backed by POST /v1/orgs/:slug/avatar (api-types 0.30.0).

Minor Changes

• d0d1346: Add entity-notice rendering (Part A) and set/clear verbs (Part B) for org, product, and source entities (#278).

  Part A — render: releases get, releases org get, and releases admin source update detail views now display a curator notice in yellow when the API returns one — formatted as Notice: <message> → <coordinate-or-href> (pointer omitted when absent). The notice also passes through in all --json outputs.

  Part B — set/clear: New flags on the three entity update commands:

  • releases org update --notice <msg> / --notice-link <coord|url> / --notice-link-text <label> / --clear-notice
  • releases admin product update — same flags
  • releases admin source update — same flags

  --notice-link is routed automatically: an https?:// value is sent as href; anything else is validated as a 1–2-segment registry coordinate (org or org/slug) and sent as coordinate. --clear-notice sends { notice: null } to remove an existing notice. The flags are mutually exclusive (--clear-notice + --notice exits with an error).

  All flag parsing lives in src/lib/notice.ts. The Notice type is imported from @buildinternet/releases-core@0.23.0 (canonical source); this PR also bumps @buildinternet/releases-api-types to ^0.29.0.

Patch Changes

• 6ef7321: admin source fetch-log <source> now shows an in-progress banner when a managed-agent fetch is still running for that source — the session id plus how long it has been running — so an operator can tell a live fetch from a stuck one instead of seeing only terminal history (#1360). The source-filtered query reads the API's enveloped activeSession; --json output is unchanged (still the bare logs array). The status column also labels the crawl_timeout (#1361) and blocked (#1171) states distinctly instead of rendering them as "no change".

Minor Changes

• c5c4a3e: Add a --local handoff flag to admin source fetch <slug> (#273). It stages local onboarding for the local-ingest skill instead of dispatching the remote managed agent: it runs the same robots.txt / Content-Signal opt-out preflight as the monorepo skill (refuses on ai-input=no / ai-train=no, e.g. conductor.build; --force overrides with explicit publisher permission), resolves the source, discovers candidate page URLs from /sitemap.xml (filtered to the changelog path) or the index HTML, classifies the page shape, and prints a structured handoff brief (--json supported) — the org-scoped batch endpoint, the preflight verdict + parsed Content-Signal, and a capped candidate-URL list with an explicit skip note (no silent truncation). No managed-agent session, no model call, and no Anthropic/adapter dependency added to the thin client — HTTP fetch + string parsing only. Exit codes: 0 proceed, 1 refuse, 2 unknown.
• 4730f53: Add --hard to admin release delete --source and admin source delete. The default stays a soft delete (releases suppress, sources tombstone), but --hard passes ?hard=true so rows are removed outright and the UNIQUE(source_id, url) dedup slot frees up — enabling a clean purge + re-ingest without a full org hard-delete (#1184). Also fixes the soft release delete --source summary, which previously printed Deleted undefined releases because the API returns { suppressed } on that path.

Patch Changes

• 8f6f272: Bump @buildinternet/releases-api-types from ^0.24.0 to ^0.27.0 and commander from ^14.0.3 to ^15.0.0 (ESM-only; no API changes required for this CLI).

Minor Changes

• 9069be7: Add --primary to admin source create so an org's primary changelog can be marked in one step (isPrimary on the create POST), instead of creating the source and then running a follow-up admin source update <slug> --primary. The REST create endpoint and the manage_source "add" action already accepted this — the CLI was the only surface missing it, so it no longer rejects the --primary the managing-sources skill documents.
• 1072996: Add admin source create-video <channel-or-playlist-url> --org <slug> to materialize a video source from a YouTube channel/playlist (POST /v1/sources/video), surfacing the resolved provider/channel and backfilled release count. The generic source create now rejects --type video and pasted youtube.com/youtu.be URLs with a pointer to the dedicated verb — mirroring the App Store guard — so a YouTube URL can no longer be silently mis-created as an empty-bodied feed source.

Minor Changes

• 1447aad: admin org update and admin source update now accept --discovery <status> to promote or demote discovery status (curated | agent | on_demand).

• 54003b5: admin product list now lists products across all orgs when the org argument is omitted.

  The org argument is optional: releases admin product list (no org) enumerates products across every org, honoring --kind, --json, and the new --limit/--page pagination flags. The cross-org table gains an Org column so a bare product slug stays attributable; org-scoped listing keeps its original columns. This closes the CLI↔MCP gap that blocked a cross-org kind=sdk audit — previously expressible only via the remote MCP list_catalog tool (buildinternet/releases-cli#259). Backed by the existing org-agnostic GET /v1/products endpoint; no API change required.

Patch Changes

• 59ff421: Resolving a source by a bare slug (admin source fetch/fetch-log/update, the MCP get_source / get_source_changelog tools, and every other command that takes a source identifier) now errors and lists the matching org/slug + src_… candidates when that slug exists under more than one org, instead of silently resolving to the oldest match. Source slugs are unique per-org but not globally, so a bare blog could previously read from — or update could mutate — a source in the wrong org. Disambiguate with an org/slug coordinate or a src_… id (both already supported). Requires the API's ?slug= source filter (releases#1323).
• 6562369: Fix crash in admin overview inputs when the API returns 404 for on_demand orgs.

Minor Changes

• c4d9046: Admin source/org ergonomics: three fixes surfaced during a Discord onboarding cleanup.

  • admin source backfill <id|slug> — new verb wrapping the full-history backfill endpoint (POST /v1/workflows/backfill-source). Resolves a slug to the typed src_… ID, dry-runs by default (counts + date range), and writes with --no-dry-run/--commit. Supports --max-windows and --markdown-file (for JS-heavy / bot-blocked pages the worker can't fetch itself). (#252)
  • admin source create now accepts --keyword-allow <list> (→ metadata.feedKeywordAllow) and the general repeatable --metadata-set key=value, so feed filters are set atomically at create time. This closes the race where a follow-up source update lost to the onboard auto-fetch and ingested the whole unfiltered feed. (#237)
  • admin org delete --hard now succeeds: it sends the typed org_ ID the destructive path requires instead of the slug the server rejects. Soft delete still uses the slug. (#236)

• a744cad: Admin source backfill/re-extract: async-aware backfill + a new reextract verb.

  • admin source backfill now handles the async dispatch shape. Deep Firecrawl backfills run as a durable workflow (buildinternet/releases#1281/#1282) and return 202 { instanceId, statusUrl } instead of a report; the CLI now detects this rather than crashing on the non-report body. Matching admin overview batch, it dispatches and returns the workflow instance ID by default (non-blocking — the right primitive for the CLI's primary agent users), with --wait to poll inline and render the report. New sibling admin source backfill-status <instanceId> does a single-shot status read (renders the report when complete) so a dispatched workflow can be polled on the caller's own cadence. The Firecrawl-ceiling guidance hint is now surfaced. (buildinternet/releases#1285)
  • admin source reextract <id|slug> — new verb wrapping POST /v1/workflows/reextract-source (buildinternet/releases#1284). Re-extracts releases from a stored raw snapshot (released-raw) with no live scrape, no Firecrawl credits, deterministic input — for reprocessing history after extraction/parse logic improves. Dry-run by default; --snapshot-id pins a specific capture, --commit/--no-dry-run writes. Surfaces the endpoint's actionable errors (no_snapshot/snapshot_not_found 404, snapshot_expired 410, non-scrape 400, missing bucket/key 503). (buildinternet/releases-cli#257)

• a188184: admin org update now accepts --featured / --no-featured, so operators can curate the editorially-featured org list (the home-page rail, buildinternet/releases#1274/#1275) from the terminal instead of only via the web Admin menu or a raw API PATCH. The flag maps to PATCH /v1/orgs/:slug { featured }; aliased onto the deprecated org edit too. (#253)

Minor Changes

• 8935518: Add App Store source support to the admin CLI.
  • New releases admin source create-appstore <url-or-id> verb — accepts an apps.apple.com URL, a bare numeric track ID, or an appstore:<trackId> coordinate, with --platform ios|macos, --org, --product, --storefront, --json, and --dry-run. It calls POST /v1/sources/appstore, which resolves the listing, mints the first release, and backfills the product's app-icon avatar.
  • releases admin source create now recognizes appstore as a valid type and rejects --type appstore / pasted apps.apple.com URLs with a pointer to create-appstore (source types are now sourced from @buildinternet/releases-core instead of a hard-coded list).
  • releases admin product list and releases get <product> surface the product avatarUrl (the app icon).

Patch Changes

• 7a28fc2: Document the source create-appstore verb in the releases-cli admin skill reference: a dedicated "Create App Store source" section (identifier forms, --platform/--storefront, idempotency, the pre-create-product workflow) plus a note on the create command that App Store apps use it.
• ed73777: Document Firecrawl monitoring as a fetch backend in the changelog skills: add it as step 5 of the parsing-changelogs pipeline overview, and note in managing-sources / finding-changelogs that for sources behind a Cloudflare Managed Challenge (persistent no_change / 0 releases that --render can't fix), Firecrawl is enabled per-source via the admin API (POST /v1/sources/:slug/firecrawl/sync), not a CLI verb or --metadata-set.

Minor Changes

• 15ad436: Tighten and enrich releases get output for products, orgs, and sources.
  • Products now show their latest releases inline. A product card previously printed only metadata and pointed you at the org feed (which mixes sibling products) or a single source — an extra round-trip for the unit that's now primary. It now embeds a preview of the product's cross-source feed, matching what get <org> and get <source> already did, and the --json output gains a releases array.
  • Leaner cards. The standalone type label ("Product" / "Organization" / "Source") and the separate ID / Slug / Org rows are folded into a single header line — Name by OrgName (orgSlug/slug) (orgs, having no parent, render Name (slug)). The "by Org" clause is dropped when the name already names the org, so App Store-style names like "Claude by Anthropic" don't double up. Empty fields (e.g. a missing URL) are omitted instead of printing a dash, redundant counts (the product card's source count, the org card's product total and bare source total) are dropped, and the typed ID moves to a dim trailing line.
  • Release rows lead with the title. The feed description column now prefers the title family (AI headline → title) over the summary/content excerpt: feed surfaces often serve a raw content excerpt in summary when there's no curated AI summary yet, which buried the far more useful title (e.g. "Claude Design by Anthropic Labs" instead of "New Anthropic Labs product that lets you collaborate…"). The product and source cards also drop the leading source column — the owning entity is already in the header — so the title gets full width and App Store rows stop repeating "Claude by Anthropic │ Claude by Anthropic 1.2…".
  • Clearer Next steps. The product card's footer now leads with releases latest --product <org/slug> and a --since 90d variant, replacing an opaque "drill into one source" hint that pointed at an arbitrary first source by raw src_ id. Org and source footers use the unified latest verb and note the --since window.
  • The org card's release feed names the owning product. Now that the release-feed wire carries the owning product (api-types 0.23.0), get <org> keeps a leading column — populated with the product name (falling back to the source) — so a multi-product org's feed shows which product shipped each release instead of dropping the column entirely.
  • releases search gains --product. Scope a full-text / semantic query to a single product's sources — e.g. releases search "webhooks" --product vercel/next-js --since 90d. Accepts an org/slug coordinate, a prod_… id, or a product slug, and composes with --kind / --since / --until / --mode. An unknown product warns and returns no results, mirroring --domain.

Minor Changes

• f57a80e: Add a keyless releases submit <url> command to suggest a changelog or release-notes source for the registry — the terminal peer of the web submit form. Accepts an optional --note and --contact, normalizes a missing scheme to https://, and supports interactive/stdin input plus --dry-run. Maintainers review the queue via the new releases admin recommendations list/triage/archive/delete verbs, mirroring the existing admin feedback triage surface.

• 7721a3f: Add releases latest --product <org/slug> (alias releases tail --product) to show one product's cross-source release feed, backed by GET /v1/orgs/:slug/releases?product=. Accepts an org/slug coordinate, a prod_… id, or a bare product slug; composes with --count, --since/--until, --include-coverage, --json/--full, and --follow. It can't combine with a [source] argument or --org.

  The local MCP server's get_latest_releases tool now filters by product correctly too — previously its product argument was misrouted as a source filter, silently returning the wrong results.

Minor Changes

• 7ee9840: Auto-create products at onboarding: onboard apply now reads optional productName/productSlug tags emitted by the discovery agent and performs a lookup-or-create for each distinct product before attaching sources to the right product under the org.

Patch Changes

• 9e3147f: releases admin overview get now shows the overview's most recent update time when it differs from the original generation time, while keeping the release and citation counts in the summary line.

Minor Changes

• 5c6b819: Add --max-content-chars [n] to releases admin overview inputs. In --json mode it clips each selected[].content to at most n characters client-side before printing (bare flag defaults to 1000), leaving every other field — existingContent, media, totalAvailable, and the selected length itself — untouched. High-volume orgs emit 500K+ chars of full release content here (sentry's largest single release is ~125K), which exceeds the ~30K Bash stdout cap a Claude Code sub-agent reads through and gets silently truncated, so the overview would be generated from only the first few releases. The clip is purely client-side — the CLI still receives the full payload over the wire — so it removes that footgun without the multi-step jq workaround. Omitting the flag preserves today's full-content output.

Minor Changes

• 1a1575e: Add the releases admin feedback triage write-path: triage <id> --status <new|triaged|closed>, archive <id> (with --undo to restore), and delete <id> (hard delete, gated behind an id typeback or --yes). admin feedback list gains --include-archived and now marks archived rows. Consumes the new PATCH/DELETE /v1/feedback/:id endpoints.
• 616fe8a: Add releases admin source stuck — lists sources that chronically fail to fetch (pause candidates) by reading the fetch-log error streak. Supports --window, --min-attempts, --include-paused, --limit, --page, and --json.
• f38f166: Add releases admin work start <batch> / status / end and a sticky run-dir pointer for the maintenance workspace. RELEASES_RUN_DIR auto-captures admin mutations into mutations.jsonl and defaults the managed-session trace dir, but a one-time export doesn't survive an agent harness (each shell is fresh), so logging silently stopped after the first command. work start creates ~/.releases/work/runs/<ts>-<batch>/ (honoring RELEASES_DATA_DIR) and writes a sticky ~/.releases/work/.current-run pointer; the CLI now resolves the active run as RELEASES_RUN_DIR env → .current-run pointer → none, so mutation logging and the trace-dir default work across separate invocations with no env threading. Explicit RELEASES_RUN_DIR still wins. work status prints the run dir, where it came from, and a mutations/sessions tally; work end clears the pointer.

Patch Changes

• 3f70b35: releases admin overview update now always HTML-entity-decodes the content body before uploading. The five entities sub-agents reflexively over-escape when relaying markdown (&, <, >, ", ' — e.g. Q&A, streams.input<T>) are a transport artifact, not authored content, and the API stores the body verbatim — so an un-decoded entity rendered wrong. The decode is single-pass and idempotent, so an already-clean body (including one a caller pre-decoded to compute citation offsets) is unchanged. --unescape-html is now the default and kept as an accepted no-op flag for back-compat.
• dc7c707: releases admin overview get now surfaces inline citations. The table line includes a citation count alongside the release count, and --json adds citationCount plus the full citations array. The org overview GET already returns citations ordered by character position — this exposes them so a post-write overview get can verify what overview update reported (which echoes citations: N) without a re-write.
• b9df70e: Reconcile the reader-facing skills (releases-mcp, releases-cli, analyzing-releases) with the live API surface. Removed references to tools/commands that don't exist (summarize_changes, compare_products, get_source_changelog, manage_*, releases summary/compare) and the deprecated list_sources/list_products/search_releases shims; documented the collections trio, lookup_domain, agent-context, and since/until time windows; and clarified that summarize/compare are agent-synthesized. Moved finding-changelogs to the operator (releases-admin) plugin since it's a key-gated curation workflow.

Minor Changes

• dc6ae62: Rework search / tail/latest human output and slim the default --json.

  The human view for search and tail/latest is now a single column-aligned row per release (identity · description · relative age · dimmed rel_…); search adds a cleaned, markdown-stripped excerpt under each hit instead of dumping raw markdown. The piped (non-TTY) TSV path is fixed to one clean row per release.

  --json now returns a lean release shape by default for get / search / tail/latest (id, version, title, summary, excerpt, url, publishedAt, nested source/org, contentChars, contentTokens); pass --full to recover the complete payload (content, contentHash, versionSort, composition, the title* variants, …). Scripts that read dropped fields should add --full.

Patch Changes

• c5ece26: Refine the release reader output: clearer ownership, shorter labels, human dates.
  • search release hits now lead with the owning org as Org/Source (e.g. Axiom/Changelog) so it's clear who ships each result. The org prefix is skipped when the source name already starts with the org name (Railway Changelog stays as-is rather than becoming Railway/Railway Changelog). Feed views (get entity cards, scoped tail) are unchanged — the org is already established there.
  • The release detail cards (get <rel_…> and release get) now show an Org: line so the owning company is named even when the source is generic (e.g. an "API Release Notes" source under Google).
  • get / release get print the publish date as Jul 22, 2024 instead of the raw ISO timestamp. --json still emits ISO publishedAt for machine consumers.
  • Trimmed the AI-attribution labels on the get card to AI summary / AI headline, and dropped the redundant Release heading above the title.

Minor Changes

• 4a72ff1: Add releases feedback to send feedback about the CLI (arg, stdin, or interactive; --contact, --type, --json, --dry-run), and releases admin feedback list to review submissions.
• 62f7f78: Add --since / --until time-window filters to releases search and releases tail|latest. Each accepts an ISO date (2026-01-01) or relative shorthand (90d, 4w, 6m, 2y) and filters releases by publish date, composing with the existing filters. Enables capability-discovery queries like releases search "slack integration" --since 90d.

Minor Changes

• cf83217: Standardize environment variables on the RELEASES_ prefix (RELEASES_API_KEY, RELEASES_API_URL, RELEASES_DATA_DIR, RELEASES_TELEMETRY_DISABLED, RELEASES_DISCOVERY_ENGINE, RELEASES_CLIENT_*, RELEASES_INSTALL_DIR). Legacy RELEASED_-prefixed names still work but now emit a one-time deprecation warning and will be removed in a future release.