{"id":47817913,"url":"https://github.com/readwiseio/readwise-cli","last_synced_at":"2026-06-16T03:04:27.774Z","repository":{"id":339267107,"uuid":"1153715846","full_name":"readwiseio/readwise-cli","owner":"readwiseio","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-16T22:54:14.000Z","size":213,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-17T09:17:35.788Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readwiseio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T16:04:18.000Z","updated_at":"2026-03-16T22:54:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/readwiseio/readwise-cli","commit_stats":null,"previous_names":["readwiseio/readwise-cli"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/readwiseio/readwise-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readwiseio%2Freadwise-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readwiseio%2Freadwise-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readwiseio%2Freadwise-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readwiseio%2Freadwise-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readwiseio","download_url":"https://codeload.github.com/readwiseio/readwise-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readwiseio%2Freadwise-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34388676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T18:51:45.164Z","updated_at":"2026-06-16T03:04:27.768Z","avatar_url":"https://github.com/readwiseio.png","language":"TypeScript","funding_links":[],"categories":["AI - Agent Skills, MCP, and CLI","Productivity and Workspace"],"sub_categories":["CLI"],"readme":"# The Official Readwise CLI\n\nA command-line interface for [Readwise](https://readwise.io) and [Reader](https://read.readwise.io). Search your documents \u0026 highlights, manage your reading list, tag and organize documents — all from the terminal.\n\nAnything you can do in Readwise/Reader, your agent can now do for you.\n\n## Install\n\n```bash\nnpm install -g @readwise/cli\n```\n\n## Setup\n\n### Interactive login (opens browser)\n\n```bash\nreadwise login\n```\n\n### Access token login (for separate hosts like OpenClaw, or scripts)\n\nGet your token from [readwise.io/access_token](https://readwise.io/access_token), then:\n\n```bash\nreadwise login-with-token\n# prompts for token (hidden input, not stored in shell history)\n```\n\nYou can also pipe the token in:\n\n```bash\necho \"$READWISE_TOKEN\" | readwise login-with-token\n```\n\nCredentials are stored in `~/.readwise-cli.json`. OAuth tokens refresh automatically.\n\n## Commands\n\nRun `readwise --help` to see all available commands, or `readwise \u003ccommand\u003e --help` for details on a specific command.\n\n### Search documents\n\n```bash\nreadwise reader-search-documents --query \"machine learning\"\nreadwise reader-search-documents --query \"react\" --category-in article\nreadwise reader-search-documents --query \"notes\" --location-in shortlist --limit 5\nreadwise reader-search-documents --query \"physics\" --published-date-gt 2024-01-01\n```\n\n### Search highlights\n\n```bash\nreadwise readwise-search-highlights --vector-search-term \"spaced repetition\"\n```\n\n### List and inspect documents\n\n```bash\nreadwise reader-list-documents --limit 5\nreadwise reader-list-documents --category article --location later\nreadwise reader-list-documents --tag \"to-review\"\nreadwise reader-get-document-details --document-id \u003cdocument-id\u003e\nreadwise reader-get-document-highlights --document-id \u003cdocument-id\u003e\n```\n\n\u003e **Tip: seen vs unseen documents.** In the response, `firstOpenedAt: null` means the document is **unseen** (never opened). A non-null `firstOpenedAt` means it has been opened/seen. Use `reader-bulk-edit-document-metadata --documents '[{\"document_id\":\"\u003cid\u003e\",\"seen\":true}]'` to mark a document as seen.\n\n### Save a document\n\n```bash\nreadwise reader-create-document --url \"https://example.com/article\"\nreadwise reader-create-document \\\n  --url \"https://example.com\" \\\n  --title \"My Article\" \\\n  --tags \"reading-list,research\" \\\n  --notes \"Found via HN\"\n```\n\n### Organize\n\n```bash\n# Tags\nreadwise reader-list-tags\nreadwise reader-add-tags-to-document --document-id \u003cid\u003e --tag-names \"important,review\"\nreadwise reader-remove-tags-from-document --document-id \u003cid\u003e --tag-names \"old-tag\"\n\n# Move between locations (new/later/shortlist/archive)\nreadwise reader-move-documents --document-ids \u003cid\u003e --location archive\n\n# Edit metadata\nreadwise reader-bulk-edit-document-metadata --documents '[{\"document_id\":\"\u003cid\u003e\",\"title\":\"Better Title\"}]'\nreadwise reader-bulk-edit-document-metadata --documents '[{\"document_id\":\"\u003cid\u003e\",\"seen\":true}]'\nreadwise reader-bulk-edit-document-metadata --documents '[{\"document_id\":\"\u003cid\u003e\",\"notes\":\"Updated notes\"}]'\n```\n\n### Highlight management\n\n```bash\nreadwise reader-add-tags-to-highlight --document-id \u003cid\u003e --highlight-document-id \u003cid\u003e --tag-names \"key-insight\"\nreadwise reader-remove-tags-from-highlight --document-id \u003cid\u003e --highlight-document-id \u003cid\u003e --tag-names \"old-tag\"\nreadwise reader-set-highlight-notes --document-id \u003cid\u003e --highlight-document-id \u003cid\u003e --notes \"This connects to...\"\n```\n\n### Export\n\n```bash\nreadwise reader-export-documents\nreadwise reader-export-documents --since-updated \"2024-06-01T00:00:00Z\"\n```\n\n## Options\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Output raw JSON (for piping to `jq`, scripts, etc.) |\n| `--refresh` | Force-refresh the command list from the server |\n| `--help` | Show all commands or command-specific options |\n\n## Configuration\n\nManage CLI settings with the `config` command. Settings are stored in `~/.readwise-cli.json` under the `config` key.\n\n```bash\nreadwise config show              # show all settings with current values\nreadwise config get readonly      # get a single setting\nreadwise config set readonly true # set a setting\n```\n\n### Readonly mode\n\nWhen `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.\n\n```bash\nreadwise config set readonly true\nreadwise --refresh   # re-fetch tool cache with annotations\nreadwise --help      # only read-only commands shown\n```\n\nTo restore full access:\n\n```bash\nreadwise config set readonly false\nreadwise login   # re-authentication required\n```\n\n\u003e **Note:** 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.\n\n## Examples\n\nPipe results to `jq`:\n\n```bash\nreadwise reader-list-documents --limit 3 --json | jq '.results[].title'\n```\n\n## Skills\n\nPre-built workflows your AI agent can run. Install them with one command:\n\n```bash\nreadwise skills install claude    # or codex, opencode\nreadwise skills list              # see all available skills\n```\n\nBrowse and contribute skills at [github.com/readwiseio/readwise-skills](https://github.com/readwiseio/readwise-skills).\n\n## Looking for MCP?\n\nUsing Claude Desktop, ChatGPT, or another AI app? Connect Readwise via MCP — no terminal needed. [Set up Readwise MCP →](https://readwise.io/mcp)\n\n## How it works\n\nThe CLI connects to the [Readwise MCP server](https://mcp2.readwise.io) internally, auto-discovers available tools, and exposes each one as a CLI command. The tool list is cached locally for 24 hours.\n\n## Development\n\n```bash\ngit clone https://github.com/readwise/readwise-cli \u0026\u0026 cd readwise-cli\nnpm install\nnpm run build\n\n# Run without building\nnpx tsx src/index.ts --help\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadwiseio%2Freadwise-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadwiseio%2Freadwise-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadwiseio%2Freadwise-cli/lists"}