@readwise/cli 0.3.0

package/README.md

@@ -0,0 +1,140 @@
+# readwise
+
+A command-line interface for [Readwise](https://readwise.io) and [Reader](https://read.readwise.io). Search your highlights, manage your reading list, tag and organize documents — all from the terminal.
+
+Commands are auto-discovered from the Readwise API, so the CLI stays up to date as new features are added.
+
+## Install
+
+```bash
+git clone <repo-url> && cd readwise
+npm install
+npm run build
+npm link
+```
+
+## Setup
+
+### Interactive login (opens browser)
+
+```bash
+readwise login
+```
+
+### Access token login (for scripts/CI)
+
+Get your token from [readwise.io/access_token](https://readwise.io/access_token), then:
+
+```bash
+readwise login-with-token
+# prompts for token (hidden input, not stored in shell history)
+```
+
+You can also pipe the token in:
+
+```bash
+echo "$READWISE_TOKEN" | readwise login-with-token
+```
+
+Credentials are stored in `~/.readwise-cli.json`. OAuth tokens refresh automatically.
+
+## Commands
+
+Run `readwise --help` to see all available commands, or `readwise <command> --help` for details on a specific command.
+
+### Search documents
+
+```bash
+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-01
+```
+
+### Search highlights
+
+```bash
+readwise readwise-search-highlights --vector-search-term "spaced repetition"
+```
+
+### List and inspect documents
+
+```bash
+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>
+```
+
+### Save a document
+
+```bash
+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"
+```
+
+### Organize
+
+```bash
+# 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-document --document-id <id> --location archive
+
+# Edit metadata
+readwise reader-edit-document-metadata --document-id <id> --title "Better Title"
+readwise reader-set-document-notes --document-id <id> --notes "Updated notes"
+```
+
+### Highlight management
+
+```bash
+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..."
+```
+
+### Export
+
+```bash
+readwise reader-export-documents
+readwise reader-export-documents --since-updated "2024-06-01T00:00:00Z"
+```
+
+## Options
+
+| 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 |
+
+## Examples
+
+Pipe results to `jq`:
+
+```bash
+readwise reader-list-documents --limit 3 --json | jq '.results[].title'
+```
+
+## Development
+
+```bash
+# Run without building
+npx tsx src/index.ts --help
+
+# Build
+npm run build
+```
+
+## How it works
+
+The 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.

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+export declare function login(): Promise<void>;
+export declare function loginWithToken(token: string): Promise<void>;
+export declare function ensureValidToken(): Promise<{
+    token: string;
+    authType: "oauth" | "token";
+}>;

package/dist/auth.js

@@ -0,0 +1,194 @@
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { URL } from "node:url";
+import open from "open";
+import { loadConfig, saveConfig } from "./config.js";
+const DISCOVERY_URL = "https://readwise.io/o/.well-known/oauth-authorization-server";
+const REDIRECT_URI = "http://localhost:6274/callback";
+const SCOPES = "openid read write";
+async function discover() {
+    const res = await fetch(DISCOVERY_URL);
+    if (!res.ok)
+        throw new Error(`OAuth discovery failed: ${res.status} ${res.statusText}`);
+    return (await res.json());
+}
+async function registerClient(registrationEndpoint) {
+    const res = await fetch(registrationEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "readwise-cli",
+            redirect_uris: [REDIRECT_URI],
+            grant_types: ["authorization_code", "refresh_token"],
+            token_endpoint_auth_method: "client_secret_basic",
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Client registration failed: ${res.status} ${body}`);
+    }
+    return (await res.json());
+}
+function generatePKCE() {
+    const verifier = randomBytes(48).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+function waitForCallback(state) {
+    return new Promise((resolve, reject) => {
+        let timeout;
+        const cleanup = () => {
+            clearTimeout(timeout);
+            server.close();
+        };
+        const server = createServer((req, res) => {
+            const url = new URL(req.url, `http://localhost:6274`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const returnedState = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`<html><body><h1>Login failed</h1><p>${error}</p><p>You can close this tab.</p></body></html>`);
+                cleanup();
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            if (!code || returnedState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end(`<html><body><h1>Invalid callback</h1><p>You can close this tab.</p></body></html>`);
+                cleanup();
+                reject(new Error("Invalid callback: missing code or state mismatch"));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<html><body><h1>Login successful!</h1><p>You can close this tab and return to the terminal.</p></body></html>`);
+            cleanup();
+            resolve(code);
+        });
+        server.listen(6274, () => {
+            // Server ready
+        });
+        server.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`Failed to start callback server: ${err.message}`));
+        });
+        // Timeout after 2 minutes
+        timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Login timed out — no callback received within 2 minutes"));
+        }, 120_000);
+    });
+}
+async function exchangeToken(tokenEndpoint, code, clientId, clientSecret, codeVerifier) {
+    const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`,
+        },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: REDIRECT_URI,
+            code_verifier: codeVerifier,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Token exchange failed: ${res.status} ${body}`);
+    }
+    return (await res.json());
+}
+export async function login() {
+    console.log("Discovering OAuth endpoints...");
+    const metadata = await discover();
+    let config = await loadConfig();
+    // Register client if needed
+    if (!config.client_id || !config.client_secret) {
+        console.log("Registering client...");
+        const { client_id, client_secret } = await registerClient(metadata.registration_endpoint);
+        config.client_id = client_id;
+        config.client_secret = client_secret;
+        await saveConfig(config);
+    }
+    const { verifier, challenge } = generatePKCE();
+    const state = randomBytes(16).toString("hex");
+    const authUrl = new URL(metadata.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", config.client_id);
+    authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
+    authUrl.searchParams.set("scope", SCOPES);
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("state", state);
+    // Start callback server before opening browser
+    const codePromise = waitForCallback(state);
+    console.log("Opening browser for authentication...");
+    await open(authUrl.toString());
+    const code = await codePromise;
+    console.log("Exchanging authorization code for tokens...");
+    const tokens = await exchangeToken(metadata.token_endpoint, code, config.client_id, config.client_secret, verifier);
+    config.access_token = tokens.access_token;
+    config.refresh_token = tokens.refresh_token;
+    config.expires_at = Date.now() + tokens.expires_in * 1000;
+    config.auth_type = "oauth";
+    await saveConfig(config);
+    console.log("Login successful! Tokens saved to ~/.readwise-cli.json");
+}
+export async function loginWithToken(token) {
+    const config = await loadConfig();
+    config.access_token = token;
+    config.auth_type = "token";
+    delete config.refresh_token;
+    delete config.expires_at;
+    delete config.client_id;
+    delete config.client_secret;
+    await saveConfig(config);
+    console.log("Token saved to ~/.readwise-cli.json");
+}
+export async function ensureValidToken() {
+    const config = await loadConfig();
+    if (!config.access_token) {
+        throw new Error("Not logged in. Run `readwise-cli login` or `readwise-cli login-with-token <token>` first.");
+    }
+    const authType = config.auth_type ?? "oauth";
+    // Access tokens don't expire and don't need refresh
+    if (authType === "token") {
+        return { token: config.access_token, authType };
+    }
+    // Refresh if expired or expiring within 60s
+    if (config.expires_at && Date.now() > config.expires_at - 60_000) {
+        if (!config.refresh_token || !config.client_id || !config.client_secret) {
+            throw new Error("Cannot refresh token — missing credentials. Run `readwise-cli login` again.");
+        }
+        console.error("Refreshing access token...");
+        const metadata = await discover();
+        const res = await fetch(metadata.token_endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Authorization: `Basic ${Buffer.from(`${config.client_id}:${config.client_secret}`).toString("base64")}`,
+            },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: config.refresh_token,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Token refresh failed: ${res.status} ${body}. Run \`readwise-cli login\` again.`);
+        }
+        const tokens = (await res.json());
+        config.access_token = tokens.access_token;
+        if (tokens.refresh_token)
+            config.refresh_token = tokens.refresh_token;
+        config.expires_at = Date.now() + tokens.expires_in * 1000;
+        await saveConfig(config);
+    }
+    return { token: config.access_token, authType };
+}

package/dist/commands.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import type { ToolDef, SchemaProperty } from "./config.js";
+export declare function toolNameToCommand(name: string): string;
+export declare function resolveRef(prop: SchemaProperty, defs?: Record<string, SchemaProperty>): SchemaProperty;
+export declare function resolveProperty(prop: SchemaProperty, defs?: Record<string, SchemaProperty>): SchemaProperty;
+export declare function displayResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}, json: boolean): void;
+export declare function registerTools(program: Command, tools: ToolDef[]): void;

package/dist/commands.js

@@ -0,0 +1,152 @@
+import { ensureValidToken } from "./auth.js";
+import { callTool } from "./mcp.js";
+export function toolNameToCommand(name) {
+    return name.replace(/_/g, "-");
+}
+export function resolveRef(prop, defs) {
+    if (prop.$ref && defs) {
+        const name = prop.$ref.replace("#/$defs/", "");
+        const resolved = defs[name];
+        if (resolved)
+            return { ...resolved, description: prop.description || resolved.description };
+    }
+    return prop;
+}
+export function resolveProperty(prop, defs) {
+    let p = resolveRef(prop, defs);
+    if (p.anyOf) {
+        const nonNull = p.anyOf.find((v) => v.type !== "null");
+        if (nonNull) {
+            p = { ...p, ...resolveRef(nonNull, defs), anyOf: undefined };
+        }
+    }
+    // Resolve items.$ref for array types
+    if (p.type === "array" && p.items) {
+        p = { ...p, items: resolveRef(p.items, defs) };
+        // Also resolve anyOf inside items (e.g. items wrapped in anyOf)
+        if (p.items?.anyOf) {
+            const nonNull = p.items.anyOf.find((v) => v.type !== "null");
+            if (nonNull) {
+                const resolvedItem = resolveRef(nonNull, defs);
+                p = { ...p, items: { ...p.items, ...resolvedItem, anyOf: undefined } };
+            }
+        }
+    }
+    return p;
+}
+function optionFlag(name, prop) {
+    const flag = `--${name.replace(/_/g, "-")}`;
+    if (prop.type === "boolean") {
+        return flag;
+    }
+    return `${flag} <value>`;
+}
+function parseValue(value, prop) {
+    if (prop.type === "integer" || prop.type === "number") {
+        const n = Number(value);
+        if (isNaN(n))
+            throw new Error(`Expected a number for value: ${value}`);
+        return n;
+    }
+    if (prop.type === "array") {
+        // Try JSON first, then comma-separated
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // fall through
+        }
+        return value.split(",").map((s) => s.trim());
+    }
+    if (prop.type === "boolean") {
+        return true;
+    }
+    return value;
+}
+export function displayResult(result, json) {
+    if (result.isError) {
+        for (const item of result.content) {
+            if (item.text) {
+                process.stderr.write(`\x1b[31mError: ${item.text}\x1b[0m\n`);
+            }
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Prefer text content; fall back to structuredContent for empty results
+    let printed = false;
+    for (const item of result.content) {
+        if (item.type === "text" && item.text) {
+            printed = true;
+            if (json) {
+                process.stdout.write(item.text + "\n");
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(item.text);
+                    console.log(JSON.stringify(parsed, null, 2));
+                }
+                catch {
+                    console.log(item.text);
+                }
+            }
+        }
+    }
+    if (!printed && result.structuredContent) {
+        const data = result.structuredContent;
+        if (json) {
+            process.stdout.write(JSON.stringify(data) + "\n");
+        }
+        else {
+            console.log(JSON.stringify(data, null, 2));
+        }
+    }
+}
+export function registerTools(program, tools) {
+    for (const tool of tools) {
+        const cmd = program
+            .command(toolNameToCommand(tool.name))
+            .description(tool.description || "");
+        const properties = tool.inputSchema.properties || {};
+        const required = new Set(tool.inputSchema.required || []);
+        const defs = tool.inputSchema.$defs;
+        for (const [propName, rawProp] of Object.entries(properties)) {
+            const prop = resolveProperty(rawProp, defs);
+            const flag = optionFlag(propName, prop);
+            const parts = [];
+            if (prop.description)
+                parts.push(prop.description);
+            if (required.has(propName))
+                parts.push("(required)");
+            const enumValues = prop.enum || prop.items?.enum;
+            if (enumValues)
+                parts.push(`[${enumValues.join(", ")}]`);
+            if (prop.default !== undefined)
+                parts.push(`(default: ${JSON.stringify(prop.default)})`);
+            cmd.option(flag, parts.join(" ") || undefined);
+        }
+        cmd.action(async (options) => {
+            try {
+                const { token, authType } = await ensureValidToken();
+                // Convert commander options back to tool arguments
+                const args = {};
+                for (const [propName, rawProp] of Object.entries(properties)) {
+                    const prop = resolveProperty(rawProp, defs);
+                    const camelKey = propName.replace(/_/g, "-").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+                    const value = options[camelKey];
+                    if (value !== undefined) {
+                        args[propName] = parseValue(String(value), prop);
+                    }
+                }
+                const result = await callTool(token, authType, tool.name, args);
+                displayResult(result, program.opts().json || false);
+            }
+            catch (err) {
+                process.stderr.write(`\x1b[31m${err.message}\x1b[0m\n`);
+                process.exitCode = 1;
+            }
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+export interface ToolDef {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: string;
+        properties?: Record<string, SchemaProperty>;
+        required?: string[];
+        $defs?: Record<string, SchemaProperty>;
+    };
+}
+export interface SchemaProperty {
+    type?: string;
+    format?: string;
+    description?: string;
+    enum?: string[];
+    items?: SchemaProperty;
+    default?: unknown;
+    anyOf?: SchemaProperty[];
+    $ref?: string;
+    properties?: Record<string, SchemaProperty>;
+    required?: string[];
+}
+export interface Config {
+    client_id?: string;
+    client_secret?: string;
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    auth_type?: "oauth" | "token";
+    tools_cache?: {
+        tools: ToolDef[];
+        fetched_at: number;
+    };
+}
+export declare function getConfigPath(): string;
+export declare function loadConfig(): Promise<Config>;
+export declare function saveConfig(config: Config): Promise<void>;
+export declare function isCacheValid(config: Config): boolean;

package/dist/config.js

@@ -0,0 +1,24 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export function getConfigPath() {
+    return join(homedir(), ".readwise-cli.json");
+}
+export async function loadConfig() {
+    try {
+        const data = await readFile(getConfigPath(), "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveConfig(config) {
+    await writeFile(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+export function isCacheValid(config) {
+    if (!config.tools_cache)
+        return false;
+    return Date.now() - config.tools_cache.fetched_at < CACHE_TTL_MS;
+}

package/dist/index.d.ts

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