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 setreadonlytrue# 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 setreadonlytrue
readwise --refresh # re-fetch tool cache with annotations
readwise --help # only read-only commands shownTo restore full access:
readwise config setreadonlyfalse
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.