supsub-search

supsub-search Skill

Full search: search across sources (official accounts, websites) and article bodies at the same time; you can narrow the scope by type.

First determine the scope: site-wide search vs the user's own subscriptions

Given a term X,look at the verb, not at whether X looks like a proper noun：

What the user says	Intent	Which path
"search for X", "look up articles related to X", "full-text search X"	Retrieval	This skill(site-wide)
"look at recent content about X", "what's new with X", "has X updated", "read X"	Browse the content stream of a certain subject	First compare against the subscription scope(see below)
"my subscriptions / my official accounts / my websites"	Already limited to the user's own scope	`supsub-sub`
"my interests"	Already limited to the user's own scope	`supsub-focus`

Steps for handling browse intent:

supsub sub list -o json + supsub focus list -o json；
Compare X with name / title usingcontains matching (case-insensitive)；
Matches a subscription source → supsub sub contents --source-id <sid> --type <t>; matches an interest → supsub focus contents --id <fid>；if both match, list both and let the user choose(the same term is very likely both a source name and an interest topic);
after a match, add "you can also search site-wide for articles related to X"; don't hide the global search path;
if nothing matches → directly execute supsub search <X> site-wide search; do not ask back "do you want me to search for you". The user's browse intent has not changed; it's just that this term is not in their subscriptions. The correct approach is to search first and then explain "you don't have a source subscribed called X; the following are site-wide results".

Lesson from actual testing: "look at recent content about Anthropic" was once sent directly into site-wide search, returning a bunch of third-party commentary articles, while the user's own subscribed Anthropic official blog source and the "Anthropic company updates and AI frontier progress" interest were completely bypassed. When the user mentions a certain subject name,the one they themselves subscribed to takes priority。

Prerequisites

Install:curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash(native install, installed to ~/.local, supports automatic background updates); or package manager npm i -g @supsub/cli / pnpm add -g @supsub/cli
Already logged in:supsub auth status shows Authenticated (on first use, first supsub auth login）
When unauthorized (exit 2 / UNAUTHORIZED), do not stop at "you are not logged in": directly run supsub auth login to open browser authorization for the user (the command will automatically open the browser and block waiting for authorization; please use a sufficiently long timeout, such as 10 minutes; the user only needs to click confirm in the browser and does not need to enter anything in the terminal). After successful authorization, retry the original command. In a browserless / headless environment, fall back to prompting the user SUPSUB_NO_BROWSER=1 supsub auth login。

Commands

Search

supsub search <keyword> [--type <ALL|MP|WEBSITE|CONTENT>]

Flag	Default	Description
`--type`	`ALL`	Search scope:`ALL`(sources + articles) / `MP`(official account sources) / `WEBSITE`(website sources) / `CONTENT`(article bodies)

<keyword> is a positional argument, which can be in Chinese or English. It is recommended to wrap it in quotes to avoid shell splitting.

# 全量搜索（默认 ALL：同时搜源 + 文章）
supsub search "RAG"

# 只搜公众号
supsub search "阮一峰" --type MP

# 只搜网站
supsub search "hacker news" --type WEBSITE

# 只搜文章正文
supsub search "向量数据库" --type CONTENT

# JSON
supsub search "MCP 协议" -o json

JSON shape: {"success":true,"data":{"results":[...],"recommendations":[...],"prompts":[...]}}

results is a heterogeneous array, each item shaped like:

// 源结果（type=MP 或 WEBSITE 时）
{ "type": "SOURCE", "data": { "sourceType": "MP", "sourceId": 12345, "isSubscribed": false, "img": "...", "name": "...", "description": "...", "introduction": "...", "url": "..." } }

// 文章结果（type=CONTENT 时）
{ "type": "CONTENT", "data": { "contentId": "...", "title": "...", "summary": "...", "url": "...", "coverImage": "...", "publishedAt": 1700000000, "publishedAtText": "2026-01-16 07:30", "sourceId": 12345, "sourceName": "...", "sourceType": "MP", "isSubscribed": false, "keywords": [...], "tags": [...] } }

recommendations is the related source recommended by the backend (SourceBasic[]），prompts is the search suggestion term provided by the backend.

For article results, the publishedAtText（"YYYY-MM-DD HH:mm") is filled in by the CLI,just use it directly for sorting/display, do not convert it yourself to publishedAt this Unix second(the original field is kept only for convenient numeric sorting).SOURCE Results do not have a publish time and do not include this field.

Agent Usage Notes

When parsing structured results, always use -o json：results[] is a {type, data} union type, first check type then access the data field.
--type ALL(default) returns a mix of sources + articles together; when you want precise control over the result type, explicitly specify MP / WEBSITE / CONTENT。
Typical search + subscribe flow:supsub search "<词>" --type MP -o json → get data.results[].data.sourceId → supsub sub add --source-id <id> --type MP(refer to supsub-sub skill）。
Search articles to get the full text:supsub search "<词>" --type CONTENT -o json get contentId and sourceId, currently the CLI does not have a "get article details by contentId" command, you need to use supsub sub contents --source-id <id> --type <T> to browse within that source.
data.results[].data.isSubscribed The field can determine whether the current result is already subscribed, avoiding duplicate sub add。
The CLI returns at most 10 results at a time (backend default pageSize=10), and does not support pagination; if you want more results, adjust the keywords to narrow or broaden the search scope.
Exit codes：0 OK，1 business error (backend 4xx),2 UNAUTHORIZED，64 INVALID_ARGS（--type when not in the allowlist),10 network error,11 server error (5xx).