bestblogs-discover

bestblogs-discover — Discover (Today / Personalized / Following Feed / Trending / Search / Weekly)

When to Use

• The user wants to quickly learn "the most worthwhile content to read today" (the most important trigger).
• The user wants to find BestBlogs picks for a certain topic, author, or content type.
• The user wants to browse the weekly.

Primitives

Primitive	CLI	Description
bestblogs.discover.today	bestblogs discover today --json	Today's candidates with multi-source fallback chain
bestblogs.discover.for_you	bestblogs discover for-you --json	Personalized recommendations (requires Pro)
bestblogs.discover.following	bestblogs discover following --json	Following feed
bestblogs.discover.trending	bestblogs discover trending --period week --json	Trending content (today / week / month)
bestblogs.discover.search	bestblogs discover search "<q>" --json	Keyword search
bestblogs.discover.newsletter.list	bestblogs discover newsletters --json	Weekly list
bestblogs.discover.newsletter.get	bestblogs discover newsletter <id> --json	Single issue of the weekly

Pre-checks

bestblogs auth status --json

Most commands require an API Key;search、newsletters in some configurations, it can also be consumed anonymously. If not logged in, prompt to first bestblogs auth login。

Core action: discover today

bestblogs discover today --limit 20 --json

Returns:

{
  "success": true,
  "data": {
    "candidates": [
      {
        "resourceId": "RAW_xxx",
        "title": "...",
        "url": "...",
        "resourceType": "ARTICLE",
        "language": "en_US",
        "score": 92,
        "sourceName": "...",
        "candidateSource": "my_brief",
        "selectionReason": "今日个性化精选",
        "fallbackApplied": false,
        "personalized": true
      }
    ],
    "primarySource": "my_brief",
    "fallbackApplied": false,
    "details": { "triedSources": ["my_brief", "for_you"] }
  }
}

candidateSource enum：

• my_brief — Pro personalized morning brief
• public_brief — Public picks (when not Pro or when personalization has not been generated)
• public_brief_fallback — Public morning brief degraded fallback
• for_you — For You recommendations
• following — Following feed

When displaying to the user, a badge should be shown according to candidateSource, and the degraded state should be explicitly indicated (whenfallbackApplied=true ).

Other Actions

# 个性化流
bestblogs discover for-you --limit 15 --lang en_US --json

# 热趋（今日 / 本周 / 本月）
bestblogs discover trending --period week --limit 20 --json
bestblogs discover trending --period today --lang zh_CN --json

# 搜索
bestblogs discover search "AI coding" --type ARTICLE --sort score --limit 10 --json

# 周刊
bestblogs discover newsletters --limit 10 --json
bestblogs discover newsletter <id> --json

Error Handling

• 403 / FORBIDDEN on for-you → The user is not Pro, degrade to following or today
• 404 / NOT_FOUND on brief related → Today's morning brief has not yet been generated, try public_brief or following
• 429 / RATE_LIMITED → The CLI has already backed off once; if it still fails, exit and tell the user to retry later
• Empty candidates → Report to the user "no recommendations today" and suggest doing bestblogs intake setup to build/fix the profile

Combination Suggestions

• After getting candidates, chain-call bestblogs-read skill for in-depth reading on items of interest
• Chain-call bestblogs-capture skill for high-value items to bookmark/add notes
• Want to know "why this was recommended"? Display candidateSource / selectionReason directly; for deeper explanations (such as the scores of contributing sources), use bestblogs-explain skill