A command-line interface for Readwise and Reader. Search your documents & highlights, manage your reading list, tag and organize documents — all from the terminal.
Anything you can do in Readwise/Reader, your agent can now do for you.
npm install -g @readwise/cliIf you installed the CLI globally with npm, upgrade to the latest published version with:
npm install -g @readwise/cli@latest
readwise --versionIf the version did not change, confirm which binary your shell is using:
which readwise
npm list -g @readwise/cli --depth=0If you run the CLI with npx, request the latest package explicitly:
npx @readwise/cli@latest --versionreadwise loginGet your token from readwise.io/access_token, then:
readwise login-with-token
# prompts for token (hidden input, not stored in shell history)You can also pipe the token in:
echo "$READWISE_TOKEN" | readwise login-with-tokenCredentials are stored in ~/.readwise-cli.json. OAuth tokens refresh automatically.
Run readwise --help to see all available commands, or readwise <command> --help for details on a specific command.
readwise reader-search-documents --query "machine learning"
readwise reader-search-documents --query "react" --category-in article
readwise reader-search-documents --query "notes" --location-in shortlist --limit 5
readwise reader-search-documents --query "physics" --published-date-gt 2024-01-01readwise readwise-search-highlights --vector-search-term "spaced repetition"readwise reader-list-documents --limit 5
readwise reader-list-documents --category article --location later
readwise reader-list-documents --tag "to-review"
readwise reader-get-document-details --document-id <document-id>
readwise reader-get-document-highlights --document-id <document-id>Tip: seen vs unseen documents. In the response,
firstOpenedAt: nullmeans the document is unseen (never opened). A non-nullfirstOpenedAtmeans it has been opened/seen. Usereader-bulk-edit-document-metadata --documents '[{"document_id":"<id>","seen":true}]'to mark a document as seen.
readwise reader-create-document --url "https://example.com/article"
readwise reader-create-document \
--url "https://example.com" \
--title "My Article" \
--tags "reading-list,research" \
--notes "Found via HN"# Tags
readwise reader-list-tags
readwise reader-add-tags-to-document --document-id <id> --tag-names "important,review"
readwise reader-remove-tags-from-document --document-id <id> --tag-names "old-tag"
# Move between locations (new/later/shortlist/archive)
readwise reader-move-documents --document-ids <id> --location archive
# Edit metadata
readwise reader-bulk-edit-document-metadata --documents '[{"document_id":"<id>","title":"Better Title"}]'
readwise reader-bulk-edit-document-metadata --documents '[{"document_id":"<id>","seen":true}]'
readwise reader-bulk-edit-document-metadata --documents '[{"document_id":"<id>","notes":"Updated notes"}]'readwise reader-add-tags-to-highlight --document-id <id> --highlight-document-id <id> --tag-names "key-insight"
readwise reader-remove-tags-from-highlight --document-id <id> --highlight-document-id <id> --tag-names "old-tag"
readwise reader-set-highlight-notes --document-id <id> --highlight-document-id <id> --notes "This connects to..."readwise reader-export-documents
readwise reader-export-documents --since-updated "2024-06-01T00:00:00Z"| Flag | Description |
|---|---|
--json |
Output raw JSON (for piping to jq, scripts, etc.) |
--refresh |
Force-refresh the command list from the server |
--help |
Show all commands or command-specific options |
Manage CLI settings with the config command. Settings are stored in ~/.readwise-cli.json under the config key.
readwise config show # show all settings with current values
readwise config get readonly # get a single setting
readwise config set readonly true # set a settingWhen readonly is enabled, only read-only tools (search, list, get) are available — write operations (create, move, tag, edit) are hidden from commands and the TUI. This is useful for agents or scripts that should never modify your library.
readwise config set readonly true
readwise --refresh # re-fetch tool cache with annotations
readwise --help # only read-only commands shownTo restore full access:
readwise config set readonly false
readwise login # re-authentication requiredNote: Disabling readonly via the CLI logs you out and requires re-authentication. This prevents an AI agent from silently toggling readonly off and using write tools. The TUI settings screen is not affected — toggling readonly there does not require re-login.
Pipe results to jq:
readwise reader-list-documents --limit 3 --json | jq '.results[].title'Pre-built workflows your AI agent can run. Install them with one command:
readwise skills install claude # or codex, opencode
readwise skills list # see all available skillsBrowse and contribute skills at github.com/readwiseio/readwise-skills.
Using Claude Desktop, ChatGPT, or another AI app? Connect Readwise via MCP — no terminal needed. Set up Readwise MCP →
The CLI connects to the Readwise MCP server internally, auto-discovers available tools, and exposes each one as a CLI command. The tool list is cached locally for 24 hours.
git clone https://github.com/readwise/readwise-cli && cd readwise-cli
npm install
npm run build
# Run without building
npx tsx src/index.ts --help
# Point the CLI at a local MCP server
READWISE_MCP_URL=http://localhost:8103/mcp npx tsx src/index.ts --refresh --helpMerging a feature PR does not publish it to users. Users receive CLI changes only after a new npm version is published by the Publish npm package GitHub Action.
To ship a release:
- Bump
package.jsonandpackage-lock.jsonto the next version in a release PR. - Merge the release PR to
master. - Create and publish a GitHub Release whose tag exactly matches the package version with a leading
v, for examplev0.5.8. - Wait for the
Publish npm packageaction to complete. It builds the CLI, checks that the release tag matchespackage.json, verifies the lockfile versions, and publishes to npm through trusted publishing. - Confirm npm shows the new version:
npm view @readwise/cli versionIf a version is prepared but never published, skip it and bump to the next version. npm versions do not need to be contiguous.