WeRead

The local weread CLI is the only interface you need. It handles authentication, request shape, skill_version, JSON parsing, upgrade checks, and normalized errors — writing ad hoc curl requests would mean reimplementing all of that and losing the normalized error layer.

Agents should use --json by default. Use human-readable output only when the user explicitly wants terminal-readable command output.

For large outputs such as shelf, notebooks, bookmarks, or exports, write JSON or Markdown to a file first, then summarize the result in chat. Do not paste full large JSON payloads or full exported notes into the conversation.

For notes export, use --output <path> by default. Only stream the export to stdout when the user explicitly asks to see the full export inline.

First Decision

Before any WeRead work, check auth and CLI health:

weread doctor

If the weread command is missing, or if auth_configured is false, read references/first-use.md and guide the user through setup.

Command Map

weread search "三体" --scope book --count 10
weread book resolve "三体" --limit 5
weread book info <bookId>
weread book chapters <bookId>
weread book progress <bookId>
weread shelf list
weread shelf recent --limit 10
weread readdata detail --mode monthly
weread readdata summary --mode monthly
weread notes notebooks --count 100
weread notes top --limit 20
weread notes bookmarks <bookId>
weread notes export <bookId> --format markdown --output notes.md
weread notes mine <bookId> --count 20
weread notes underlines <bookId> <chapterUid>
weread notes best <bookId> --chapter-uid <chapterUid>
weread notes readreviews <bookId> <chapterUid> --reviews-json '[{"range":"900-2004","count":20}]'
weread reviews list <bookId> --type 1 --count 20
weread reviews single <reviewId>
weread discover recommend --count 12
weread discover similar <bookId> --count 12
weread discover friends --count 20
weread api list

When a supported API isn't covered by a first-class command, use the raw escape hatch:

weread api call /store/search --param keyword=三体 --param scope=10

When To Read References

References are loaded on demand to keep startup context lean. Load them only when the task requires it:

• First-time setup, missing auth, or API Key questions: read references/first-use.md
• Shelf totals, public/private counts, audiobook or article-collection handling: read references/domain-rules.md
• Notes, highlights, bookmarks, personal ideas, public reviews, or exports: read references/domain-rules.md
• Reading statistics, historical periods, cross-year ranges, or time-unit interpretation: read references/domain-rules.md
• Deep links to books, chapters, highlights, or ideas: read references/domain-rules.md

Intent Routing

Search

• Find a book, get a bookId, or user says 搜书/找书: weread search "<keyword>" --scope book
• Generic 搜一下 or mixed intent: --scope all
• Web fiction or 网文: --scope fiction
• Audiobooks, podcasts, 听书, 有声书, or 专辑: --scope audio
• Authors: --scope author
• Full-text search or 书里提到: --scope fulltext
• Book lists: --scope list
• Official accounts: --scope mp
• Articles: --scope article

Book Details

If the user gives a title rather than an ID, prefer weread --json book resolve "<title>" --limit 5 and use items[].bookId.

• Metadata: book info
• Chapter UIDs (needed for notes/highlights by chapter): book chapters
• Reading progress: book progress — progress is an integer percent; 1 means 1%, only 100 means finished

Shelf

Use weread --json shelf list. For recent reading, use weread --json shelf recent --limit 10. For anything nuanced (public/private split, audiobook handling), read references/domain-rules.md.

Reading Statistics

Use weread --json readdata summary --mode monthly for common summaries, or weread --json readdata detail with --mode weekly, monthly, annually, or overall. Time fields in structured output are seconds. For historical or cross-period calculations, read references/domain-rules.md.

Notes and Highlights

• Overview across all books: weread --json notes notebooks
• Books with the most personal notes/highlights: weread --json notes top --limit 20
• Single-book export: weread notes export <bookId> --format markdown --output <path>; choose a local Markdown path and summarize counts/content instead of pasting the whole file
• If manually combining data, use both weread --json notes bookmarks <bookId> and weread --json notes mine <bookId>
• For counting rules, export limits, or popular highlight queries, read references/domain-rules.md

Reviews

Public reviews: weread --json reviews list <bookId> with --type 0 (all) through --type 4. Single review: weread --json reviews single <reviewId>.

Recommendations

• Personalized: weread --json discover recommend
• Similar books: weread --json discover similar <bookId>
• Friends' reading activity: weread --json discover friends; continue with nextMaxIdx as --max-idx and reuse synckey for refreshes

Pagination

Stay shallow by default — only paginate further when the user explicitly asks for a complete export, a ranking, or a total that requires all pages. Use --limit for display size and --all where supported. For manual pagination, use --json and pass the native cursor from the previous JSON result:

• Search: hasMore == 1 → pass last item searchIdx as --max-idx
• Notebooks: hasMore == 1 → pass last books[].sort as --last-sort
• Reviews: pass last review idx as --max-idx and returned synckey as --synckey
• Similar: pass last item idx as --max-idx and booksimilar.sessionId as --session-id
• Friends' activity: pass nextMaxIdx as --max-idx; reuse the returned synckey when refreshing the feed

Error Handling

The CLI normalizes errors to JSON:

{
  "ok": false,
  "skill_version": "1.0.4",
  "error": {
    "type": "missing_auth",
    "message": "..."
  }
}

• missing_auth: read references/first-use.md and help configure the key
• upgrade_required: stop immediately and follow upgrade_info.message; don't continue the original task until upgraded
• upstream_timeout, network_error: these are retryable; the CLI already retries transient failures before returning the error
• api_error, http_error, invalid_json: report the failure; retry only when repeating is safe

User-Facing Output

• Default to --json; use --compact when a command returns too much metadata for the task
• Convert Unix timestamps to readable dates
• Convert seconds to hours and minutes
• Use numbered lists for search results, shelf entries, notes, reviews, and recommendations
• Include WeRead deep links when useful; format rules are in references/domain-rules.md