Readwise Skill

Use this skill to perform Readwise (highlights/books) and Reader (documents) workflows through readwise-cli.

Prerequisites

1) Ensure readwise-cli is installed

Preferred: install from GitHub Releases of this repository.

# 1) Inspect releases
gh release list -R Leechael/readwise-skills

# 2) Download latest artifacts
gh release download -R Leechael/readwise-skills --pattern 'readwise-cli-*.tar.gz'

# 3) Extract your platform artifact and install binary
tar -xzf readwise-cli-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz
install -m 0755 readwise-cli /usr/local/bin/readwise-cli

Quick check:

readwise-cli --help

2) Configure credentials

Required environment variable:

export READWISE_API_TOKEN="<token>"

Alternatively, pass --token on every invocation.

3) Verify login/config status before operations

Use the built-in status command:

readwise-cli status

If credentials are missing or invalid, this command will fail with guidance. Do not continue with operations until status is successful.

Recommended Credential Management (1Password CLI)

Prefer running readwise-cli with the 1Password CLI (op) so credentials are injected at runtime instead of stored in shell profiles.

Reference:

• https://developer.1password.com/docs/service-accounts/use-with-1password-cli

Example pattern:

op run --env-file=.env -- readwise-cli status
op run --env-file=.env -- readwise-cli highlight list --json

(Your .env should define READWISE_API_TOKEN with a 1Password secret reference.)

Command Mapping

v2 — Highlights & Books

• Check auth: readwise-cli status
• List highlights: readwise-cli highlight list
• Get highlight: readwise-cli highlight get <id>
• Create highlights: readwise-cli highlight create
• Update highlight: readwise-cli highlight update <id>
• Delete highlight: readwise-cli highlight delete <id>
• Highlight tags: readwise-cli highlight tag list|add|update|delete
• List books: readwise-cli book list
• Get book: readwise-cli book get <id>
• Book tags: readwise-cli book tag list|add|update|delete
• Export highlights: readwise-cli export
• Daily review: readwise-cli review

v3 — Reader

• List documents: readwise-cli reader list
• Save document: readwise-cli reader save
• Update document: readwise-cli reader update <id>
• Delete document: readwise-cli reader delete <id>
• List Reader tags: readwise-cli reader tag list

Recommended Workflow

1. Run readwise-cli status first.
2. Prefer read commands first: highlight list, book list, reader list.
3. Use filters to narrow results: --category, --book-id, --updated-after.
4. Pipe JSON output through --jq for scripting: --json --jq '.results[]'.
5. Use write commands when needed: highlight create, reader save.

Usage Examples

1) Check authentication

readwise-cli status
readwise-cli status --json

2) List and filter highlights

readwise-cli highlight list --json
readwise-cli highlight list --book-id 12345 --page-size 10 --json
readwise-cli highlight list --json --jq '.results[] | {id, text}'

3) Get a single highlight

readwise-cli highlight get 67890 --json
readwise-cli highlight get 67890 --plain

4) Create a highlight

readwise-cli highlight create --text "Important quote" --title "Book Title" --author "Author Name" --json
echo '{"highlights":[{"text":"From stdin","title":"Source"}]}' | readwise-cli highlight create --stdin --json

5) Manage highlight tags

readwise-cli highlight tag list 67890 --json
readwise-cli highlight tag add 67890 --name "favorite" --json
readwise-cli highlight tag update 67890 111 --name "must-read"
readwise-cli highlight tag delete 67890 111

6) List and get books

readwise-cli book list --category books --json
readwise-cli book list --json --jq '.results[] | {id, title, author}'
readwise-cli book get 12345 --json

7) Export and daily review

readwise-cli export --json
readwise-cli export --updated-after "2025-01-01T00:00:00Z" --json
readwise-cli review --json
readwise-cli review --json --jq '.highlights[] | {text, title}'

8) Reader: list and save documents

readwise-cli reader list --json
readwise-cli reader list --category article --location new --json
readwise-cli reader save --url "https://example.com/article" --json
readwise-cli reader save --url "https://example.com" --title "Custom Title" --tag reading --tag tech --json

9) Reader: update and delete documents

readwise-cli reader update abc123 --title "New Title" --location archive
readwise-cli reader delete abc123

10) Reader tags

readwise-cli reader tag list --json
readwise-cli reader tag list --plain

Error Handling Rules

• Missing credentials: explicitly report missing READWISE_API_TOKEN.
• API failures: include HTTP status code and response body.
• Not found: clearly include the identifier that was requested.
• Auth failures: exit code 2. Not found: exit code 3. General errors: exit code 1.

Output Rules

• Use --json for machine-readable JSON output.
• Use --plain for tab-separated stable output.
• Use --jq with --json for filtered JSON output.
• Human hints are printed to stderr, data to stdout.
• Never invent Readwise data; only report real command results.