@letterstory/cli 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# `@letterstory/cli`
+
+Spin up and manage Letterstory **phantom blogs** from your terminal. The CLI is a thin
+client over the Letterstory MCP endpoint (`POST /api/mcp`) — it wraps the same tool
+manifest an agent sees, so it never drifts from the API.
+
+## Install
+
+The CLI is plain ESM with **zero dependencies** and needs no build step (Node ≥ 20).
+
+```bash
+# from a checkout of this repo
+cd cli
+npm link          # puts `letterstory` on your PATH
+# …or run it directly without linking:
+node cli/bin/letterstory.mjs --help
+```
+
+## Authenticate
+
+You need a Letterstory API key (starts with `lb_`) with the `deployment:read` and
+`deployment:write` capabilities — mint one in the app under **Settings → API keys**.
+Add `deployment:domain` too if you plan to buy custom domains.
+
+```bash
+letterstory login --key lb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# points at https://app.letterstory.com by default; override with --url
+```
+
+Credentials resolve from `--key`/`--url` flags, then `LETTERSTORY_API_KEY` /
+`LETTERSTORY_API_URL`, then `~/.letterstory/config.json` (written by `login`, mode 600).
+
+## Spin up a blog
+
+```bash
+# create a blog and wait until it's live (polls for you)
+letterstory deploy create --name "My Blog" --theme gazette
+
+#   Created deployment 7c19c7… (provisioning)
+#     … provisioning · building
+#     … provisioning · connecting
+#   ✓ Live at https://my-blog-7c19c7.letterstory-staging.com
+
+letterstory deploy list
+letterstory deploy get <deployment-id>
+letterstory deploy rebuild <deployment-id>      # after publishing new articles
+letterstory deploy delete <deployment-id> --yes
+```
+
+Pass `--no-wait` to return immediately and poll later with `deploy get`.
+
+## Custom domains
+
+```bash
+letterstory domain check myblog.com                       # price it (no charge)
+letterstory domain buy <deployment-id> myblog.com --yes   # buys + attaches (spends money)
+```
+
+## Anything else
+
+Every Letterstory tool is reachable, not just the deployment ones:
+
+```bash
+letterstory tools                                  # list all tools
+letterstory call list_articles --args '{"limit":5}'
+letterstory call ingest_article --args '{"title":"…","content":"…"}'
+```
+
+## Global flags
+
+| Flag        | Meaning                                |
+| ----------- | -------------------------------------- |
+| `--json`    | Machine-readable output                |
+| `--url`     | Override the API base URL for one call |
+| `--key`     | Override the API key for one call      |
+| `--help`    | Show usage                             |
+| `--version` | Print the CLI version                  |

package/bin/letterstory.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Thin entry point: hand argv to run() and translate its exit code to the process.
+// All logic lives in ../lib so it stays unit-testable without spawning a process.
+import { run } from "../lib/cli.mjs";
+
+run(process.argv.slice(2))
+	.then((code) => process.exit(code))
+	.catch((err) => {
+		// A non-CliError escaped run() — a real bug. Show the stack.
+		console.error(err);
+		process.exit(1);
+	});

package/lib/cli.mjs

@@ -0,0 +1,152 @@
+// Argument parsing, help, and command routing for the Letterstory CLI. `run(argv)`
+// is the single entry the bin and the tests both call; it returns an exit code and
+// never throws for user-facing problems (those become a printed CliError + code 1).
+
+import { LetterstoryClient, CliError, resolveConfig } from "./client.mjs";
+import { cmdLogin, cmdLogout, cmdConfig, cmdTools, cmdCall, cmdDeploy, cmdDomain } from "./commands.mjs";
+
+// Keep in sync with cli/package.json.
+export const VERSION = "0.1.0";
+
+// Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
+// can't accidentally swallow the id as --json's value.
+const BOOLEAN_FLAGS = new Set(["json", "yes", "no-wait", "help", "version"]);
+
+// Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
+/**
+ * @param {string[]} argv
+ * @returns {{ positionals: string[], flags: Record<string, string | boolean> }}
+ */
+export function parseArgs(argv) {
+	const positionals = [];
+	const flags = {};
+	for (let i = 0; i < argv.length; i++) {
+		const tok = argv[i];
+		if (!tok.startsWith("--")) {
+			positionals.push(tok);
+			continue;
+		}
+		const eq = tok.indexOf("=");
+		if (eq !== -1) {
+			flags[tok.slice(2, eq)] = tok.slice(eq + 1);
+			continue;
+		}
+		const name = tok.slice(2);
+		const next = argv[i + 1];
+		if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) {
+			flags[name] = true;
+		} else {
+			flags[name] = next;
+			i++;
+		}
+	}
+	return { positionals, flags };
+}
+
+function str(v) {
+	return typeof v === "string" ? v : undefined;
+}
+
+export const HELP = `letterstory — spin up and manage Letterstory phantom blogs from your terminal
+
+Usage:
+  letterstory <command> [args] [--flags]
+
+Auth:
+  login --key <lb_…> [--url <url>]   Save your API key (default url: https://app.letterstory.com)
+  logout                             Forget saved credentials
+  config                             Show the resolved url + key (masked)
+
+Phantom blogs:
+  deploy create --name <name> [--description <text>] [--theme <theme>]
+                [--collection <uuid>] [--no-wait]   Create a blog; waits until it's live
+  deploy list [--limit <n>]                          List your blogs
+  deploy get <deployment-id>                         Show one blog's status + URL
+  deploy rebuild <deployment-id>                     Rebuild to pull in newly-published content
+  deploy diagnostics <deployment-id>                 Why is my blog empty? snapshot
+  deploy delete <deployment-id> --yes                Tear down the blog (keeps the collection)
+
+Custom domains:
+  domain check <domain>                              Price a domain (read-only, no charge)
+  domain buy <deployment-id> <domain> --yes          Buy + attach a domain (spends money)
+
+Anything else:
+  tools                              List every tool this server exposes
+  call <tool> [--args '<json>'] [--flag value …]     Call any tool directly
+
+Global flags:
+  --json          Machine-readable output
+  --url <url>     Override the API base URL for this invocation
+  --key <lb_…>    Override the API key for this invocation
+  --help          Show this help
+  --version       Print the CLI version
+
+Credentials resolve from --key/--url, then LETTERSTORY_API_KEY / LETTERSTORY_API_URL,
+then ~/.letterstory/config.json.`;
+
+const CLIENT_COMMANDS = {
+	login: cmdLogin,
+	logout: cmdLogout,
+	config: cmdConfig,
+	tools: cmdTools,
+	call: cmdCall,
+	deploy: cmdDeploy,
+	domain: cmdDomain,
+};
+
+// LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an
+// end-to-end test) tune the deploy-create wait loop without editing code. Bad or
+// absent values fall back to the shipping defaults (4s interval, 90 polls ≈ 6 min).
+function envInt(name, fallback) {
+	const n = Number(process.env[name]);
+	return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+export function defaultIo() {
+	return {
+		log: (m) => process.stdout.write(`${m}\n`),
+		error: (m) => process.stderr.write(`${m}\n`),
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		pollIntervalMs: envInt("LETTERSTORY_POLL_INTERVAL_MS", 4000),
+		maxPolls: envInt("LETTERSTORY_MAX_POLLS", 90),
+	};
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ log: (m: string) => void, error: (m: string) => void, sleep: (ms: number) => Promise<void>, pollIntervalMs?: number, maxPolls?: number }} [io]
+ * @returns {Promise<number>} process exit code
+ */
+export async function run(argv, io = defaultIo()) {
+	const { positionals, flags } = parseArgs(argv);
+	const command = positionals[0];
+
+	if (flags.version || command === "version") {
+		io.log(VERSION);
+		return 0;
+	}
+	if (!command || command === "help" || flags.help) {
+		io.log(HELP);
+		return 0;
+	}
+
+	const handler = CLIENT_COMMANDS[command];
+	if (!handler) {
+		io.error(`Unknown command: ${command}`);
+		io.error(`Run \`letterstory help\` for usage.`);
+		return 1;
+	}
+
+	try {
+		const config = resolveConfig({ url: str(flags.url), key: str(flags.key) });
+		const client = new LetterstoryClient({ url: config.url, key: config.key });
+		const ctx = { client, config, positionals: positionals.slice(1), flags, io };
+		return await handler(ctx);
+	} catch (err) {
+		if (err instanceof CliError) {
+			io.error(`Error: ${err.message}`);
+			return 1;
+		}
+		throw err;
+	}
+}

package/lib/client.mjs

@@ -0,0 +1,137 @@
+// The Letterstory CLI's transport: a thin JSON-RPC client over the MCP endpoint
+// (POST /api/mcp), plus config resolution. The CLI wraps the same tool manifest an
+// agent sees, so it stays in sync with the server by construction — there is no
+// second copy of the surface here, only ergonomic wrappers around tools/call.
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+export const DEFAULT_API_URL = "https://app.letterstory.com";
+
+// A CliError is a message we've already made human-friendly; the entry point prints
+// its message and exits 1 without a stack trace. Anything else is a real bug.
+export class CliError extends Error {}
+
+// Config lives at ~/.letterstory/config.json. LETTERSTORY_CONFIG_HOME overrides the
+// home dir (the tests point it at a temp dir so they never touch the real file).
+export function configPath() {
+	const home = process.env.LETTERSTORY_CONFIG_HOME || homedir();
+	return join(home, ".letterstory", "config.json");
+}
+
+export function readConfigFile() {
+	const path = configPath();
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+// The file holds an lb_ API key, so it's written owner-only (0600) and the mode is
+// re-asserted in case it pre-existed with looser bits.
+export function writeConfigFile(config) {
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+	chmodSync(path, 0o600);
+	return path;
+}
+
+export function clearConfigFile() {
+	const path = configPath();
+	if (existsSync(path)) rmSync(path);
+	return path;
+}
+
+// Precedence: explicit flags > env > config file > built-in default. Returns which
+// source the key came from so `config` can show it. The URL defaults to prod.
+export function resolveConfig({ url, key } = {}) {
+	const file = readConfigFile();
+	const keySource = key ? "flag" : process.env.LETTERSTORY_API_KEY ? "env" : file.key ? "file" : "none";
+	return {
+		url: url || process.env.LETTERSTORY_API_URL || file.url || DEFAULT_API_URL,
+		key: key || process.env.LETTERSTORY_API_KEY || file.key || null,
+		keySource,
+	};
+}
+
+export class LetterstoryClient {
+	constructor({ url, key, fetchImpl } = {}) {
+		this.url = (url || DEFAULT_API_URL).replace(/\/+$/, "");
+		this.key = key || null;
+		this.fetch = fetchImpl || globalThis.fetch;
+	}
+
+	get mcpEndpoint() {
+		return `${this.url}/api/mcp`;
+	}
+
+	// Unauthenticated discovery (GET /api/mcp): tool names + descriptions, no schema.
+	// Lets `letterstory tools` work before you've logged in.
+	async discover() {
+		let res;
+		try {
+			res = await this.fetch(this.mcpEndpoint, { headers: { accept: "application/json" } });
+		} catch (err) {
+			throw new CliError(`Could not reach ${this.mcpEndpoint}: ${err.message}`);
+		}
+		if (!res.ok) throw new CliError(`Discovery failed (HTTP ${res.status}) at ${this.mcpEndpoint}`);
+		return res.json();
+	}
+
+	// One JSON-RPC round trip. The MCP route is stateless per POST, so tools/call
+	// needs no prior initialize handshake.
+	async rpc(method, params) {
+		if (!this.key) {
+			throw new CliError("Not logged in. Run `letterstory login --key <lb_…>` or set LETTERSTORY_API_KEY.");
+		}
+		let res;
+		try {
+			res = await this.fetch(this.mcpEndpoint, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json",
+					"x-integrations-key": this.key,
+				},
+				body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+			});
+		} catch (err) {
+			throw new CliError(`Could not reach ${this.mcpEndpoint}: ${err.message}`);
+		}
+		// Auth failures come back as a plain HTTP error, not a JSON-RPC envelope.
+		if (res.status === 401 || res.status === 403) {
+			throw new CliError(`Authentication failed (HTTP ${res.status}). Check your API key and its capabilities.`);
+		}
+		const body = await res.json().catch(() => null);
+		if (!body) throw new CliError(`Unexpected non-JSON response (HTTP ${res.status}) from ${this.mcpEndpoint}`);
+		if (body.error) {
+			const detail = body.error.data ? `: ${JSON.stringify(body.error.data)}` : "";
+			throw new CliError(`${body.error.message}${detail}`);
+		}
+		return body.result;
+	}
+
+	async listTools() {
+		const result = await this.rpc("tools/list", {});
+		return result?.tools ?? [];
+	}
+
+	// Invoke a tool and unwrap the MCP content envelope. A tool-level failure arrives
+	// as { isError: true, content:[{text}] } on HTTP 200 (e.g. a capability the key
+	// lacks, or a validation error) — surface that text as a CliError.
+	async callTool(name, args = {}) {
+		const result = await this.rpc("tools/call", { name, arguments: args });
+		const text = result?.content?.[0]?.text ?? "";
+		if (result?.isError) throw new CliError(text || `Tool ${name} failed`);
+		if (!text) return {};
+		try {
+			return JSON.parse(text);
+		} catch {
+			return text; // a few tools return a bare string
+		}
+	}
+}

package/lib/commands.mjs

@@ -0,0 +1,325 @@
+// Command handlers. Each takes a ctx { client, positionals, flags, io } and returns
+// a process exit code. Handlers do their own printing through io (so poll progress
+// streams live), and throw CliError for anything the user needs to fix.
+
+import { LetterstoryClient, CliError, resolveConfig, writeConfigFile, clearConfigFile, configPath } from "./client.mjs";
+
+// --- small helpers ----------------------------------------------------------
+
+// A flag with no value parses to `true`; coerce that back to undefined so a bare
+// `--name` reads as "missing", not the string "true".
+function flagStr(v) {
+	return typeof v === "string" ? v : undefined;
+}
+
+function flagNum(v) {
+	const s = flagStr(v);
+	if (s === undefined) return undefined;
+	const n = Number(s);
+	if (!Number.isFinite(n)) throw new CliError(`Expected a number, got "${s}"`);
+	return n;
+}
+
+function requireFlag(flags, name) {
+	const v = flagStr(flags[name]);
+	if (v === undefined) throw new CliError(`Missing required --${name}`);
+	return v;
+}
+
+function requirePositional(positionals, index, label) {
+	const v = positionals[index];
+	if (v === undefined) throw new CliError(`Missing required <${label}>`);
+	return v;
+}
+
+function printResult(io, flags, value, formatter) {
+	if (flags.json || !formatter) {
+		io.log(JSON.stringify(value, null, 2));
+	} else {
+		io.log(formatter(value));
+	}
+}
+
+function formatDeployment(d) {
+	const lines = [
+		`${d.name}  [${d.deployment_id}]`,
+		`  status:     ${d.status}${d.phase ? ` · ${d.phase}` : ""}`,
+		`  theme:      ${d.theme}`,
+		`  collection: ${d.collection_id ?? "(none)"}`,
+	];
+	if (d.url) lines.push(`  url:        ${d.url}`);
+	if (d.domain) lines.push(`  domain:     ${d.domain}`);
+	if (d.last_error) lines.push(`  error:      ${d.last_error}`);
+	return lines.join("\n");
+}
+
+// Poll get_deployment until the blog reaches a terminal state. Emits a line only
+// when status/phase changes so the output reads as progress, not a firehose.
+async function pollUntilTerminal(client, id, io) {
+	const maxPolls = io.maxPolls ?? 90;
+	const interval = io.pollIntervalMs ?? 4000;
+	let last = "";
+	for (let i = 0; i < maxPolls; i++) {
+		const d = await client.callTool("get_deployment", { deployment_id: id });
+		if (d.status === "live" || d.status === "error") return d;
+		const line = `${d.status}${d.phase ? ` · ${d.phase}` : ""}`;
+		if (line !== last) {
+			io.log(`  … ${line}`);
+			last = line;
+		}
+		await io.sleep(interval);
+	}
+	return {
+		status: "error",
+		last_error: `Timed out waiting for it to go live. Check: letterstory deploy get ${id}`,
+		url: null,
+	};
+}
+
+// --- auth / config ----------------------------------------------------------
+
+export async function cmdLogin(ctx) {
+	const { flags, io } = ctx;
+	const key = requireFlag(flags, "key");
+	const url = flagStr(flags.url);
+	if (!key.startsWith("lb_")) {
+		io.error("Warning: Letterstory API keys usually start with 'lb_'. Saving anyway.");
+	}
+	const saved = { key, ...(url ? { url } : {}) };
+	const path = writeConfigFile(saved);
+	io.log(`Saved credentials to ${path}`);
+
+	// Verify the key works (and report the tool count) without failing the save if
+	// the network is down — a saved-but-unverified key is still usable later.
+	try {
+		const resolved = resolveConfig({ url, key });
+		const client = new LetterstoryClient({ url: resolved.url, key: resolved.key });
+		const tools = await client.listTools();
+		io.log(`Authenticated to ${resolved.url} — ${tools.length} tools available.`);
+		return 0;
+	} catch (err) {
+		io.error(`Saved, but could not verify the key: ${err.message}`);
+		return 0;
+	}
+}
+
+export function cmdLogout(ctx) {
+	const path = clearConfigFile();
+	ctx.io.log(`Cleared credentials at ${path}`);
+	return 0;
+}
+
+export function cmdConfig(ctx) {
+	const { config, io, flags } = ctx;
+	const masked = config.key ? `${config.key.slice(0, 6)}…${config.key.slice(-4)}` : "(none)";
+	const value = {
+		url: config.url,
+		key: masked,
+		key_source: config.keySource,
+		config_file: configPath(),
+	};
+	if (flags.json) {
+		io.log(JSON.stringify(value, null, 2));
+	} else {
+		io.log(`url:         ${value.url}`);
+		io.log(`key:         ${value.key} (from ${value.key_source})`);
+		io.log(`config file: ${value.config_file}`);
+	}
+	return 0;
+}
+
+// --- discovery / generic passthrough ----------------------------------------
+
+export async function cmdTools(ctx) {
+	const { client, io, flags } = ctx;
+	const doc = await client.discover();
+	const tools = doc.tools ?? [];
+	if (flags.json) {
+		io.log(JSON.stringify(tools, null, 2));
+		return 0;
+	}
+	io.log(`${tools.length} tools available at ${client.url}:\n`);
+	for (const t of tools) io.log(`  ${t.name} — ${t.description ?? ""}`);
+	return 0;
+}
+
+// Escape hatch: call any tool by name. Args come from --args '<json>', or from
+// individual string flags (everything after the tool name). Keeps the whole
+// manifest reachable without a bespoke subcommand per tool.
+export async function cmdCall(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "tool");
+	let args = {};
+	if (flags.args !== undefined) {
+		try {
+			args = JSON.parse(flagStr(flags.args) ?? "");
+		} catch {
+			throw new CliError(`--args must be a JSON object, e.g. --args '{"name":"My Blog"}'`);
+		}
+	} else {
+		for (const [k, v] of Object.entries(flags)) {
+			if (k === "json" || k === "url" || k === "key") continue;
+			args[k] = v;
+		}
+	}
+	const result = await client.callTool(name, args);
+	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+	return 0;
+}
+
+// --- deployments (phantom blogs) --------------------------------------------
+
+export async function cmdDeploy(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "create":
+			return deployCreate(rest);
+		case "list":
+			return deployList(rest);
+		case "get":
+		case "status":
+			return deployGet(rest);
+		case "rebuild":
+			return deployRebuild(rest);
+		case "diagnostics":
+			return deployDiagnostics(rest);
+		case "delete":
+			return deployDelete(rest);
+		default:
+			throw new CliError(
+				`Unknown deploy subcommand: ${sub ?? "(none)"}. Try: create, list, get, rebuild, diagnostics, delete`
+			);
+	}
+}
+
+async function deployCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const name = requireFlag(flags, "name");
+	const args = { name };
+	const description = flagStr(flags.description);
+	const theme = flagStr(flags.theme);
+	const collection = flagStr(flags.collection);
+	if (description !== undefined) args.description = description;
+	if (theme !== undefined) args.theme = theme;
+	if (collection !== undefined) args.collection_id = collection;
+
+	const created = await client.callTool("create_deployment", args);
+	io.log(`Created deployment ${created.deployment_id} (${created.status})`);
+
+	if (flags["no-wait"]) {
+		io.log(`Provisioning in the background. Poll with: letterstory deploy get ${created.deployment_id}`);
+		return 0;
+	}
+
+	const final = await pollUntilTerminal(client, created.deployment_id, io);
+	if (final.status === "live") {
+		io.log(`\n✓ Live at ${final.url}`);
+		return 0;
+	}
+	io.error(`\n✗ Deployment ${final.status}: ${final.last_error ?? "unknown error"}`);
+	return 1;
+}
+
+async function deployList(ctx) {
+	const { client, flags, io } = ctx;
+	const limit = flagNum(flags.limit);
+	const result = await client.callTool("list_deployments", limit !== undefined ? { limit } : {});
+	const items = result.items ?? [];
+	if (flags.json) {
+		io.log(JSON.stringify(result, null, 2));
+		return 0;
+	}
+	if (items.length === 0) {
+		io.log("No deployments yet. Create one with: letterstory deploy create --name <name>");
+		return 0;
+	}
+	for (const d of items) {
+		io.log(`${d.status.padEnd(13)} ${d.deployment_id}  ${d.name}${d.url ? `  ${d.url}` : ""}`);
+	}
+	return 0;
+}
+
+async function deployGet(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	const d = await client.callTool("get_deployment", { deployment_id: id });
+	printResult(io, flags, d, formatDeployment);
+	return 0;
+}
+
+async function deployRebuild(ctx) {
+	const { client, positionals, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	await client.callTool("rebuild_deployment", { deployment_id: id });
+	io.log(`Rebuild started for ${id}. New published content will appear once the build finishes.`);
+	return 0;
+}
+
+async function deployDiagnostics(ctx) {
+	const { client, positionals, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	const diag = await client.callTool("get_deployment_diagnostics", { deployment_id: id });
+	io.log(JSON.stringify(diag, null, 2));
+	return 0;
+}
+
+async function deployDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	if (!flags.yes) {
+		io.error(`This tears down the blog's site and revokes its content key (the collection is kept).`);
+		io.error(`Re-run with --yes to confirm: letterstory deploy delete ${id} --yes`);
+		return 1;
+	}
+	await client.callTool("delete_deployment", { deployment_id: id });
+	io.log(`Deleted deployment ${id}.`);
+	return 0;
+}
+
+// --- custom domains ---------------------------------------------------------
+
+export async function cmdDomain(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "check":
+			return domainCheck(rest);
+		case "buy":
+			return domainBuy(rest);
+		default:
+			throw new CliError(`Unknown domain subcommand: ${sub ?? "(none)"}. Try: check, buy`);
+	}
+}
+
+async function domainCheck(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const domain = requirePositional(positionals, 0, "domain");
+	const quote = await client.callTool("check_domain", { domain });
+	if (flags.json) {
+		io.log(JSON.stringify(quote, null, 2));
+		return 0;
+	}
+	io.log(`${domain}`);
+	io.log(`  available:   ${quote.available}`);
+	if (quote.price !== undefined) io.log(`  price:       $${quote.price}`);
+	io.log(`  purchasable: ${quote.purchasable}`);
+	return 0;
+}
+
+async function domainBuy(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	const domain = requirePositional(positionals, 1, "domain");
+	if (!flags.yes) {
+		io.error(`Buying ${domain} SPENDS money (registered under Letterstory, auto-renewing yearly).`);
+		io.error(`Price it first with: letterstory domain check ${domain}`);
+		io.error(`Then confirm with:   letterstory domain buy ${id} ${domain} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("buy_domain", { deployment_id: id, domain });
+	io.log(`Purchase started for ${domain}. Attach + DNS run in the background.`);
+	io.log(`Poll with: letterstory deploy get ${id}`);
+	if (flags.json) io.log(JSON.stringify(result, null, 2));
+	return 0;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@letterstory/cli",
+	"version": "0.1.0",
+	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
+	"type": "module",
+	"license": "UNLICENSED",
+	"author": "Letterstory",
+	"homepage": "https://github.com/letterstory/Letterbrace/tree/main/cli#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/letterstory/Letterbrace.git",
+		"directory": "cli"
+	},
+	"bugs": {
+		"url": "https://github.com/letterstory/Letterbrace/issues"
+	},
+	"keywords": [
+		"letterstory",
+		"cli",
+		"cms",
+		"blog",
+		"phantom",
+		"mcp"
+	],
+	"bin": {
+		"letterstory": "bin/letterstory.mjs"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"README.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}