weread-omni: An Unofficial WeRead Toolkit With a CLI, SDK and Agent Skill

What the Official WeRead Skill Leaves Out

WeRead's own Agent Skill, opened in May 2026, exposes six API-key capabilities: shelf lookup, book search, reading statistics, book details, note highlights and recommendations. weread-omni covers all six and adds four areas the README lists as closed in the official skill: creating, editing and deleting your own highlights and reviews; importing EPUB, PDF, MOBI, TXT and AZW3 files; public-account and article access; and the WeRead AI endpoints. The target reader is an engineer wiring WeRead into an agent or a script who has hit the ceiling of read-only access. The project is explicit that it is unofficial, with no affiliation to Tencent or WeRead and no endorsement from either.

One Implementation, Three Entry Points

The README states that the 40 operations have a single implementation shared by three surfaces: the weread-omni command line, which can emit JSON for every command; a TypeScript SDK with full types; and an agent skill shipped inside the repository. That single-implementation claim matters for behaviour drift. When the CLI gains a flag, the SDK and the skill are working against the same code path rather than a reimplementation. The skill itself is not a runtime dependency: the README notes it does not install the weread-omni command, so you complete the npm install and login first, then add the skill. Its job is procedural, telling the agent how to check login state, call the JSON CLI, paginate correctly, and confirm with you before a write.

Login, Doctor and the Account Layout

Node.js 22.13.0 or newer is required, along with a WeChat account that already has WeRead enabled. The documented sequence is npm install --global weread-omni, then weread-omni login --json, then weread-omni doctor --json. The login command prints a QR code to scan once. The README states that the JSON returned after a successful login contains only the account alias, client ID, vid and device ID, with no token included. The doctor command checks the current installation and login state and issues one read-only request to confirm the connection works. Credentials land in ~/.config/weread/accounts/<alias>/ with directory permissions of 0700 and file permissions of 0600, and WEREAD_CONFIG_DIR relocates that tree. Multi-account use is alias-based: the first login without --account becomes default, and weread-omni --account work login adds another. Aliases must start with a lowercase letter or digit, may continue with lowercase letters, digits, hyphens and underscores, and cap at 64 characters. Resolution order when no --account is passed is a single account if only one exists, then WEREAD_ACCOUNT, then the alias saved by weread-omni accounts use. In a non-interactive context with several accounts and no default set, the command fails rather than guessing, which is the correct behaviour for scripts.

Reads, Writes and the Star Scale

Search and reading commands follow a consistent shape: weread-omni search books "三体" --json, book info BOOK_ID, book chapters BOOK_ID, notes bookmarks BOOK_ID, read-data detail --mode annually, discover similar BOOK_ID, and ai ask-book BOOK_ID with a question. The chapters command returns the chapterUid that later commands need, so a bookmark call reads weread-omni notes add-bookmark BOOK_ID CHAPTER_UID "1-20" "要划线的原文" --json. Review posting takes a star argument restricted to 20, 40, 60, 80 or 100, mapping to one through five stars; a value outside that set is not a valid input. Shelf mutations invert their own defaults: shelf pin, set-private, mark-finished and mark-reading apply the state by default, and --no-top, --no-secret, --no-finished or --no-reading undo it. That inversion is worth reading twice before scripting, because the flag names describe the negation, not the action.

Public Accounts Are the Distinctive Surface

Public-account support is where this project diverges most from the official six. The documented flow starts with a scoped search, weread-omni search books "公众号名称" --scope 2 --json, to confirm the exact MP_WXS_<number> identifier before subscribing. From there you can list subscriptions, page through articles with --count, --synckey or --offset, resolve an article link to a WeRead review ID, or attempt paid-content retrieval for articles your account can already access. Export comes in two forms: public-accounts feed writes an RSS, Atom or JSON file with --out and --limit, and public-accounts export writes an article directory. Feed and export default to 20 articles and cap --limit at 100. Neither overwrites existing files or directories. Article bodies are downloaded only from validated HTTPS mp.weixin.qq.com/s addresses, and the README states that JavaScript verification or a captcha is recorded in diagnostics rather than circumvented. That is a deliberate boundary, and it means a blocked article stays blocked.

The Local Library Is Plaintext and Grows

By default the CLI caches book metadata, tables of contents and downloaded public-account articles locally, and reuses the copy on a repeat read. weread-omni library path, library status and library verify inspect it. The location is $XDG_DATA_HOME/weread/library, falling back to ~/.local/share/weread/library, overridable with WEREAD_LIBRARY_DIR. Content is indexed per account, identical files are stored once, and old content is never cleaned up automatically. The README is direct about the security posture: the reading content is stored in plaintext, holds no login information, and should still be treated as sensitive. The library depends on SQLite WAL; on a filesystem that does not support it, the CLI warns and continues without the library rather than failing. WEREAD_LIBRARY_ALLOW_UNSAFE=1 skips the single-writer check, which the README permits only when you have confirmed one writing process. Two flags control the cache per invocation: --refresh re-downloads and updates, --no-library bypasses local content entirely for that command. On a shared or backed-up machine, an unbounded plaintext archive of everything you have read is the part to think about before the first sync.

Import Limits, the Renamed Binary and What to Verify

Book import takes EPUB, PDF, MOBI, TXT and AZW3 through weread-omni import book ./my-book.epub --json, with a default per-file ceiling of 200 MiB that WEREAD_MAX_UPLOAD_BYTES raises. One upgrade detail deserves attention: version 0.1.0 installed a binary named weread, which collided with the official skill's command name, so 0.1.1 renamed it to weread-omni. The README states that upgrading does not remove the old weread binary, so anyone who installed 0.1.0 should reinstall once to clear it. The comparison point is not another third-party client but the official Agent Skill itself: it authenticates with an API key against six documented read capabilities, while weread-omni drives account-scoped endpoints to reach writes, imports and public accounts. That extra reach is the whole value proposition, and it is also the risk, since those endpoints are not a published contract and the project offers no compatibility guarantee for them. The only release listed is v0.1.1, so the surface is young. Verify three things first: that weread-omni doctor reports a healthy connection on your account, that your filesystem supports SQLite WAL if you want the library, and that plaintext article storage under ~/.local/share/weread/library is acceptable where you plan to run it. The MIT licence covers the code; it says nothing about whether automating your own WeRead account fits WeRead's terms, which is a question for you and not for the licence file.

Editorial conclusion

Adopt weread-omni if you are automating WeRead from a script or an agent and need writes the official skill does not expose: adding bookmarks, posting reviews, importing EPUB or PDF files, or pulling public-account articles into an RSS file. Do not adopt it if you need a supported integration, because the README states plainly that it is unofficial and unaffiliated with Tencent, and it carries no compatibility promise for the private endpoints it calls. Before trusting it with a real account, run weread-omni doctor, confirm the config directory is 0700 and the account files are 0600, and decide whether you accept that downloaded article text sits unencrypted under ~/.local/share/weread/library.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. teng-lin/weread-omni on GitHub