readwise-reader-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lis186
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# Readwise Reader CLI
+
+[![npm version](https://img.shields.io/npm/v/readwise-reader-cli.svg)](https://www.npmjs.com/package/readwise-reader-cli)
+[![CI](https://github.com/lis186/readwise-reader-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/lis186/readwise-reader-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A command-line interface for the [Readwise Reader](https://readwise.io/read) API.
+
+Based on the official [Readwise Reader API](https://readwise.io/reader_api).
+
+## Installation
+
+```bash
+npm install -g readwise-reader-cli
+```
+
+Or run directly with npx:
+
+```bash
+npx readwise-reader-cli list
+npx readwise-reader-cli save https://example.com
+```
+
+## Setup
+
+1. Get your Readwise access token from [readwise.io/access_token](https://readwise.io/access_token)
+
+2. Set the token as an environment variable:
+
+```bash
+export READWISE_TOKEN=your_token_here
+```
+
+Or create a `.env` file in your project:
+
+```
+READWISE_TOKEN=your_token_here
+```
+
+## Usage
+
+### List documents
+
+```bash
+# List all documents
+reader list
+
+# Filter by location
+reader list --location later
+
+# Filter by category
+reader list --category article
+
+# Limit results
+reader list --limit 10
+
+# Output as JSON
+reader list --json
+```
+
+### Save a document
+
+```bash
+# Save a URL
+reader save https://example.com/article
+
+# With metadata
+reader save https://example.com/article \
+  --title "My Article" \
+  --author "John Doe" \
+  --tags "tech,programming" \
+  --location later
+
+# Output as JSON
+reader save https://example.com/article --json
+```
+
+### Update a document
+
+```bash
+# Update title
+reader update <document-id> --title "New Title"
+
+# Update multiple fields
+reader update <document-id> \
+  --title "New Title" \
+  --author "Jane Doe" \
+  --location archive
+
+# Update tags
+reader update <document-id> --tags "new,tags"
+```
+
+### Delete a document
+
+```bash
+reader delete <document-id>
+```
+
+### List tags
+
+```bash
+reader tags
+reader tags --json
+```
+
+### Verify authentication
+
+```bash
+reader auth
+```
+
+## Options
+
+### Global options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON |
+| `--help` | Show help |
+| `--version` | Show version |
+
+### Location values
+
+- `new` - Inbox
+- `later` - Read Later
+- `archive` - Archive
+- `feed` - Feed
+
+### Category values
+
+- `article`
+- `email`
+- `rss`
+- `highlight`
+- `note`
+- `pdf`
+- `epub`
+- `tweet`
+- `video`
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/lis186/readwise-reader-cli.git
+cd readwise-reader-cli
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev -- list
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,12 @@
+import type { ListDocumentsParams, ListDocumentsResponse, SaveDocumentParams, SaveDocumentResponse, UpdateDocumentParams, Document, ListTagsResponse } from './types.js';
+export declare class ReadwiseApiClient {
+    private token;
+    constructor(token: string);
+    private request;
+    listDocuments(params?: ListDocumentsParams): Promise<ListDocumentsResponse>;
+    saveDocument(params: SaveDocumentParams): Promise<SaveDocumentResponse>;
+    updateDocument(id: string, params: UpdateDocumentParams): Promise<Document>;
+    deleteDocument(id: string): Promise<void>;
+    listTags(pageCursor?: string): Promise<ListTagsResponse>;
+    verifyAuth(): Promise<boolean>;
+}

package/dist/api-client.js

@@ -0,0 +1,79 @@
+const API_BASE_URL = 'https://readwise.io/api/v3';
+const AUTH_URL = 'https://readwise.io/api/v2/auth/';
+export class ReadwiseApiClient {
+    token;
+    constructor(token) {
+        if (!token) {
+            throw new Error('Readwise API token is required');
+        }
+        this.token = token;
+    }
+    async request(endpoint, options = {}) {
+        const url = `${API_BASE_URL}${endpoint}`;
+        const headers = {
+            'Authorization': `Token ${this.token}`,
+            'Content-Type': 'application/json',
+            ...options.headers,
+        };
+        const response = await fetch(url, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            if (response.status === 429) {
+                const retryAfter = response.headers.get('Retry-After');
+                throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`);
+            }
+            throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    async listDocuments(params = {}) {
+        const searchParams = new URLSearchParams();
+        Object.entries(params)
+            .filter(([_, v]) => v !== undefined)
+            .forEach(([k, v]) => searchParams.set(k, v === true ? 'true' : String(v)));
+        const query = searchParams.toString();
+        const endpoint = query ? `/list/?${query}` : '/list/';
+        return this.request(endpoint);
+    }
+    async saveDocument(params) {
+        return this.request('/save/', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async updateDocument(id, params) {
+        return this.request(`/update/${id}/`, {
+            method: 'PATCH',
+            body: JSON.stringify(params),
+        });
+    }
+    async deleteDocument(id) {
+        await this.request(`/delete/${id}/`, {
+            method: 'DELETE',
+        });
+    }
+    async listTags(pageCursor) {
+        const query = pageCursor ? `?pageCursor=${pageCursor}` : '';
+        return this.request(`/tags/${query}`);
+    }
+    async verifyAuth() {
+        const response = await fetch(AUTH_URL, {
+            headers: {
+                'Authorization': `Token ${this.token}`,
+            },
+        });
+        if (response.status === 204) {
+            return true;
+        }
+        if (response.status === 401) {
+            return false;
+        }
+        throw new Error(`Auth check failed: ${response.status} ${response.statusText}`);
+    }
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,4 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { BaseCommandOptions } from '../types.js';
+export type AuthCommandOptions = BaseCommandOptions;
+export declare function verifyAuth(client: ReadwiseApiClient, options?: AuthCommandOptions): Promise<string>;

package/dist/commands/auth.js

@@ -0,0 +1,10 @@
+export async function verifyAuth(client, options = {}) {
+    const isValid = await client.verifyAuth();
+    if (options.json) {
+        return JSON.stringify({ valid: isValid }, null, 2);
+    }
+    if (isValid) {
+        return 'Token is valid.';
+    }
+    return 'Token is invalid.';
+}

package/dist/commands/delete.d.ts

@@ -0,0 +1,4 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { BaseCommandOptions } from '../types.js';
+export type DeleteCommandOptions = BaseCommandOptions;
+export declare function deleteDocument(client: ReadwiseApiClient, id: string, options?: DeleteCommandOptions): Promise<string>;

package/dist/commands/delete.js

@@ -0,0 +1,7 @@
+export async function deleteDocument(client, id, options = {}) {
+    await client.deleteDocument(id);
+    if (options.json) {
+        return JSON.stringify({ success: true, id }, null, 2);
+    }
+    return `Document ${id} deleted successfully.`;
+}

package/dist/commands/index.d.ts

@@ -0,0 +1,12 @@
+export { listDocuments } from './list.js';
+export type { ListCommandOptions } from './list.js';
+export { saveDocument } from './save.js';
+export type { SaveCommandOptions } from './save.js';
+export { updateDocument } from './update.js';
+export type { UpdateCommandOptions } from './update.js';
+export { deleteDocument } from './delete.js';
+export type { DeleteCommandOptions } from './delete.js';
+export { listTags } from './tags.js';
+export type { TagsCommandOptions } from './tags.js';
+export { verifyAuth } from './auth.js';
+export type { AuthCommandOptions } from './auth.js';

package/dist/commands/index.js

@@ -0,0 +1,6 @@
+export { listDocuments } from './list.js';
+export { saveDocument } from './save.js';
+export { updateDocument } from './update.js';
+export { deleteDocument } from './delete.js';
+export { listTags } from './tags.js';
+export { verifyAuth } from './auth.js';

package/dist/commands/list.d.ts

@@ -0,0 +1,8 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { DocumentLocation, DocumentCategory, BaseCommandOptions } from '../types.js';
+export interface ListCommandOptions extends BaseCommandOptions {
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    limit?: number;
+}
+export declare function listDocuments(client: ReadwiseApiClient, options?: ListCommandOptions): Promise<string>;

package/dist/commands/list.js

@@ -0,0 +1,29 @@
+import { removeUndefined } from '../types.js';
+export async function listDocuments(client, options = {}) {
+    const response = await client.listDocuments(removeUndefined({ location: options.location, category: options.category }));
+    const documents = options.limit
+        ? response.results.slice(0, options.limit)
+        : response.results;
+    if (options.json) {
+        return JSON.stringify(documents, null, 2);
+    }
+    if (documents.length === 0) {
+        return 'No documents found.';
+    }
+    const lines = documents.map((doc, index) => {
+        // Handle tags as either array or empty object from API
+        const tagsArray = Array.isArray(doc.tags) ? doc.tags : [];
+        const tags = tagsArray.map((t) => t.name).join(', ');
+        return [
+            `[${index + 1}] ${doc.title || '(Untitled)'}`,
+            `    ID: ${doc.id}`,
+            `    URL: ${doc.source_url || doc.url}`,
+            `    Location: ${doc.location} | Category: ${doc.category}`,
+            tags ? `    Tags: ${tags}` : null,
+            `    Saved: ${new Date(doc.saved_at).toLocaleDateString()}`,
+        ]
+            .filter(Boolean)
+            .join('\n');
+    });
+    return `Found ${response.count} documents:\n\n${lines.join('\n\n')}`;
+}

package/dist/commands/save.d.ts

@@ -0,0 +1,11 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { DocumentLocation, DocumentCategory, BaseCommandOptions } from '../types.js';
+export interface SaveCommandOptions extends BaseCommandOptions {
+    title?: string;
+    author?: string;
+    tags?: string[];
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    notes?: string;
+}
+export declare function saveDocument(client: ReadwiseApiClient, url: string, options?: SaveCommandOptions): Promise<string>;

package/dist/commands/save.js

@@ -0,0 +1,17 @@
+import { removeUndefined } from '../types.js';
+export async function saveDocument(client, url, options = {}) {
+    const params = removeUndefined({
+        url,
+        title: options.title,
+        author: options.author,
+        tags: options.tags,
+        location: options.location,
+        category: options.category,
+        notes: options.notes,
+    });
+    const response = await client.saveDocument(params);
+    if (options.json) {
+        return JSON.stringify(response, null, 2);
+    }
+    return `Document saved successfully!\n  ID: ${response.id}\n  URL: ${response.url}`;
+}

package/dist/commands/tags.d.ts

@@ -0,0 +1,4 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { BaseCommandOptions } from '../types.js';
+export type TagsCommandOptions = BaseCommandOptions;
+export declare function listTags(client: ReadwiseApiClient, options?: TagsCommandOptions): Promise<string>;

package/dist/commands/tags.js

@@ -0,0 +1,11 @@
+export async function listTags(client, options = {}) {
+    const response = await client.listTags();
+    if (options.json) {
+        return JSON.stringify(response.results, null, 2);
+    }
+    if (response.results.length === 0) {
+        return 'No tags found.';
+    }
+    const tagList = response.results.map((tag) => `  - ${tag.name}`).join('\n');
+    return `Tags (${response.count}):\n${tagList}`;
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,11 @@
+import type { ReadwiseApiClient } from '../api-client.js';
+import type { DocumentLocation, DocumentCategory, BaseCommandOptions } from '../types.js';
+export interface UpdateCommandOptions extends BaseCommandOptions {
+    title?: string;
+    author?: string;
+    summary?: string;
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    tags?: string[];
+}
+export declare function updateDocument(client: ReadwiseApiClient, id: string, options?: UpdateCommandOptions): Promise<string>;

package/dist/commands/update.js

@@ -0,0 +1,13 @@
+import { removeUndefined } from '../types.js';
+export async function updateDocument(client, id, options = {}) {
+    const { json, ...params } = options;
+    const cleanParams = removeUndefined(params);
+    if (Object.keys(cleanParams).length === 0) {
+        throw new Error('At least one field must be provided to update');
+    }
+    const response = await client.updateDocument(id, cleanParams);
+    if (json) {
+        return JSON.stringify(response, null, 2);
+    }
+    return `Document updated successfully!\n  ID: ${response.id}\n  Title: ${response.title || '(Untitled)'}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { config } from 'dotenv';
+import { ReadwiseApiClient } from './api-client.js';
+import { listDocuments, saveDocument, updateDocument, deleteDocument, listTags, verifyAuth, } from './commands/index.js';
+// Load environment variables
+config();
+const program = new Command();
+function getClient() {
+    const token = process.env.READWISE_TOKEN || process.env.READWISE_ACCESS_TOKEN;
+    if (!token) {
+        console.error('Error: READWISE_TOKEN or READWISE_ACCESS_TOKEN environment variable is required.');
+        console.error('Set it in your .env file or export it in your shell.');
+        process.exit(1);
+    }
+    return new ReadwiseApiClient(token);
+}
+// Common error handling wrapper for command actions
+function withErrorHandling(handler) {
+    return async (...args) => {
+        try {
+            const client = getClient();
+            const result = await handler(client, ...args);
+            console.log(result);
+        }
+        catch (error) {
+            console.error('Error:', error.message);
+            process.exit(1);
+        }
+    };
+}
+program
+    .name('reader')
+    .description('CLI tool for Readwise Reader API')
+    .version('0.1.0');
+// List documents command
+program
+    .command('list')
+    .description('List documents from your Reader library')
+    .option('-l, --location <location>', 'Filter by location (new, later, archive, feed)')
+    .option('-c, --category <category>', 'Filter by category (article, email, pdf, etc.)')
+    .option('-n, --limit <number>', 'Limit number of results', parseInt)
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(listDocuments));
+// Save document command
+program
+    .command('save <url>')
+    .description('Save a new document to Reader')
+    .option('-t, --title <title>', 'Document title')
+    .option('-a, --author <author>', 'Document author')
+    .option('--tags <tags>', 'Comma-separated tags', (val) => val.split(','))
+    .option('-l, --location <location>', 'Location (new, later, archive, feed)')
+    .option('-c, --category <category>', 'Category (article, email, pdf, etc.)')
+    .option('--notes <notes>', 'Notes to add')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(saveDocument));
+// Update document command
+program
+    .command('update <id>')
+    .description('Update an existing document')
+    .option('-t, --title <title>', 'New title')
+    .option('-a, --author <author>', 'New author')
+    .option('-s, --summary <summary>', 'New summary')
+    .option('-l, --location <location>', 'New location (new, later, archive, feed)')
+    .option('-c, --category <category>', 'New category')
+    .option('--tags <tags>', 'New tags (comma-separated)', (val) => val.split(','))
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(updateDocument));
+// Delete document command
+program
+    .command('delete <id>')
+    .description('Delete a document')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(deleteDocument));
+// List tags command
+program
+    .command('tags')
+    .description('List all tags')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(listTags));
+// Verify auth command
+program
+    .command('auth')
+    .description('Verify API token is valid')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(verifyAuth));
+program.parse();

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+export type DocumentLocation = 'new' | 'later' | 'archive' | 'feed';
+export type DocumentCategory = 'article' | 'email' | 'rss' | 'highlight' | 'note' | 'pdf' | 'epub' | 'tweet' | 'video';
+export interface Tag {
+    name: string;
+}
+export interface Document {
+    id: string;
+    url: string;
+    source_url: string;
+    title: string;
+    author: string | null;
+    source: string | null;
+    category: DocumentCategory;
+    location: DocumentLocation;
+    tags: Tag[] | Record<string, never>;
+    site_name: string | null;
+    word_count: number | null;
+    created_at: string;
+    updated_at: string;
+    published_date: string | null;
+    summary: string | null;
+    image_url: string | null;
+    reading_progress: number;
+    first_opened_at: string | null;
+    last_opened_at: string | null;
+    saved_at: string;
+    last_moved_at: string;
+}
+export interface ListDocumentsResponse {
+    count: number;
+    nextPageCursor: string | null;
+    results: Document[];
+}
+export interface ListDocumentsParams {
+    id?: string;
+    updatedAfter?: string;
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    pageCursor?: string;
+    withHtmlContent?: boolean;
+}
+export interface SaveDocumentParams {
+    url: string;
+    html?: string;
+    title?: string;
+    author?: string;
+    tags?: string[];
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    published_date?: string;
+    image_url?: string;
+    notes?: string;
+}
+export interface SaveDocumentResponse {
+    id: string;
+    url: string;
+}
+export interface UpdateDocumentParams {
+    title?: string;
+    author?: string;
+    summary?: string;
+    published_date?: string;
+    image_url?: string;
+    location?: DocumentLocation;
+    category?: DocumentCategory;
+    tags?: string[];
+}
+export interface ListTagsResponse {
+    count: number;
+    nextPageCursor: string | null;
+    results: Tag[];
+}
+export interface BaseCommandOptions {
+    json?: boolean;
+}
+export declare function removeUndefined<T extends object>(obj: T): T;

package/dist/types.js

@@ -0,0 +1,4 @@
+// Utility function to remove undefined values from an object
+export function removeUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([_, v]) => v !== undefined));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "readwise-reader-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for Readwise Reader API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "reader": "./dist/index.js",
+    "readwise-reader-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "npm run test:run && npm run build"
+  },
+  "keywords": [
+    "readwise",
+    "reader",
+    "cli",
+    "reading-list"
+  ],
+  "author": "lis186",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lis186/readwise-reader-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lis186/readwise-reader-cli/issues"
+  },
+  "homepage": "https://github.com/lis186/readwise-reader-cli#readme",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0",
+    "tsx": "^4.6.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "dotenv": "^16.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}