@readwise/cli 0.3.1 → 0.5.1

package/README.md

@@ -1,8 +1,8 @@
-# readwise
+# The Official Readwise CLI
 
-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.
+A command-line interface for [Readwise](https://readwise.io) and [Reader](https://read.readwise.io). Search your documents & 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.
+Anything you can do in Readwise/Reader, your agent can now do for you.
 
 ## Install
 
@@ -18,7 +18,7 @@ npm install -g @readwise/cli
 readwise login
 ```
 
-### Access token login (for scripts/CI)
+### Access token login (for separate hosts like OpenClaw, or scripts)
 
 Get your token from [readwise.io/access_token](https://readwise.io/access_token), then:
 
@@ -64,6 +64,8 @@ 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: 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":"<id>","seen":true}]'` to mark a document as seen.
+
 ### Save a document
 
 ```bash
@@ -84,11 +86,12 @@ readwise reader-add-tags-to-document --document-id <id> --tag-names "important,r
 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
+readwise reader-move-documents --document-ids <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"
+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"}]'
 ```
 
 ### Highlight management

package/dist/config.d.ts

@@ -15,6 +15,7 @@ export interface SchemaProperty {
     enum?: string[];
     items?: SchemaProperty;
     default?: unknown;
+    examples?: unknown[];
     anyOf?: SchemaProperty[];
     $ref?: string;
     properties?: Record<string, SchemaProperty>;

package/dist/index.js

@@ -6,6 +6,7 @@ import { getTools } from "./mcp.js";
 import { registerTools } from "./commands.js";
 import { loadConfig } from "./config.js";
 import { VERSION } from "./version.js";
+import { registerSkillsCommands } from "./skills.js";
 function readHiddenInput(prompt) {
     return new Promise((resolve, reject) => {
         if (!process.stdin.isTTY) {
@@ -90,8 +91,9 @@ async function main() {
     const forceRefresh = process.argv.includes("--refresh");
     const positionalArgs = process.argv.slice(2).filter((a) => !a.startsWith("--"));
     const hasSubcommand = positionalArgs.length > 0;
-    // If no subcommand, TTY, and authenticated → launch TUI
-    if (!hasSubcommand && process.stdout.isTTY && config.access_token) {
+    const wantsHelp = process.argv.includes("--help") || process.argv.includes("-h");
+    // If no subcommand, TTY, and authenticated → launch TUI (unless --help)
+    if (!hasSubcommand && !wantsHelp && process.stdout.isTTY && config.access_token) {
         try {
             const { token, authType } = await ensureValidToken();
             const tools = await getTools(token, authType, forceRefresh);
@@ -110,6 +112,14 @@ async function main() {
         console.log("\nRun `readwise login` or `readwise login-with-token` to authenticate.");
         return;
     }
+    // Register skills commands (works without auth)
+    registerSkillsCommands(program);
+    // If not authenticated and trying a non-login command, tell user to log in
+    if (!config.access_token && hasSubcommand && positionalArgs[0] !== "login" && positionalArgs[0] !== "login-with-token" && positionalArgs[0] !== "skills") {
+        process.stderr.write("\x1b[31mNot logged in.\x1b[0m Run `readwise login` or `readwise login-with-token` to authenticate.\n");
+        process.exitCode = 1;
+        return;
+    }
     // Try to load tools if we have a token (for subcommand mode)
     if (config.access_token) {
         try {
@@ -119,7 +129,6 @@ async function main() {
         }
         catch (err) {
             // Don't fail — login command should still work
-            // Only warn if user is trying to run a non-login command
             if (hasSubcommand && positionalArgs[0] !== "login" && positionalArgs[0] !== "login-with-token") {
                 process.stderr.write(`\x1b[33mWarning: Could not fetch tools: ${err.message}\x1b[0m\n`);
             }

package/dist/skills.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerSkillsCommands(program: Command): void;

package/dist/skills.js

@@ -0,0 +1,246 @@
+import { readdir, readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+const REPO_OWNER = "readwiseio";
+const REPO_NAME = "readwise-skills";
+const SKILLS_SUBDIR = "skills";
+const GITHUB_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}`;
+const GITHUB_RAW = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/master`;
+/** Local cache directory for fetched skills */
+function cacheDir() {
+    return join(homedir(), ".readwise", "skills-cache");
+}
+/** Staleness threshold — refetch if cache is older than this */
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+function cacheMetaPath() {
+    return join(cacheDir(), ".fetched_at");
+}
+async function isCacheFresh() {
+    const metaPath = cacheMetaPath();
+    if (!existsSync(metaPath))
+        return false;
+    try {
+        const ts = Number(await readFile(metaPath, "utf-8"));
+        return Date.now() - ts < CACHE_MAX_AGE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function touchCache() {
+    await writeFile(cacheMetaPath(), String(Date.now()));
+}
+/** Fetch the list of skill directory names from GitHub API */
+async function fetchSkillNames() {
+    const res = await fetch(`${GITHUB_API}/contents/${SKILLS_SUBDIR}`, {
+        headers: { Accept: "application/vnd.github.v3+json", "User-Agent": "readwise-cli" },
+    });
+    if (!res.ok)
+        throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
+    const entries = (await res.json());
+    return entries.filter((e) => e.type === "dir").map((e) => e.name);
+}
+/** Fetch a single SKILL.md from GitHub */
+async function fetchSkillFile(skillName) {
+    const url = `${GITHUB_RAW}/${SKILLS_SUBDIR}/${skillName}/SKILL.md`;
+    const res = await fetch(url, { headers: { "User-Agent": "readwise-cli" } });
+    if (!res.ok)
+        throw new Error(`Failed to fetch ${skillName}: ${res.status}`);
+    return res.text();
+}
+/** Fetch all skills from GitHub and write to cache */
+async function refreshCache() {
+    const names = await fetchSkillNames();
+    const cache = cacheDir();
+    // Clear old cache
+    if (existsSync(cache))
+        await rm(cache, { recursive: true });
+    await mkdir(cache, { recursive: true });
+    // Fetch all in parallel
+    const results = await Promise.allSettled(names.map(async (name) => {
+        const content = await fetchSkillFile(name);
+        const dir = join(cache, name);
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, "SKILL.md"), content);
+        return name;
+    }));
+    const fetched = results
+        .filter((r) => r.status === "fulfilled")
+        .map((r) => r.value);
+    await touchCache();
+    return fetched;
+}
+/** Get cached skill names, refreshing if stale */
+async function getSkillNames(forceRefresh) {
+    if (!forceRefresh && (await isCacheFresh())) {
+        return listCachedSkills();
+    }
+    try {
+        return await refreshCache();
+    }
+    catch (err) {
+        // Fall back to cache if network fails
+        const cached = await listCachedSkills();
+        if (cached.length > 0) {
+            console.error(`\x1b[33mWarning: Could not fetch from GitHub (${err.message}), using cached skills.\x1b[0m`);
+            return cached;
+        }
+        throw err;
+    }
+}
+async function listCachedSkills() {
+    const cache = cacheDir();
+    if (!existsSync(cache))
+        return [];
+    const entries = await readdir(cache, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isDirectory() && existsSync(join(cache, e.name, "SKILL.md")))
+        .map((e) => e.name);
+}
+async function readSkillFrontmatter(skillName) {
+    const content = await readFile(join(cacheDir(), skillName, "SKILL.md"), "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const fm = {};
+    for (const line of match[1].split("\n")) {
+        const [key, ...rest] = line.split(":");
+        if (key && rest.length)
+            fm[key.trim()] = rest.join(":").trim();
+    }
+    return fm;
+}
+/** Known agent platforms and their skills directories */
+const PLATFORMS = {
+    claude: { name: "Claude Code", path: join(homedir(), ".claude", "skills") },
+    codex: { name: "Codex CLI", path: join(homedir(), ".codex", "skills") },
+    opencode: { name: "OpenCode", path: join(homedir(), ".opencode", "skills") },
+};
+export function registerSkillsCommands(program) {
+    const skills = program.command("skills").description("Manage Readwise skills for AI agents");
+    skills
+        .command("list")
+        .description("List available skills (fetched from github.com/readwiseio/readwise-skills)")
+        .option("--refresh", "Force refresh from GitHub")
+        .action(async (opts) => {
+        try {
+            const names = await getSkillNames(!!opts.refresh);
+            if (names.length === 0) {
+                console.log("No skills found.");
+                return;
+            }
+            console.log("Available skills:\n");
+            for (const name of names) {
+                const fm = await readSkillFrontmatter(name);
+                const desc = fm.description || "";
+                console.log(`  ${name.padEnd(22)} ${desc}`);
+            }
+            console.log(`\nRun \`readwise skills install <platform>\` to install. Platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+        }
+        catch (err) {
+            console.error(`\x1b[31mFailed to list skills: ${err.message}\x1b[0m`);
+            process.exitCode = 1;
+        }
+    });
+    skills
+        .command("install [platform]")
+        .description("Install skills to an agent platform (claude, codex, opencode)")
+        .option("--all", "Detect installed agents and install to all")
+        .option("--refresh", "Force refresh from GitHub before installing")
+        .action(async (platform, opts) => {
+        try {
+            const names = await getSkillNames(!!opts?.refresh);
+            if (names.length === 0) {
+                console.error("No skills found.");
+                process.exitCode = 1;
+                return;
+            }
+            let targets = [];
+            if (opts?.all) {
+                for (const [key, info] of Object.entries(PLATFORMS)) {
+                    const parentDir = dirname(info.path);
+                    if (existsSync(parentDir)) {
+                        targets.push({ key, ...info });
+                    }
+                }
+                if (targets.length === 0) {
+                    console.log("No supported agents detected. Supported platforms: " + Object.keys(PLATFORMS).join(", "));
+                    return;
+                }
+            }
+            else if (platform) {
+                const info = PLATFORMS[platform.toLowerCase()];
+                if (!info) {
+                    console.error(`Unknown platform: ${platform}`);
+                    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                targets = [{ key: platform.toLowerCase(), ...info }];
+            }
+            else {
+                console.error("Specify a platform or use --all.");
+                console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+                process.exitCode = 1;
+                return;
+            }
+            const cache = cacheDir();
+            for (const target of targets) {
+                console.log(`\nInstalling to ${target.name} (${target.path})...`);
+                await mkdir(target.path, { recursive: true });
+                for (const skillName of names) {
+                    const srcFile = join(cache, skillName, "SKILL.md");
+                    const destDir = join(target.path, skillName);
+                    await mkdir(destDir, { recursive: true });
+                    const content = await readFile(srcFile, "utf-8");
+                    await writeFile(join(destDir, "SKILL.md"), content);
+                    console.log(`  \u2713 ${skillName}`);
+                }
+            }
+            console.log("\nDone!");
+        }
+        catch (err) {
+            console.error(`\x1b[31mFailed to install skills: ${err.message}\x1b[0m`);
+            process.exitCode = 1;
+        }
+    });
+    skills
+        .command("show <name>")
+        .description("Print the raw SKILL.md for a skill")
+        .option("--refresh", "Force refresh from GitHub")
+        .action(async (name, opts) => {
+        try {
+            await getSkillNames(!!opts.refresh);
+            const skillPath = join(cacheDir(), name, "SKILL.md");
+            if (!existsSync(skillPath)) {
+                console.error(`Skill not found: ${name}`);
+                const available = await listCachedSkills();
+                if (available.length)
+                    console.error(`Available: ${available.join(", ")}`);
+                process.exitCode = 1;
+                return;
+            }
+            const content = await readFile(skillPath, "utf-8");
+            process.stdout.write(content);
+        }
+        catch (err) {
+            console.error(`\x1b[31mFailed: ${err.message}\x1b[0m`);
+            process.exitCode = 1;
+        }
+    });
+    skills
+        .command("update")
+        .description("Force refresh skills from GitHub")
+        .action(async () => {
+        try {
+            console.log("Fetching skills from github.com/readwiseio/readwise-skills...");
+            const names = await refreshCache();
+            console.log(`Updated ${names.length} skills: ${names.join(", ")}`);
+        }
+        catch (err) {
+            console.error(`\x1b[31mFailed to update: ${err.message}\x1b[0m`);
+            process.exitCode = 1;
+        }
+    });
+}