weread-omni: an unofficial WeRead toolkit with 40 operations, an agent skill and a CLI

The gap weread-omni is built to fill

WeRead's own Agent Skill, opened in May 2026, hands an agent six read-only abilities behind an API key: shelf lookup, book search, reading statistics, book details, highlights, and recommendations. weread-omni covers all six and then goes after the operations the official skill leaves closed. The README's comparison table lists four: creating, editing and deleting your own highlights and reviews; importing EPUB, PDF, MOBI, TXT and AZW3 files; reading public accounts and their articles; and calling WeRead's AI.

The intended user is someone building on top of a personal WeRead account rather than a corporate integration. The package ships a CLI where every command can emit JSON, a TypeScript SDK with published types, and an agent skill in the repository. The README is explicit that all 40 operations come from one implementation and the three entry points share it, which matters if you plan to prototype in the terminal and then move the same calls into code. It is also explicit that this is unofficial: the project states it has no affiliation with Tencent or WeRead and is neither endorsed nor supported by them.

One operation set, three surfaces, and a local content library

The architecture visible in the repository is a single core with three front ends. The package exports three entry points from package.json: the root module, ./cli, and ./plugin, with types generated alongside each. The bin field maps the weread-omni command to ./dist/cli.js. The CLI is the reference surface; the SDK exposes the same operations with types; the skill in the skills directory tells an agent how to drive the JSON CLI, how to page through results, and when to ask you before a write.

Sitting under all of this is a local content library. The CLI stores book information, tables of contents and downloaded public account articles on disk, and serves repeat reads from that copy instead of refetching. The README describes it as indexed per account, deduplicating identical files, and never cleaning up old content automatically. Content lives by default under $XDG_DATA_HOME/weread/library, falling back to ~/.local/share/weread/library, and WEREAD_LIBRARY_DIR relocates it. That store depends on SQLite WAL; when the filesystem does not support it, the README says the CLI warns and continues without the library rather than failing. There is an escape hatch, WEREAD_LIBRARY_ALLOW_UNSAFE=1, to skip the single-writer check when you know only one process is writing. The README also notes the library holds reading content in plaintext. It contains no login information, but the project tells you to treat it as sensitive anyway. That is an honest warning and a real operational cost: a cache of book text and article bodies on your machine is a different asset from a token file.

Installing weread-omni and running a first search

The README requires Node.js >=22.13.0 and a WeChat account with WeRead enabled. Installation is a global npm install, followed by a QR login and a health check.

npm install --global weread-omni
weread-omni login --json
weread-omni doctor --json
weread-omni search books "三体" --json

weread-omni login shows a QR code to scan with your WeRead account. The README states the JSON returned on success contains only the account alias, client ID, vid and device ID, and no tokens. weread-omni doctor verifies the current install and login state and makes one read-only request to confirm the connection works. If doctor fails, the connection is the thing to look at first, not your command syntax.

There is a naming detail worth knowing before you upgrade. Version 0.1.0 installed a command called weread, which collided with the official skill's command name, so from 0.1.1 the command is weread-omni. Upgrading does not remove the old weread binary; if you installed 0.1.0, the README says to reinstall once.

The agent skill is installed separately and does not install the CLI. It assumes the command is already installed and logged in.

npx skills add teng-lin/weread-omni --skill weread
npx skills add teng-lin/weread-omni --skill weread --global --agent codex --agent claude-code --yes

The first form installs into the project, the second globally for Codex and Claude Code. npx skills list and npx skills update weread inspect and refresh it, with --global added when the install was global.

Public accounts, feeds and the boundary the project will not cross

The public account feature is the part with no official equivalent, and it is also the part where the README draws its clearest line. Subscribing starts with a search that must be scoped to public accounts, because the account ID format matters.

weread-omni search books "公众号名称" --scope 2 --json
weread-omni public-accounts subscribe MP_WXS_1234567890 --json
weread-omni public-accounts articles MP_WXS_1234567890 --count 20 --json

Search with --scope 2 to find the exact MP_WXS_<digits> identifier, then subscribe with it. The articles command pages through a subscription and accepts --synckey for incremental refresh, which cannot be combined with --offset. From there, feed and export write files rather than printing to stdout:

weread-omni public-accounts feed MP_WXS_1234567890 --format json --out ./account.feed.json --limit 50 --json
weread-omni public-accounts feed subscriptions --format rss --out ./subscriptions.xml --limit 50 --json
weread-omni public-accounts export MP_WXS_1234567890 --out ./account-archive --limit 100 --json

Feed supports rss, atom and json output, and passing subscriptions instead of an account ID builds a feed across everything you follow. Both feed and export default to 20 articles, and --limit caps at 100. Neither overwrites an existing file or directory, so a repeat run against the same path fails rather than clobbering your archive.

The constraint that shapes what this feature is good for: article bodies are downloaded only from validated HTTPS mp.weixin.qq.com/s addresses. When a page presents JavaScript verification or a captcha, the README says the situation is recorded in diagnostics and no attempt is made to bypass it. That is the right call, and it also means an archive run can silently come back short. Check the diagnostics rather than assuming --limit was honored.

Where weread-omni breaks down or is the wrong choice

The project is unofficial, and that is a maintenance property, not a disclaimer. Every write operation (shelf pin, set-private, mark-finished, review add, notes add-bookmark) depends on endpoints the project reverse-engineered. The official skill's six read operations have a documented contract behind them; these do not. If WeRead changes a response shape, the failure lands on the write path first, and the README offers no rollback story for a write that half-succeeded.

Multi-account work has sharp edges. Account aliases must start with a lowercase letter or digit, may continue with lowercase letters, digits, hyphens and underscores, and cap at 64 characters. When no --account is passed, the resolution order is: use the only account if there is one; otherwise read WEREAD_ACCOUNT; otherwise fall back to the default recorded by weread-omni accounts use <alias>. If neither is set, an interactive terminal prompts, and a non-interactive command simply fails. Any cron job or CI step that forgets --account will behave differently depending on whether a human is attached to the terminal, which is exactly the class of bug that shows up in production and not in testing.

The local library is another place to think before adopting. It is plaintext, it grows without bound, and it is never pruned automatically. On a filesystem without SQLite WAL support, the CLI warns and quietly stops using the library, so caching behavior differs between machines running the same command. And the import path has a ceiling: single files default to no more than 200 MiB, adjustable through WEREAD_MAX_UPLOAD_BYTES. If your use case is a supported, contractual integration with WeRead, this is not the tool, and no amount of feature coverage changes that.

How this differs from the official WeRead Agent Skill

The obvious alternative is the official skill itself, and the difference is not a matter of polish. The official skill is read-only and keyed to an API key: shelf, search, statistics, book details, highlights, recommendations. It cannot write, cannot import, cannot read public accounts, and cannot call WeRead AI. Its advantage is that it is the vendor's own surface, so its behavior is the vendor's problem to keep stable.

weread-omni inverts the trade. It adds write access to your own highlights, reviews and shelf state, plus book import, public account feeds and the AI commands, at the cost of depending on undocumented endpoints and requiring a QR login tied to a real WeChat account rather than an API key. The login model follows from that: credentials sit under ~/.config/weread/accounts/<alias>/ with directory permissions 0700 and file permissions 0600, relocatable via WEREAD_CONFIG_DIR, and the login JSON is designed to carry no tokens. If you only need the six official capabilities and you value a supported contract, the official skill is the simpler answer. If you need to write a highlight from a script or mirror a public account into RSS, there is no official path, and that is the whole reason this package exists.

Licence, upgrade cost and what to check before committing

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are preserved. That covers the code. It does not cover WeRead's service, your account, or the content you pull through the tool, and the README's own framing (unofficial, unaffiliated, unsupported) is the relevant context for anyone weighing the risk. This is not legal advice; if you are shipping something commercial on top of it, the licence of the package is the easy question and the terms of the service you are calling are the hard one.

Upgrade cost is low but not zero. The package is at 0.1.2 in package.json, with v0.1.1 published on 2026-08-03 and the last push to main on 2026-09-05. The 0.1.0 to 0.1.1 rename is the pattern to expect: a command name changed, the old binary was left in place rather than removed, and the fix was a reinstall. Anything scripted against the CLI should pin a version and read CHANGELOG.md before moving. The skill is versioned separately through npx skills update weread, so a CLI upgrade and a skill upgrade are two operations, not one.

Editorial conclusion

Adopt weread-omni if you want scriptable access to WeRead shelf state, highlights, public account feeds or book imports, and you are comfortable running an unofficial client against your own account. Do not adopt it if you need a supported integration, a guarantee that write commands will keep working after WeRead changes its backend, or an agent that can act without confirmation. Before wiring it into anything automated, run weread-omni doctor to confirm login and connectivity, check weread-omni library path to see where downloaded article text lands on disk, and read the weread-omni <command> --help output for the write commands you intend to call, because the README states that each subcommand's defaults and ranges are defined there and not in the table.

Frequently asked questions

Official sources

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