readable-md 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# readable-md
+
+[Readable](https://readable.md) on the command line. De-slop a draft,
+check text for AI slop, simplify it for a reader, shorten it or explain its
+jargon. Every number, date and fact is checked: a passage whose rewrite
+changes the meaning stays as written.
+
+```bash
+npm i -g readable-md        # installs the `readable` command
+npx readable-md deslop draft.md   # or run it once without installing
+```
+
+Node 20 or newer. No dependencies.
+
+## Sign in
+
+Create an API key at <https://readable.md/account>, then:
+
+```bash
+readable login              # paste the key (hidden), it is checked and saved
+readable usage              # plan and pages left this billing cycle
+```
+
+The key is saved to `~/.config/readable/config.json` (mode 0600, or under
+`$XDG_CONFIG_HOME`). `readable logout` removes it.
+
+## Tools
+
+```bash
+readable deslop draft.md > clean.md
+readable deslop draft.md --voice my-old-post.md     # edit toward your voice
+pbpaste | readable check                            # free, never rewrites
+readable simplify letter.pdf --audience patients
+readable simplify --url https://example.com/terms --level 1
+readable shorten report.md --length 0.4 --out short.md
+readable explain contract.md --audience customers --language Spanish
+```
+
+Input is a file (`.pdf` is uploaded), `-` or a pipe for stdin, or
+`--url <url>`. The Markdown result goes to stdout; the summary line and the
+share link go to stderr, so pipes get only the text.
+
+| Option | Tools | |
+| --- | --- | --- |
+| `--audience <id>` | simplify, explain | `general`, `customers`, `patients`, `second-language`, `young`, `newcomer`, `decision-maker`, `specialist` |
+| `--level <0-5>` | simplify, explain | 0 very simple, 2 plain (default), 5 expert |
+| `--reader <text>` | simplify, explain | describe the reader in your own words |
+| `--length <0.2-0.9>` | shorten | share of the original to keep (default 0.5) |
+| `--voice <file>` | deslop | a sample of your own writing |
+| `--language <name>` | all but check | write the result in this language |
+| `--json` | all | print the full JSON result |
+| `-o, --out <file>` | all | write the Markdown to a file |
+| `-q, --quiet` | all | no summary line or share link |
+| `--key <key>` | all | API key for this call |
+
+Plans count pages: a page is 500 words, and the CLI, the API, the MCP server
+and the app share them. Slop checks are free.
+
+## Use it from an AI assistant (MCP)
+
+```bash
+readable mcp
+```
+
+prints the MCP server URL (`https://readable.md/mcp`) and the config for
+Claude Code, Cursor and other clients, for example:
+
+```bash
+claude mcp add --transport http readable https://readable.md/mcp \
+  --header "Authorization: Bearer <key>"
+```
+
+## Environment
+
+| Variable | |
+| --- | --- |
+| `READABLE_API_KEY` | API key (used when `--key` is not given; overrides the saved key) |
+| `READABLE_API_URL` | API base URL, default `https://readable.md` |
+| `XDG_CONFIG_HOME` | where the config file lives, default `~/.config` |
+
+## Exit codes
+
+| Code | |
+| --- | --- |
+| 0 | done |
+| 1 | usage error (bad option, missing input, unreadable file) |
+| 2 | API or auth error (no key, invalid key, plan, bad source) |
+| 3 | quota or rate limit reached |

package/bin/readable.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { run } from "../src/commands.js";
+
+const { version } = JSON.parse(
+	readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+process.exitCode = await run(process.argv.slice(2), {
+	env: process.env,
+	fetch: globalThis.fetch,
+	stdout: process.stdout,
+	stderr: process.stderr,
+	stdin: process.stdin,
+	version,
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "readable-md",
+  "version": "1.0.0",
+  "description": "Readable on the command line: de-slop, slop-check, simplify, shorten and explain text.",
+  "type": "module",
+  "bin": {
+    "readable": "./bin/readable.mjs"
+  },
+  "files": ["bin", "src", "README.md"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. packages/cli"
+  },
+  "keywords": ["readable", "ai", "slop", "writing", "cli", "mcp"],
+  "homepage": "https://readable.md",
+  "license": "MIT"
+}

package/src/api.js

@@ -0,0 +1,120 @@
+/**
+ * HTTP calls to the Readable API, through an injectable fetch.
+ */
+
+export const EXIT = /** @type {const} */ ({
+	ok: 0,
+	usage: 1,
+	api: 2,
+	quota: 3,
+});
+
+export class ApiError extends Error {
+	/**
+	 * @param {string} code
+	 * @param {string} message
+	 * @param {number} [status]
+	 */
+	constructor(code, message, status) {
+		super(message);
+		this.name = "ApiError";
+		this.code = code;
+		this.status = status;
+	}
+
+	get exitCode() {
+		return this.code === "quota" || this.code === "rate"
+			? EXIT.quota
+			: EXIT.api;
+	}
+}
+
+/**
+ * @typedef {object} Client
+ * @property {string} baseUrl
+ * @property {string} key
+ * @property {typeof fetch} fetch
+ * @property {string} version
+ */
+
+/**
+ * @param {Client} client
+ * @param {string} path
+ * @param {RequestInit} [init]
+ */
+export async function request(client, path, init = {}) {
+	/** @type {Response} */
+	let response;
+	try {
+		response = await client.fetch(`${client.baseUrl}${path}`, {
+			...init,
+			headers: {
+				Authorization: `Bearer ${client.key}`,
+				Accept: "application/json",
+				"User-Agent": `readable-md/${client.version}`,
+				...(init.headers ?? {}),
+			},
+		});
+	} catch (caught) {
+		throw new ApiError(
+			"network",
+			`Could not reach ${client.baseUrl}: ${/** @type {Error} */ (caught).message}`,
+		);
+	}
+	const text = await response.text();
+	/** @type {any} */
+	let body = null;
+	try {
+		body = text ? JSON.parse(text) : null;
+	} catch {
+		// Not JSON: handled below.
+	}
+	if (!response.ok) {
+		const error = body?.error;
+		if (error && typeof error.message === "string")
+			throw new ApiError(
+				String(error.code ?? "error"),
+				error.message,
+				response.status,
+			);
+		throw new ApiError(
+			response.status === 401 ? "unauthorized" : "http",
+			`${response.status} ${response.statusText || "error"} from ${path}`.trim(),
+			response.status,
+		);
+	}
+	if (body === null)
+		throw new ApiError("invalid_response", `No JSON from ${path}.`);
+	return body;
+}
+
+/** @param {Client} client */
+export function getUsage(client) {
+	return request(client, "/api/v1/usage");
+}
+
+/**
+ * @param {Client} client
+ * @param {Record<string, string | number>} fields
+ * @param {{ text?: string, pdf?: { name: string, bytes: Uint8Array } }} input
+ */
+export function transform(client, fields, input) {
+	if (input.pdf) {
+		const form = new FormData();
+		for (const [name, value] of Object.entries(fields))
+			form.set(name, String(value));
+		form.set(
+			"file",
+			new Blob([input.pdf.bytes], { type: "application/pdf" }),
+			input.pdf.name,
+		);
+		return request(client, "/api/v1/transform", { method: "POST", body: form });
+	}
+	return request(client, "/api/v1/transform", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(
+			input.text === undefined ? fields : { ...fields, text: input.text },
+		),
+	});
+}

package/src/args.js

@@ -0,0 +1,209 @@
+/**
+ * Argument parsing. Pure: argv in, a command description out.
+ */
+import { parseArgs } from "node:util";
+
+export class UsageError extends Error {
+	/** @param {string} message */
+	constructor(message) {
+		super(message);
+		this.name = "UsageError";
+	}
+}
+
+/** CLI command → API tool id. */
+export const TOOL_COMMANDS = /** @type {const} */ ({
+	deslop: "deslop",
+	check: "slop-check",
+	simplify: "simplify",
+	shorten: "shorten",
+	explain: "explain",
+});
+
+export const OTHER_COMMANDS = ["login", "logout", "usage", "tools", "mcp"];
+
+export const AUDIENCES = [
+	"general",
+	"customers",
+	"patients",
+	"second-language",
+	"young",
+	"newcomer",
+	"decision-maker",
+	"specialist",
+];
+
+/** @typedef {keyof typeof TOOL_COMMANDS} ToolCommand */
+
+/**
+ * @typedef {object} Parsed
+ * @property {string | null} command
+ * @property {boolean} help
+ * @property {boolean} version
+ * @property {string | undefined} key
+ * @property {string | undefined} input
+ * @property {Record<string, string | boolean | undefined>} options
+ */
+
+const COMMON = {
+	help: { type: "boolean", short: "h" },
+	version: { type: "boolean", short: "v" },
+	key: { type: "string" },
+};
+
+const TOOL_OPTIONS = {
+	...COMMON,
+	url: { type: "string" },
+	json: { type: "boolean" },
+	out: { type: "string", short: "o" },
+	quiet: { type: "boolean", short: "q" },
+};
+
+const WRITING_OPTIONS = { ...TOOL_OPTIONS, language: { type: "string" } };
+
+/** @type {Record<string, Record<string, { type: "string" | "boolean", short?: string }>>} */
+const OPTIONS = {
+	deslop: {
+		...WRITING_OPTIONS,
+		voice: { type: "string" },
+		"no-voice-profile": { type: "boolean" },
+	},
+	// Slop check never rewrites, so it takes no output language.
+	check: TOOL_OPTIONS,
+	simplify: {
+		...WRITING_OPTIONS,
+		audience: { type: "string" },
+		level: { type: "string" },
+		reader: { type: "string" },
+	},
+	shorten: { ...WRITING_OPTIONS, length: { type: "string" } },
+	explain: {
+		...WRITING_OPTIONS,
+		audience: { type: "string" },
+		level: { type: "string" },
+		reader: { type: "string" },
+	},
+	login: { ...COMMON },
+	logout: { ...COMMON },
+	usage: { ...COMMON, json: { type: "boolean" } },
+	tools: { ...COMMON },
+	mcp: { ...COMMON },
+};
+
+/** @param {string} name */
+export function isToolCommand(name) {
+	return Object.hasOwn(TOOL_COMMANDS, name);
+}
+
+/**
+ * @param {string[]} argv arguments after `readable`
+ * @returns {Parsed}
+ */
+export function parse(argv) {
+	const [first, ...rest] = argv;
+	if (first === undefined || first.startsWith("-")) {
+		const { values } = safeParse(argv, COMMON, false);
+		return {
+			command: null,
+			help: Boolean(values.help) || first === undefined,
+			version: Boolean(values.version),
+			key: undefined,
+			input: undefined,
+			options: {},
+		};
+	}
+	if (first === "help")
+		return {
+			command: rest[0] ?? null,
+			help: true,
+			version: false,
+			key: undefined,
+			input: undefined,
+			options: {},
+		};
+	const spec = OPTIONS[first];
+	if (!spec)
+		throw new UsageError(
+			`Unknown command "${first}". Run \`readable --help\` for the list.`,
+		);
+	const tool = isToolCommand(first);
+	const { values, positionals } = safeParse(rest, spec, tool);
+	if (positionals.length > (tool ? 1 : 0))
+		throw new UsageError(`Unexpected argument "${positionals[tool ? 1 : 0]}".`);
+	const { help, version, key, ...options } = values;
+	const parsed = {
+		command: first,
+		help: Boolean(help),
+		version: Boolean(version),
+		key: /** @type {string | undefined} */ (key),
+		input: positionals[0],
+		options: /** @type {Record<string, string | boolean | undefined>} */ (
+			options
+		),
+	};
+	if (tool && !parsed.help) validateToolOptions(parsed);
+	return parsed;
+}
+
+/**
+ * @param {string[]} args
+ * @param {Record<string, { type: "string" | "boolean", short?: string }>} options
+ * @param {boolean} allowPositionals
+ */
+function safeParse(args, options, allowPositionals) {
+	try {
+		return parseArgs({ args, options, allowPositionals, strict: true });
+	} catch (caught) {
+		const message = /** @type {Error} */ (caught).message
+			.split(". To specify")[0]
+			.replace(/\.$/, "");
+		throw new UsageError(`${message}. See \`readable --help\`.`);
+	}
+}
+
+/** @param {Parsed} parsed */
+function validateToolOptions(parsed) {
+	const { options } = parsed;
+	if (parsed.input && options.url)
+		throw new UsageError("Pass a file or --url, not both.");
+	if (
+		typeof options.audience === "string" &&
+		!AUDIENCES.includes(options.audience)
+	)
+		throw new UsageError(
+			`Unknown audience "${options.audience}". Use one of ${AUDIENCES.join(", ")}.`,
+		);
+	if (options.level !== undefined) {
+		const level = Number(options.level);
+		if (!Number.isInteger(level) || level < 0 || level > 5)
+			throw new UsageError("--level must be a whole number from 0 to 5.");
+	}
+	if (options.length !== undefined) {
+		const length = Number(options.length);
+		if (!Number.isFinite(length) || length < 0.2 || length > 0.9)
+			throw new UsageError(
+				"--length must be a share of the original from 0.2 to 0.9 (0.5 = half).",
+			);
+	}
+}
+
+/**
+ * The JSON body for `POST /api/v1/transform`, without the text or file.
+ * @param {ToolCommand} command
+ * @param {Record<string, string | boolean | undefined>} options
+ * @param {{ voice?: string }} [extra]
+ */
+export function transformFields(command, options, extra = {}) {
+	/** @type {Record<string, string | number | boolean>} */
+	const body = { tool: TOOL_COMMANDS[command] };
+	if (typeof options.url === "string") body.url = options.url;
+	if (typeof options.audience === "string") body.audience = options.audience;
+	if (options.level !== undefined) body.level = Number(options.level);
+	if (typeof options.reader === "string") body.reader = options.reader;
+	if (options.length !== undefined) body.length = Number(options.length);
+	if (typeof options.language === "string")
+		body.output_language = options.language;
+	if (extra.voice) body.voice = extra.voice.slice(0, 6_000);
+	if (options["no-voice-profile"]) body.voice_profile = false;
+	return body;
+}

package/src/commands.js

@@ -0,0 +1,460 @@
+/**
+ * The commands. `run(argv, io)` returns an exit code and never calls
+ * process.exit, so it can be tested with a fake io and fetch.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { ApiError, EXIT, getUsage, transform } from "./api.js";
+import {
+	AUDIENCES,
+	isToolCommand,
+	parse,
+	transformFields,
+	UsageError,
+} from "./args.js";
+import {
+	configPath,
+	looksLikeKey,
+	readConfig,
+	removeConfig,
+	resolveApiUrl,
+	resolveKey,
+	writeConfig,
+} from "./config.js";
+
+/**
+ * @typedef {object} Io
+ * @property {NodeJS.ProcessEnv} env
+ * @property {typeof fetch} fetch
+ * @property {{ write(chunk: string): unknown }} stdout
+ * @property {{ write(chunk: string): unknown }} stderr
+ * @property {NodeJS.ReadableStream & { isTTY?: boolean, setRawMode?: (mode: boolean) => unknown }} stdin
+ * @property {string} version
+ */
+
+/** Keep in step with `src/lib/tools.ts`. */
+export const TOOL_LIST = [
+	{
+		command: "deslop",
+		summary:
+			"Strip filler, hedging, recap paragraphs and stock phrases from AI-written text, optionally toward your own voice.",
+	},
+	{
+		command: "check",
+		summary:
+			"Score a text and mark the sentences that read as machine-written. No rewrite, and free.",
+	},
+	{
+		command: "simplify",
+		summary:
+			"Rewrite to the reading level of the person who has to understand it, and explain the terms.",
+	},
+	{
+		command: "shorten",
+		summary:
+			"Cut a document to the length you set without dropping a number, date, condition or deadline.",
+	},
+	{
+		command: "explain",
+		summary:
+			"Keep the text as it is and add a short plain explanation next to each piece of jargon.",
+	},
+];
+
+const MAIN_HELP = `readable: make text readable from the command line (https://readable.md)
+
+Usage
+  readable <tool> [file|-] [options]
+  readable <command> [options]
+
+Tools
+${TOOL_LIST.map((tool) => `  ${tool.command.padEnd(10)}${tool.summary}`).join("\n")}
+
+Commands
+  login     Save an API key (from https://readable.md/account)
+  logout    Remove the saved key
+  usage     Show your plan and the pages left this billing cycle
+  tools     List the tools
+  mcp       Show how to add Readable to Claude Code, Cursor and other MCP clients
+
+Options
+  --key <key>   API key (else READABLE_API_KEY, else the saved key)
+  -h, --help    Help for a command: readable deslop --help
+  -v, --version Print the version
+
+Examples
+  readable deslop draft.md > clean.md
+  pbpaste | readable check
+  readable simplify --url https://example.com/terms --audience customers
+`;
+
+const TOOL_HELP = {
+	common: `Input
+  [file]              A text, Markdown or PDF file; "-" or a pipe reads stdin
+  --url <url>         A web page or PDF to fetch instead
+
+Output
+  --json              Print the full JSON result
+  -o, --out <file>    Write the Markdown to a file instead of stdout
+  -q, --quiet         Do not print the summary line and share link
+  --key <key>         API key
+
+The result's Markdown goes to stdout; the summary line and share link go to
+stderr, so piping works: readable deslop draft.md | pbcopy`,
+	deslop: `  --voice <file>      A sample of your own writing to edit toward
+                      (replaces your saved voice profile for this run)
+  --no-voice-profile  Do not edit toward your saved voice profile
+  --language <name>   Write the result in this language`,
+	check: "",
+	simplify: `  --audience <id>     ${AUDIENCES.join(", ")}
+  --level <0-5>       0 very simple … 2 plain (default) … 5 expert
+  --reader <text>     Describe the reader in your own words
+  --language <name>   Write the result in this language`,
+	shorten: `  --length <0.2-0.9>  Share of the original to keep (default 0.5)
+  --language <name>   Write the result in this language`,
+	explain: `  --audience <id>     ${AUDIENCES.join(", ")}
+  --level <0-5>       Level of the explanations (default 2)
+  --reader <text>     Describe the reader in your own words
+  --language <name>   Write the result in this language`,
+};
+
+const COMMAND_HELP = {
+	login: `Usage: readable login [--key <key>]
+
+Saves an API key after checking it. Without --key it asks for the key
+(input hidden) or reads it from stdin. Keys: https://readable.md/account`,
+	logout: "Usage: readable logout\n\nRemoves the saved key.",
+	usage: `Usage: readable usage [--json]
+
+Shows your plan and the pages used this billing cycle. The app, the API,
+the MCP server and this CLI share the same pages; a page is 500 words.`,
+	tools: "Usage: readable tools\n\nLists the tools.",
+	mcp: `Usage: readable mcp
+
+Prints the MCP server URL and config for Claude Code, Cursor and other
+clients.`,
+};
+
+/** @param {string | null} command */
+export function helpFor(command) {
+	if (command && isToolCommand(command)) {
+		const tool = TOOL_LIST.find((entry) => entry.command === command);
+		const specific = TOOL_HELP[/** @type {keyof typeof TOOL_HELP} */ (command)];
+		return `Usage: readable ${command} [file|-] [options]
+
+${tool?.summary}
+
+${specific ? `Options\n${specific}\n\n` : ""}${TOOL_HELP.common}
+`;
+	}
+	if (command && command in COMMAND_HELP)
+		return `${COMMAND_HELP[/** @type {keyof typeof COMMAND_HELP} */ (command)]}\n`;
+	return MAIN_HELP;
+}
+
+/**
+ * @param {NodeJS.ReadableStream} stream
+ * @returns {Promise<string>}
+ */
+export async function readAll(stream) {
+	const chunks = [];
+	for await (const chunk of stream)
+		chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Ask for a secret on a terminal without echoing it.
+ * @param {Io} io
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+export function promptHidden(io, question) {
+	const { stdin } = io;
+	io.stderr.write(question);
+	return new Promise((resolve, reject) => {
+		let value = "";
+		stdin.setRawMode?.(true);
+		stdin.resume();
+		stdin.setEncoding?.("utf8");
+		/** @param {string} chunk */
+		const onData = (chunk) => {
+			for (const char of chunk) {
+				if (char === "\r" || char === "\n" || char === "\u0004") {
+					finish();
+					resolve(value);
+					return;
+				}
+				if (char === "\u0003") {
+					finish();
+					reject(new UsageError("Cancelled."));
+					return;
+				}
+				if (char === "\u007f" || char === "\b") value = value.slice(0, -1);
+				else value += char;
+			}
+		};
+		const finish = () => {
+			stdin.removeListener("data", onData);
+			stdin.setRawMode?.(false);
+			stdin.pause();
+			io.stderr.write("\n");
+		};
+		stdin.on("data", onData);
+	});
+}
+
+/**
+ * @param {Io} io
+ * @param {string | undefined} flag
+ */
+async function client(io, flag) {
+	const config = await readConfig(io.env);
+	const key = resolveKey(flag, io.env, config);
+	if (!key)
+		throw new ApiError(
+			"unauthorized",
+			"No API key. Run `readable login`, set READABLE_API_KEY or pass --key. Keys: https://readable.md/account",
+		);
+	return {
+		baseUrl: resolveApiUrl(io.env, config),
+		key: key.trim(),
+		fetch: io.fetch,
+		version: io.version,
+	};
+}
+
+/**
+ * Where the text comes from: a file, stdin or --url.
+ * @param {Io} io
+ * @param {string | undefined} input
+ * @param {Record<string, string | boolean | undefined>} options
+ * @returns {Promise<{ text?: string, pdf?: { name: string, bytes: Uint8Array } }>}
+ */
+export async function readInput(io, input, options) {
+	if (options.url) return {};
+	if (input === "-" || (!input && !io.stdin.isTTY)) {
+		const text = await readAll(io.stdin);
+		if (!text.trim()) throw new UsageError("Nothing on stdin.");
+		return { text };
+	}
+	if (!input)
+		throw new UsageError(
+			"Give a file, pipe text in, or pass --url. Example: readable deslop draft.md",
+		);
+	let bytes;
+	try {
+		bytes = await readFile(input);
+	} catch {
+		throw new UsageError(`Cannot read ${input}.`);
+	}
+	if (extname(input).toLowerCase() === ".pdf")
+		return { pdf: { name: basename(input), bytes: new Uint8Array(bytes) } };
+	return { text: bytes.toString("utf8") };
+}
+
+/**
+ * @param {Io} io
+ * @param {import("./args.js").Parsed} parsed
+ */
+async function runTool(io, parsed) {
+	const { options } = parsed;
+	const input = await readInput(io, parsed.input, options);
+	let voice;
+	if (typeof options.voice === "string") {
+		try {
+			voice = await readFile(options.voice, "utf8");
+		} catch {
+			throw new UsageError(`Cannot read the voice sample ${options.voice}.`);
+		}
+	}
+	const fields = transformFields(
+		/** @type {import("./args.js").ToolCommand} */ (parsed.command),
+		options,
+		{ voice },
+	);
+	const result = await transform(await client(io, parsed.key), fields, input);
+	if (options.json) {
+		io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return EXIT.ok;
+	}
+	const markdown = String(result.markdown ?? "");
+	if (typeof options.out === "string") {
+		await writeFile(options.out, markdown);
+		if (!options.quiet) io.stderr.write(`Wrote ${options.out}\n`);
+	} else io.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
+	if (!options.quiet) {
+		if (result.summary) io.stderr.write(`${result.summary}\n`);
+		if (result.share_url) io.stderr.write(`${result.share_url}\n`);
+	}
+	return EXIT.ok;
+}
+
+/**
+ * @param {Io} io
+ * @param {import("./args.js").Parsed} parsed
+ */
+async function login(io, parsed) {
+	let key = parsed.key;
+	if (!key) {
+		if (io.stdin.isTTY) {
+			io.stderr.write(
+				"Create a key at https://readable.md/account, then paste it here.\n",
+			);
+			key = await promptHidden(io, "API key: ");
+		} else key = (await readAll(io.stdin)).split(/\r?\n/)[0];
+	}
+	key = (key ?? "").trim();
+	if (!key) throw new UsageError("No key given.");
+	if (!looksLikeKey(key))
+		throw new UsageError(
+			"That is not a Readable API key. Keys start with rdbl_ followed by 64 hex characters.",
+		);
+	const config = await readConfig(io.env);
+	const usage = await getUsage({
+		baseUrl: resolveApiUrl(io.env, config),
+		key,
+		fetch: io.fetch,
+		version: io.version,
+	});
+	const path = await writeConfig(io.env, { ...config, api_key: key });
+	io.stderr.write(
+		`Logged in (${usage.plan ?? "unknown"} plan). Key saved to ${path}\n`,
+	);
+	return EXIT.ok;
+}
+
+/** @param {Io} io */
+async function logout(io) {
+	const config = await readConfig(io.env);
+	if (!config.api_key) {
+		io.stderr.write("No saved key.\n");
+		return EXIT.ok;
+	}
+	const { api_key: _removed, ...rest } = config;
+	if (Object.keys(rest).length) await writeConfig(io.env, rest);
+	else await removeConfig(io.env);
+	io.stderr.write(`Removed the key from ${configPath(io.env)}\n`);
+	return EXIT.ok;
+}
+
+/** @param {unknown} value */
+const count = (value) =>
+	typeof value === "number" ? value.toLocaleString("en") : "unlimited";
+
+/**
+ * @param {Io} io
+ * @param {import("./args.js").Parsed} parsed
+ */
+async function usage(io, parsed) {
+	const data = await getUsage(await client(io, parsed.key));
+	if (parsed.options.json) {
+		io.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+		return EXIT.ok;
+	}
+	const lines = [
+		`Plan:       ${data.plan}`,
+		`Pages:      ${count(data.pages_used)} of ${count(data.pages_limit)} used this billing cycle`,
+	];
+	if (data.renews_at)
+		lines.push(
+			`Renews:     ${new Date(data.renews_at).toISOString().slice(0, 10)}`,
+		);
+	if (data.words_per_page)
+		lines.push(
+			`A page:     ${count(data.words_per_page)} words, up to ${count(data.pages_per_run)} pages at once`,
+		);
+	io.stdout.write(`${lines.join("\n")}\n`);
+	return EXIT.ok;
+}
+
+/** @param {Io} io */
+function tools(io) {
+	io.stdout.write(
+		`${TOOL_LIST.map((tool) => `${tool.command.padEnd(10)}${tool.summary}`).join("\n")}\n`,
+	);
+	return EXIT.ok;
+}
+
+/** @param {string} baseUrl */
+export function mcpText(baseUrl) {
+	const url = `${baseUrl}/mcp`;
+	const cursor = {
+		mcpServers: {
+			readable: { url, headers: { Authorization: "Bearer <key>" } },
+		},
+	};
+	const generic = {
+		mcpServers: {
+			readable: {
+				type: "http",
+				url,
+				headers: { Authorization: "Bearer <key>" },
+			},
+		},
+	};
+	return `Readable MCP server (Streamable HTTP): ${url}
+Authenticate with an API key from https://readable.md/account as
+"Authorization: Bearer <key>".
+
+Claude Code
+  claude mcp add --transport http readable ${url} --header "Authorization: Bearer <key>"
+
+Cursor (~/.cursor/mcp.json)
+${JSON.stringify(cursor, null, 2)}
+
+Other clients (VS Code, Claude Desktop via config, Windsurf, …)
+${JSON.stringify(generic, null, 2)}
+
+Tools: deslop, slop_check, simplify, shorten, explain.
+`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {Io} io
+ * @returns {Promise<number>}
+ */
+export async function run(argv, io) {
+	try {
+		const parsed = parse(argv);
+		if (parsed.version) {
+			io.stdout.write(`${io.version}\n`);
+			return EXIT.ok;
+		}
+		if (parsed.help) {
+			io.stdout.write(helpFor(parsed.command));
+			return EXIT.ok;
+		}
+		switch (parsed.command) {
+			case "login":
+				return await login(io, parsed);
+			case "logout":
+				return await logout(io);
+			case "usage":
+				return await usage(io, parsed);
+			case "tools":
+				return tools(io);
+			case "mcp":
+				io.stdout.write(
+					mcpText(resolveApiUrl(io.env, await readConfig(io.env))),
+				);
+				return EXIT.ok;
+			default:
+				return await runTool(io, parsed);
+		}
+	} catch (caught) {
+		if (caught instanceof UsageError) {
+			io.stderr.write(`readable: ${caught.message}\n`);
+			return EXIT.usage;
+		}
+		if (caught instanceof ApiError) {
+			io.stderr.write(`readable: ${caught.message}\n`);
+			return caught.exitCode;
+		}
+		io.stderr.write(
+			`readable: ${/** @type {Error} */ (caught)?.message ?? caught}\n`,
+		);
+		return EXIT.usage;
+	}
+}

package/src/config.js

@@ -0,0 +1,81 @@
+/**
+ * Config file and environment: where the key and the API live.
+ */
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_API_URL = "https://readable.md";
+
+/**
+ * @typedef {object} Config
+ * @property {string} [api_key]
+ * @property {string} [api_url]
+ */
+
+/** @param {NodeJS.ProcessEnv} env */
+export function configPath(env) {
+	const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return join(base, "readable", "config.json");
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Promise<Config>}
+ */
+export async function readConfig(env) {
+	try {
+		const parsed = JSON.parse(await readFile(configPath(env), "utf8"));
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Write the config readable by its owner only.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {Config} config
+ */
+export async function writeConfig(env, config) {
+	const path = configPath(env);
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, {
+		mode: 0o600,
+	});
+	await chmod(path, 0o600);
+	return path;
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export async function removeConfig(env) {
+	const path = configPath(env);
+	await rm(path, { force: true });
+	return path;
+}
+
+/**
+ * The key to use: `--key`, then READABLE_API_KEY, then the config file.
+ * @param {string | undefined} flag
+ * @param {NodeJS.ProcessEnv} env
+ * @param {Config} config
+ */
+export function resolveKey(flag, env, config) {
+	return flag || env.READABLE_API_KEY || config.api_key || undefined;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {Config} config
+ */
+export function resolveApiUrl(env, config) {
+	return (env.READABLE_API_URL || config.api_url || DEFAULT_API_URL).replace(
+		/\/+$/,
+		"",
+	);
+}
+
+/** @param {string} key */
+export function looksLikeKey(key) {
+	return /^rdbl_[0-9a-f]{64}$/i.test(key.trim());
+}