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.