@vakra-dev/reader-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vakra-dev
+
+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,177 @@
+# Reader CLI
+
+Read the web from your terminal. Built for AI coding agents.
+
+The Reader CLI scrapes, crawls, and screenshots web pages via the [Reader API](https://reader.dev). It outputs clean markdown to stdout, ready to pipe into any AI workflow.
+
+## Install
+
+```bash
+npm install -g @vakra-dev/reader-cli
+```
+
+Or run directly:
+
+```bash
+npx @vakra-dev/reader-cli scrape https://example.com
+```
+
+## Setup
+
+**For humans** - save your API key once:
+
+```bash
+reader config set api-key rdr_your_key_here
+```
+
+**For AI agents / CI** - set the environment variable:
+
+```bash
+export READER_API_KEY=rdr_your_key_here
+```
+
+Get your API key at [console.reader.dev](https://console.reader.dev).
+
+## Usage
+
+### Scrape a page
+
+```bash
+reader scrape https://example.com
+```
+
+Output is clean markdown, printed to stdout:
+
+```bash
+reader scrape https://docs.stripe.com/payments > stripe-payments.md
+```
+
+### Formats
+
+```bash
+reader scrape https://example.com                     # markdown (default)
+reader scrape https://example.com -f html              # cleaned HTML
+reader scrape https://example.com -f screenshot -o page.png   # full-page screenshot
+```
+
+### JSON output
+
+Get the full API response with metadata:
+
+```bash
+reader scrape https://example.com --json
+```
+
+### Crawl a site
+
+Discover and scrape all pages:
+
+```bash
+reader crawl https://docs.example.com --max-pages 20
+```
+
+Save pages to individual files:
+
+```bash
+reader crawl https://docs.example.com -o ./docs/
+```
+
+List URLs only:
+
+```bash
+reader crawl https://example.com --urls-only
+```
+
+### Check status
+
+```bash
+reader status
+```
+
+```
+Reader CLI v0.1.0
+API:     https://api.reader.dev (connected)
+Key:     rdr_...c3bb
+Credits: 874 / 1000 (free tier)
+Resets:  2026-07-01
+```
+
+### Check credits
+
+```bash
+reader credits
+reader credits --json
+```
+
+### Configuration
+
+```bash
+reader config set api-key <key>     # save API key
+reader config set api-url <url>     # custom API URL
+reader config show                  # show current config
+```
+
+Config is stored at `~/.reader/config.json`. Environment variables take precedence:
+
+| Setting | Env var | Default |
+|---------|---------|---------|
+| API key | `READER_API_KEY` | - |
+| API URL | `READER_API_URL` | `https://api.reader.dev` |
+
+## Command reference
+
+### `reader scrape <url>`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-f, --format` | Output format: `markdown`, `html`, `screenshot` | `markdown` |
+| `--json` | Full JSON response | - |
+| `-o, --output` | Write to file | stdout |
+| `--no-main-content` | Include nav, header, footer | - |
+| `--include-tags` | CSS selectors to keep | - |
+| `--exclude-tags` | CSS selectors to remove | - |
+| `--wait-for` | Wait for CSS selector | - |
+| `--timeout` | Timeout in ms | `30000` |
+| `--proxy-mode` | `standard`, `stealth`, `auto` | `auto` |
+
+### `reader crawl <url>`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--max-depth` | Crawl depth | `2` |
+| `--max-pages` | Max pages to crawl | `20` |
+| `--urls-only` | Only list URLs | - |
+| `--json` | Full JSON response | - |
+| `-o, --output-dir` | Write pages to directory | stdout |
+
+### `reader status`
+
+Shows CLI version, API connectivity, credit balance, and tier.
+
+### `reader credits`
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Full JSON response |
+
+### `reader config`
+
+| Subcommand | Description |
+|------------|-------------|
+| `set api-key <key>` | Save API key |
+| `set api-url <url>` | Set custom API URL |
+| `show` | Display current config |
+
+## For AI agents
+
+The CLI is designed for seamless use with AI coding agents like Claude Code, Cursor, and Codex:
+
+- **Markdown to stdout** - agents read content directly
+- **Errors to stderr** - never pollutes piped output
+- **Exit codes** - 0 on success, 1 on error
+- **No interactive prompts** - everything via flags and env vars
+- **`--json` flag** - structured output for programmatic use
+
+## License
+
+MIT - see [LICENSE](LICENSE).

package/dist/index.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/scrape.ts
+import { ReaderClient } from "@vakra-dev/reader-js";
+
+// src/utils/config.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var CONFIG_DIR = join(homedir(), ".reader");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+function loadConfig() {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+  } catch {
+  }
+  return {};
+}
+function saveConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+function getApiKey() {
+  if (process.env.READER_API_KEY) {
+    return process.env.READER_API_KEY;
+  }
+  const config = loadConfig();
+  if (config.apiKey) {
+    return config.apiKey;
+  }
+  console.error("Error: No API key configured.\n");
+  console.error("  For humans:  reader config set api-key <your-key>");
+  console.error("  For agents:  export READER_API_KEY=<your-key>");
+  console.error("\n  Get your key at https://console.reader.dev");
+  process.exit(1);
+}
+function getApiUrl() {
+  return process.env.READER_API_URL || loadConfig().apiUrl || "https://api.reader.dev";
+}
+function redactKey(key) {
+  if (key.length <= 8) return "****";
+  return key.slice(0, 4) + "..." + key.slice(-4);
+}
+
+// src/utils/output.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+function info(msg) {
+  console.error(msg);
+}
+function error(msg) {
+  console.error(`Error: ${msg}`);
+}
+function outputContent(content) {
+  process.stdout.write(content);
+}
+function outputJson(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+function saveScreenshot(base64, outputPath) {
+  const buffer = Buffer.from(base64, "base64");
+  const path = outputPath || "screenshot.png";
+  writeFileSync2(path, buffer);
+  return path;
+}
+
+// src/commands/scrape.ts
+function registerScrapeCommand(program2) {
+  program2.command("scrape <url>").description("Scrape a URL and output content").option("-f, --format <format>", "Output format: markdown (default), html, screenshot", "markdown").option("--json", "Output full JSON response").option("-o, --output <file>", "Write output to file").option("--no-main-content", "Include full page (nav, header, footer)").option("--include-tags <selectors>", "CSS selectors to include (comma-separated)").option("--exclude-tags <selectors>", "CSS selectors to exclude (comma-separated)").option("--wait-for <selector>", "Wait for CSS selector before scraping").option("--timeout <ms>", "Timeout in milliseconds", "30000").option("--proxy-mode <mode>", "Proxy mode: standard, stealth, auto").action(async (url, opts) => {
+    const apiKey = getApiKey();
+    const client = new ReaderClient({ apiKey, baseUrl: getApiUrl() });
+    const formats = [];
+    const requestedFormat = opts.format;
+    if (requestedFormat === "screenshot") {
+      formats.push("screenshot");
+    } else if (requestedFormat === "html") {
+      formats.push("html");
+    } else {
+      formats.push("markdown");
+    }
+    if (requestedFormat !== "screenshot" && opts.output?.endsWith(".png")) {
+      formats.push("screenshot");
+    }
+    try {
+      const result = await client.read({
+        url,
+        formats,
+        onlyMainContent: opts.mainContent !== false,
+        includeTags: opts.includeTags?.split(",").map((s) => s.trim()),
+        excludeTags: opts.excludeTags?.split(",").map((s) => s.trim()),
+        waitForSelector: opts.waitFor,
+        timeoutMs: parseInt(opts.timeout, 10),
+        proxyMode: opts.proxyMode
+      });
+      if (result.kind === "scrape") {
+        const data = result.data;
+        if (opts.json) {
+          outputJson(data);
+          return;
+        }
+        if (data.screenshot) {
+          const path = saveScreenshot(data.screenshot, opts.output);
+          info(`Screenshot saved to ${path}`);
+          if (requestedFormat === "screenshot") return;
+        }
+        const content = data.markdown || data.html || "";
+        if (opts.output && !opts.output.endsWith(".png")) {
+          const { writeFileSync: writeFileSync3 } = await import("fs");
+          writeFileSync3(opts.output, content);
+          info(`Written to ${opts.output}`);
+        } else {
+          outputContent(content);
+        }
+      } else {
+        const job = result.data;
+        if (opts.json) {
+          outputJson(job);
+        } else {
+          for (const page of job.results) {
+            outputContent(page.markdown || page.html || "");
+          }
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      error(msg);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/crawl.ts
+import { ReaderClient as ReaderClient2 } from "@vakra-dev/reader-js";
+function registerCrawlCommand(program2) {
+  program2.command("crawl <url>").description("Crawl a website and output discovered pages").option("--max-depth <n>", "Maximum crawl depth", "2").option("--max-pages <n>", "Maximum pages to crawl", "20").option("--urls-only", "Only output discovered URLs, don't scrape content").option("--json", "Output full JSON response").option("-o, --output-dir <dir>", "Write each page to a separate file").action(async (url, opts) => {
+    const apiKey = getApiKey();
+    const client = new ReaderClient2({ apiKey, baseUrl: getApiUrl() });
+    info(`Crawling ${url} (depth: ${opts.maxDepth}, max: ${opts.maxPages} pages)...`);
+    try {
+      const result = await client.read({
+        url,
+        maxDepth: parseInt(opts.maxDepth, 10),
+        maxPages: parseInt(opts.maxPages, 10),
+        formats: opts.urlsOnly ? [] : ["markdown"]
+      });
+      if (result.kind !== "job") {
+        error("Unexpected response - expected a crawl job");
+        process.exit(1);
+      }
+      const job = result.data;
+      if (opts.json) {
+        outputJson(job);
+        return;
+      }
+      if (opts.urlsOnly || job.results.length === 0) {
+        for (const page of job.results) {
+          outputContent(page.url + "\n");
+        }
+        info(`
+${job.results.length} URLs discovered`);
+        return;
+      }
+      if (opts.outputDir) {
+        const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync3 } = await import("fs");
+        mkdirSync2(opts.outputDir, { recursive: true });
+        for (const page of job.results) {
+          const slug = new URL(page.url).pathname.replace(/\//g, "_").replace(/^_/, "").replace(/_$/, "") || "index";
+          const filename = `${opts.outputDir}/${slug}.md`;
+          writeFileSync3(filename, page.markdown || page.html || "");
+        }
+        info(`${job.results.length} pages written to ${opts.outputDir}/`);
+      } else {
+        for (let i = 0; i < job.results.length; i++) {
+          const page = job.results[i];
+          if (i > 0) outputContent("\n---\n\n");
+          outputContent(`# ${page.url}
+
+`);
+          outputContent(page.markdown || page.html || "");
+        }
+        info(`
+${job.results.length} pages crawled`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      error(msg);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/status.ts
+import { ReaderClient as ReaderClient3 } from "@vakra-dev/reader-js";
+
+// src/version.ts
+var version = "0.1.0";
+
+// src/commands/status.ts
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show CLI version, API connectivity, and credits").action(async () => {
+    const apiKey = getApiKey();
+    const apiUrl = getApiUrl();
+    const client = new ReaderClient3({ apiKey, baseUrl: apiUrl });
+    console.log(`Reader CLI v${version}`);
+    console.log(`API:     ${apiUrl}`);
+    console.log(`Key:     ${redactKey(apiKey)}`);
+    try {
+      const credits = await client.getCredits();
+      console.log(`Credits: ${credits.balance} / ${credits.limit} (${credits.tier} tier)`);
+      console.log(`Resets:  ${credits.resetAt}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`API:     connection failed (${msg})`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/credits.ts
+import { ReaderClient as ReaderClient4 } from "@vakra-dev/reader-js";
+function registerCreditsCommand(program2) {
+  program2.command("credits").description("Check credit balance and usage").option("--json", "Output full JSON response").action(async (opts) => {
+    const apiKey = getApiKey();
+    const client = new ReaderClient4({ apiKey, baseUrl: getApiUrl() });
+    try {
+      const credits = await client.getCredits();
+      if (opts.json) {
+        outputJson(credits);
+        return;
+      }
+      console.log(`Balance: ${credits.balance} / ${credits.limit}`);
+      console.log(`Used:    ${credits.used}`);
+      console.log(`Tier:    ${credits.tier}`);
+      console.log(`Resets:  ${credits.resetAt}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      error(msg);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/config.ts
+function registerConfigCommand(program2) {
+  const config = program2.command("config").description("Manage CLI configuration");
+  config.command("set <key> <value>").description("Set a config value (api-key, api-url)").action((key, value) => {
+    const current = loadConfig();
+    if (key === "api-key") {
+      current.apiKey = value;
+      saveConfig(current);
+      console.error(`API key saved: ${redactKey(value)}`);
+    } else if (key === "api-url") {
+      current.apiUrl = value;
+      saveConfig(current);
+      console.error(`API URL saved: ${value}`);
+    } else {
+      console.error(`Unknown config key: ${key}`);
+      console.error("Valid keys: api-key, api-url");
+      process.exit(1);
+    }
+  });
+  config.command("show").description("Show current configuration").action(() => {
+    const current = loadConfig();
+    const envKey = process.env.READER_API_KEY;
+    const envUrl = process.env.READER_API_URL;
+    console.log("Configuration:");
+    console.log("");
+    if (envKey) {
+      console.log(`  API Key:  ${redactKey(envKey)} (from READER_API_KEY env)`);
+    } else if (current.apiKey) {
+      console.log(`  API Key:  ${redactKey(current.apiKey)} (from ~/.reader/config.json)`);
+    } else {
+      console.log("  API Key:  not configured");
+    }
+    if (envUrl) {
+      console.log(`  API URL:  ${envUrl} (from READER_API_URL env)`);
+    } else if (current.apiUrl) {
+      console.log(`  API URL:  ${current.apiUrl} (from ~/.reader/config.json)`);
+    } else {
+      console.log("  API URL:  https://api.reader.dev (default)");
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("reader").description("Read the web for your AI agents. Powered by reader.dev.").version(version);
+registerConfigCommand(program);
+registerStatusCommand(program);
+registerScrapeCommand(program);
+registerCrawlCommand(program);
+registerCreditsCommand(program);
+program.parse();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vakra-dev/reader-cli",
+  "version": "0.1.0",
+  "description": "CLI for the Reader API - read the web for your AI agents",
+  "type": "module",
+  "bin": {
+    "reader": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "pretest": "tsup",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vakra-dev/reader-js": "^0.2.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.9"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vakra-dev/reader-cli.git"
+  },
+  "keywords": [
+    "reader",
+    "scraper",
+    "web",
+    "ai",
+    "cli",
+    "markdown",
+    "screenshot",
+    "crawl"
+  ]
+}