@letterstory/cli 0.2.0 → 0.2.2

package/README.md

@@ -9,13 +9,38 @@ manifest an agent sees, so it never drifts from the API.
 The CLI is plain ESM with **zero dependencies** and needs no build step (Node ≥ 20).
 
 ```bash
-# from a checkout of this repo
+npm install -g @letterstory/cli   # puts `letterstory` (and `phantom`) on your PATH
+# …or run it without installing:
+npx @letterstory/cli --help
+```
+
+Contributing to the CLI itself? Run it straight from a checkout instead:
+
+```bash
 cd cli
-npm link          # puts `letterstory` (and `phantom`) on your PATH
+npm link          # puts `letterstory` (and `phantom`) on your PATH, pointing at this checkout
 # …or run it directly without linking:
 node cli/bin/letterstory.mjs --help
 ```
 
+## Updating
+
+The CLI checks npm for a newer published version at most once every 24 hours (cached
+alongside your config, so most runs make no extra network call) and prints a one-line
+nudge on stderr when one's available:
+
+```
+Update available: 0.2.1 → 0.3.0. Run `npm install -g @letterstory/cli@latest` to upgrade.
+```
+
+To upgrade immediately:
+
+```bash
+npm install -g @letterstory/cli@latest
+```
+
+Set `LETTERSTORY_NO_UPDATE_CHECK=1` to disable the check entirely (e.g. in CI).
+
 ## `phantom` — the same CLI, Phantomstory-branded
 
 `phantom` is a ghost-branded entry point for demos and presentations — same binary, same
@@ -32,6 +57,22 @@ otherwise runs the exact same code path as `letterstory`.
 
 ## Authenticate
 
+Two ways in — pick whichever fits how you're running the CLI.
+
+**Sign in via your browser** (the default — best for interactive use on your own machine):
+
+```bash
+letterstory login
+# opens your browser to https://app.letterstory.com, or override with --url
+```
+
+This runs a browser-based OAuth 2.1 flow (PKCE, loopback redirect — RFC 8252) against your
+account. It comes back with a full-access session and a refresh token, so there's no API key
+to mint or scope up front. Tokens are saved to `~/.letterstory/config.json` (mode 600) and
+refresh automatically. Run `letterstory logout` to revoke the session and forget it.
+
+**Or use a static API key** (for CI/automation, or when you want scoped-down access):
+
 You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) 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.
@@ -44,8 +85,9 @@ letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 Credentials resolve from `--key`/`--url` flags, then `LETTERSTORY_API_KEY` /
 `LETTERSTORY_API_URL`, then `~/.letterstory/config.json` (written by `login`, mode 600).
 
-Run `letterstory whoami` (alias `status`) any time to confirm which key/url resolved and
-see your company profile.
+Run `letterstory whoami` (alias `status`) any time to confirm which key/url (or OAuth session)
+resolved and see your company profile. Run `letterstory config` to see the resolved url and
+credential source without making a network call.
 
 ## Spin up a blog
 
@@ -69,6 +111,24 @@ letterstory deploy delete <deployment-id> --yes
 Pass `--no-wait` to return immediately and poll later with `deploy get`, or `--dry-run`
 on `create` to print what would be sent without creating anything.
 
+### One-shot: bare `deploy`
+
+For the common case — reserve a blog, price (and optionally buy) a domain, and rebuild,
+all in one call — skip the subcommand word entirely:
+
+```bash
+letterstory deploy --domain yourverticalreview.com --buy
+#   Reserved phantom blog "Yourverticalreview" (7c19c7…)
+#   Priced yourverticalreview.com
+#   Registered yourverticalreview.com
+#   SSL + DNS provisioned · sitemap + schema generated
+#
+#   Your phantom blog is live at https://yourverticalreview.com.
+
+letterstory deploy --blog 7c19c7… --rebuild   # rebuild an existing blog instead of creating one
+letterstory deploy --domain demo.com --dry-run  # preview without calling the API
+```
+
 ## Custom domains
 
 ```bash
@@ -163,21 +223,30 @@ Every Letterstory tool is reachable, not just the ones with a dedicated command
 
 ```bash
 letterstory whoami                                 # or: status — verify your key + who it's for
-letterstory tools                                  # list all tools
+letterstory tools list                             # list all tools (bare `tools` also works)
+letterstory tools show list_articles                # one tool's capability + full argument schema
 letterstory call list_articles --args '{"limit":5}'
 letterstory call ingest_article --args '{"title":"…","content":"…"}'
+
+# `tool` is the same idea with schema-coerced arguments instead of raw JSON:
+letterstory tool list_articles --arg limit=5 --arg collection_id=c1
+letterstory tool ingest_article --json-args '{"title":"…"}' --arg content="…"
+cat article.json | letterstory tool ingest_article --stdin
+
+letterstory mcp                                     # print MCP server config for an agent
+letterstory mcp --print-key                         # inline the real key instead of a placeholder
 ```
 
 ## Global flags
 
-| Flag         | Meaning                                                                  |
-| ------------ | ------------------------------------------------------------------------ |
-| `--json`     | Machine-readable output                                                  |
-| `--quiet`    | Suppress success chatter on the new command groups (`--json` implies it) |
-| `--verbose`  | Log HTTP requests/responses to stderr                                    |
-| `--no-color` | Accepted for compatibility; this CLI already prints plain text           |
-| `--dry-run`  | On `deploy`/`blogs create`: print what would be created, don't create it |
-| `--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                                                    |
+| Flag         | Meaning                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------- |
+| `--json`     | Machine-readable output                                                                   |
+| `--quiet`    | Suppress success chatter on the new command groups (`--json` implies it)                  |
+| `--verbose`  | Log HTTP requests/responses to stderr                                                     |
+| `--no-color` | Accepted for compatibility; this CLI already prints plain text                            |
+| `--dry-run`  | On `deploy`/`blogs create`, or bare `deploy`: print what would happen, don't call the API |
+| `--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/lib/cli.mjs

@@ -3,6 +3,7 @@
 // never throws for user-facing problems (those become a printed CliError + code 1).
 
 import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import { checkForUpdate } from "./update-check.mjs";
 import {
 	cmdLogin,
 	cmdLogout,
@@ -10,6 +11,8 @@ import {
 	cmdWhoami,
 	cmdTools,
 	cmdCall,
+	cmdTool,
+	cmdMcp,
 	cmdDeploy,
 	cmdDomain,
 	cmdBlogs,
@@ -25,11 +28,25 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.2";
 
 // 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", "quiet", "verbose", "no-color", "dry-run"]);
+const BOOLEAN_FLAGS = new Set([
+	"json",
+	"yes",
+	"no-wait",
+	"help",
+	"version",
+	"quiet",
+	"verbose",
+	"no-color",
+	"dry-run",
+	"buy",
+	"rebuild",
+	"print-key",
+	"stdin",
+]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
 // A flag repeated more than once (e.g. `--topic a --topic b`, used by `strategy
@@ -100,6 +117,10 @@ Auth:
   config                             Show the resolved url + credential source
 
 Phantom blogs:
+  deploy [--domain <d>] [--name <n>] [--theme <t>] [--collection <uuid>]
+         [--blog <id>] [--buy] [--rebuild] [--dry-run]
+                                                      One-shot: reserve/locate a blog, price
+                                                      the domain, optionally buy it, rebuild
   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
@@ -158,8 +179,13 @@ Insights:
   insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]
 
 Anything else:
-  tools                              List every tool this server exposes
+  tools list                         List every tool this server exposes, by name
+  tools show <name>                  Show one tool's capability + full argument schema
   call <tool> [--args '<json>'] [--flag value …]     Call any tool directly
+  tool <name> [--arg k=v …] [--json-args '<json>'] [--stdin]
+                                      Call any tool with schema-coerced arguments
+  mcp [--name <name>] [--print-key] [--json]
+                                      Print MCP server config for Claude Code/Desktop/Cursor
   whoami (alias status)              Verify the resolved key and show who it's for
 
 Global flags:
@@ -167,7 +193,7 @@ Global flags:
   --quiet         Suppress success chatter (new command groups only; --json implies it)
   --verbose       Log HTTP requests/responses to stderr
   --no-color      Accepted for compatibility; this CLI prints plain text already
-  --dry-run       For deploy/blogs create: print what would be created, don't create it
+  --dry-run       For deploy/blogs create, or bare deploy: print what would happen, don't call the API
   --url <url>     Override the API base URL for this invocation
   --key <ls_…>    Override the API key for this invocation
   --help          Show this help
@@ -185,6 +211,10 @@ const CLIENT_COMMANDS = {
 	status: cmdWhoami,
 	tools: cmdTools,
 	call: cmdCall,
+	// `tool` is Mathew's phantomstory-cli name for `call`, with schema-aware
+	// argument coercion (--arg/--json-args/--stdin) added on top.
+	tool: cmdTool,
+	mcp: cmdMcp,
 	deploy: cmdDeploy,
 	domain: cmdDomain,
 	// Mathew's phantomstory-cli names for the exact same deploy/domain commands.
@@ -215,6 +245,9 @@ export function defaultIo() {
 		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 		pollIntervalMs: envInt("LETTERSTORY_POLL_INTERVAL_MS", 4000),
 		maxPolls: envInt("LETTERSTORY_MAX_POLLS", 90),
+		// Only a *real* CLI invocation (never a test, which always builds its own io)
+		// gets the background update-version check — see the `finally` block in run().
+		updateCheck: true,
 	};
 }
 
@@ -269,5 +302,18 @@ export async function run(argv, io = defaultIo()) {
 			return 1;
 		}
 		throw err;
+	} finally {
+		// Fire-and-await (bounded by checkForUpdate's own short fetch timeout) so the
+		// nudge, if any, is printed before the bin's process.exit() — but a warm cache
+		// (the common case) resolves with no network call at all, so this is normally
+		// instant. --json output stays machine-clean; real errors above already returned.
+		if (io.updateCheck && !flags.json) {
+			try {
+				const notice = await checkForUpdate({ currentVersion: VERSION });
+				if (notice) io.error(notice);
+			} catch {
+				// Never let the update nudge itself become the reason a command fails.
+			}
+		}
 	}
 }

package/lib/commands/deploy.mjs

@@ -52,6 +52,10 @@ async function pollUntilTerminal(client, id, io, bin) {
 
 export async function cmdDeploy(ctx) {
 	const sub = ctx.positionals[0];
+	// Bare `deploy` (no subcommand word) is phantomstory-cli's flagship, flag-only
+	// invocation — `phantom deploy --domain x.com --buy` — not one of the create/
+	// list/get/… verbs below, so route it to the orchestrator before the switch.
+	if (sub === undefined) return deployOrchestrate(ctx);
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
 	switch (sub) {
 		case "create":
@@ -76,11 +80,153 @@ export async function cmdDeploy(ctx) {
 			return deployDelete(rest);
 		default:
 			throw new CliError(
-				`Unknown deploy subcommand: ${sub ?? "(none)"}. Try: create, list, get, update, rebuild, diagnostics, delete`
+				`Unknown deploy subcommand: ${sub}. Try: create, list, get, update, rebuild, diagnostics, delete — or bare ` +
+					`"${ctx.bin} deploy --domain <domain>" to reserve+price+build in one step.`
 			);
 	}
 }
 
+// --- one-shot orchestrator: reserve/locate → price domain → optionally buy →
+// rebuild-if-changed. Mirrors phantomstory-cli's flagship `phantom deploy` in this
+// CLI's own plain-text conventions (no spinners/animation, see commands/README notes
+// on the ui/render toolkit not being ported).
+function nameFromDomain(domain) {
+	if (!domain) return undefined;
+	const host = domain
+		.replace(/^https?:\/\//, "")
+		.replace(/^www\./, "")
+		.split("/")[0];
+	const base = host.split(".")[0];
+	if (!base) return undefined;
+	return base
+		.split(/[-_]/)
+		.filter(Boolean)
+		.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+		.join(" ");
+}
+
+function pickId(obj) {
+	if (obj && typeof obj === "object") {
+		for (const key of ["deployment_id", "id", "deploymentId"]) {
+			if (typeof obj[key] === "string") return obj[key];
+		}
+	}
+	return undefined;
+}
+
+function liveUrl(domain, collected) {
+	if (domain) return `https://${domain}`;
+	for (const v of Object.values(collected)) {
+		if (v && typeof v === "object") {
+			const url = v.url ?? v.live_url ?? v.blog_url;
+			if (typeof url === "string") return url;
+		}
+	}
+	return undefined;
+}
+
+async function deployOrchestrate(ctx) {
+	const { client, flags, io } = ctx;
+	const domainFlag = flagStr(flags.domain);
+	const nameFlag = flagStr(flags.name);
+	const themeFlag = flagStr(flags.theme);
+	const collectionFlag = flagStr(flags.collection);
+	const blogFlag = flagStr(flags.blog);
+	const buy = Boolean(flags.buy);
+	const forceRebuild = Boolean(flags.rebuild);
+	const domain = domainFlag !== undefined ? stripScheme(domainFlag) : undefined;
+
+	if (!domain && !nameFlag && !blogFlag) {
+		throw new CliError(
+			`Nothing to deploy — pass --domain, --name, or --blog. e.g. "${ctx.bin} deploy --domain yourverticalreview.com"`
+		);
+	}
+	if (buy && !domain) {
+		throw new CliError("--buy needs a --domain to register.");
+	}
+	if (blogFlag && (nameFlag || themeFlag || collectionFlag)) {
+		throw new CliError(
+			`--name/--theme/--collection can't be combined with --blog. Use "${ctx.bin} deploy update <id>" to rename, re-theme, or repoint an existing blog.`
+		);
+	}
+
+	if (flags["dry-run"]) {
+		const name = nameFlag || nameFromDomain(domain) || "Phantom Blog";
+		io.log(`Dry run — would deploy with:`);
+		io.log(
+			JSON.stringify(
+				compact({
+					blog: blogFlag,
+					name: blogFlag ? undefined : name,
+					theme: themeFlag,
+					collection: collectionFlag,
+					domain,
+					buy,
+					rebuild: forceRebuild,
+				}),
+				null,
+				2
+			)
+		);
+		if (domain) io.log(`\nWould be live at https://${domain}`);
+		return 0;
+	}
+
+	const collected = {};
+	let changed = false;
+	let deploymentId = blogFlag;
+
+	if (deploymentId) {
+		collected.blog = await client.callTool("get_deployment", { deployment_id: deploymentId });
+		io.log(`Found phantom blog ${deploymentId}`);
+	} else {
+		const name = nameFlag || nameFromDomain(domain) || "Phantom Blog";
+		const created = await client.callTool(
+			"create_deployment",
+			compact({ name, theme: themeFlag, collection_id: collectionFlag })
+		);
+		collected.blog = created;
+		deploymentId = pickId(created);
+		changed = true;
+		io.log(`Reserved phantom blog "${name}"${deploymentId ? ` (${deploymentId})` : ""}`);
+	}
+
+	if (domain) {
+		collected.domain = await client.callTool("check_domain", { domain });
+		io.log(`Priced ${domain}`);
+
+		if (buy) {
+			if (!deploymentId) throw new CliError("Cannot register a domain without a blog id.");
+			collected.purchase = await client.callTool("buy_domain", { deployment_id: deploymentId, domain });
+			changed = true;
+			io.log(`Registered ${domain}`);
+		}
+	}
+
+	if (deploymentId && (changed || forceRebuild)) {
+		collected.build = await client.callTool("rebuild_deployment", { deployment_id: deploymentId });
+		io.log(`SSL + DNS provisioned · sitemap + schema generated`);
+		try {
+			collected.diagnostics = await client.callTool("get_deployment_diagnostics", {
+				deployment_id: deploymentId,
+			});
+		} catch {
+			// best-effort — diagnostics may not be ready immediately after a build kicks off
+		}
+	} else if (deploymentId) {
+		io.log(`No changes — skipped rebuild (pass --rebuild to force).`);
+	}
+
+	if (flags.json) {
+		io.log(JSON.stringify(collected, null, 2));
+		return 0;
+	}
+
+	const url = liveUrl(domain, collected);
+	io.log(`\nYour phantom blog is live${url ? ` at ${url}` : ""}.`);
+	return 0;
+}
+
 async function deployCreate(ctx) {
 	const { client, flags, io } = ctx;
 	const name = requireFlag(flags, "name");

package/lib/commands/discovery.mjs

@@ -1,11 +1,29 @@
-// Discovery / generic passthrough: `tools` (list the manifest) and `call` (invoke any
-// tool by name). Unchanged from the original commands.mjs — this is the escape hatch
-// that keeps every tool reachable even ones with no dedicated command group.
+// Discovery / generic passthrough: `tools` (browse the manifest — list + show) and
+// `call`/`tool` (invoke any tool by name). This is the escape hatch that keeps every
+// tool reachable even ones with no dedicated command group. `discover()` is the same
+// unauthenticated GET both `tools list` and `tools show` read from — there's no
+// separate bundled/static manifest to keep in sync (unlike phantomstory-cli's
+// manifest.ts), so there's no `--live` flag here: it's always live, by construction.
 
+import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, requirePositional } from "./shared.mjs";
+import { flagStr, flagList, requirePositional } from "./shared.mjs";
+
+// --- tools: list / show -----------------------------------------------------
 
 export async function cmdTools(ctx) {
+	const sub = ctx.positionals[0];
+	if (sub === undefined || sub === "list" || sub === "ls") {
+		const rest = { ...ctx, positionals: ctx.positionals.slice(sub === undefined ? 0 : 1) };
+		return toolsList(rest);
+	}
+	if (sub === "show") {
+		return toolsShow({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
+	throw new CliError(`Unknown tools subcommand: ${sub}. Try: list, show <name>`);
+}
+
+async function toolsList(ctx) {
 	const { client, io, flags } = ctx;
 	const doc = await client.discover();
 	const tools = doc.tools ?? [];
@@ -15,12 +33,75 @@ export async function cmdTools(ctx) {
 	}
 	io.log(`${tools.length} tools available at ${client.url}:\n`);
 	for (const t of tools) io.log(`  ${t.name} — ${t.description ?? ""}`);
+	io.log(``);
+	io.log(`  Run \`${ctx.bin} tools show <name>\` for a tool's full argument schema.`);
 	return 0;
 }
 
+async function toolsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "name");
+	const doc = await client.discover();
+	const tool = (doc.tools ?? []).find((t) => t.name === name);
+	if (!tool) {
+		throw new CliError(`No tool named "${name}". See \`${ctx.bin} tools list\`.`);
+	}
+	if (flags.json) {
+		io.log(JSON.stringify(tool, null, 2));
+		return 0;
+	}
+	renderTool(io, tool);
+	return 0;
+}
+
+function renderTool(io, tool) {
+	io.log(tool.name);
+	io.log(`  ${tool.description ?? ""}`);
+	io.log(``);
+	io.log(`  capability: ${tool.capability ?? "(none)"}`);
+	const props = tool.inputSchema?.properties ?? {};
+	const required = new Set(tool.inputSchema?.required ?? []);
+	const names = Object.keys(props);
+	if (names.length === 0) {
+		io.log(`  (no arguments)`);
+		return;
+	}
+	io.log(``);
+	io.log(`  arguments:`);
+	for (const name of names) {
+		const req = required.has(name) ? "required" : "optional";
+		const detail = detailOf(props[name]);
+		io.log(`    ${name} (${typeLabel(props[name])}, ${req})${detail ? ` — ${detail}` : ""}`);
+	}
+}
+
+function typeLabel(prop) {
+	if (!prop) return "any";
+	if (prop.enum) return "enum";
+	if (typeof prop.type === "string") return prop.type;
+	if (Array.isArray(prop.type)) return prop.type.filter((t) => t !== "null").join("|") || "any";
+	if (prop.anyOf) {
+		const types = prop.anyOf.map((a) => (typeof a.type === "string" ? a.type : "any")).filter((t) => t !== "null");
+		return [...new Set(types)].join("|") || "any";
+	}
+	return "any";
+}
+
+function detailOf(prop) {
+	const parts = [];
+	if (prop.description) parts.push(prop.description);
+	if (prop.enum) parts.push(`one of: ${prop.enum.map(String).join(", ")}`);
+	if (prop.default !== undefined) parts.push(`default: ${JSON.stringify(prop.default)}`);
+	return parts.join(" · ");
+}
+
+// --- call / tool: raw dispatcher --------------------------------------------
+
 // 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.
+// manifest reachable without a bespoke subcommand per tool. This is the original,
+// stable spelling; `tool` (below) is Mathew's phantomstory-cli name for the same
+// idea, with schema-aware argument coercion added on top.
 export async function cmdCall(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const name = requirePositional(positionals, 0, "tool");
@@ -41,3 +122,117 @@ export async function cmdCall(ctx) {
 	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
 	return 0;
 }
+
+// `tool <name> [--arg k=v ...] [--json-args '{…}'] [--stdin]` — phantomstory-cli's
+// raw dispatcher. Unlike `call`, args are coerced toward the tool's real schema
+// (`--arg limit=5` becomes a number, `--arg tags=a,b` an array), and can be piped in
+// as JSON. Precedence low-to-high: --stdin, then --json-args, then --arg (most
+// specific wins) — matches phantomstory-cli's tools.ts.
+export async function cmdTool(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "tool");
+	const doc = await client.discover();
+	const tool = (doc.tools ?? []).find((t) => t.name === name);
+	if (!tool && !flags.quiet) {
+		io.error(`Warning: "${name}" is not in the discovered catalog; sending anyway.`);
+	}
+
+	let args = {};
+	if (flags.stdin) args = { ...args, ...asObject(readStdinJson()) };
+	const jsonArgs = flagStr(flags["json-args"]);
+	if (jsonArgs !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(jsonArgs);
+		} catch (err) {
+			throw new CliError(`Invalid --json-args: ${err.message}`);
+		}
+		args = { ...args, ...asObject(parsed) };
+	}
+	const pairs = coerceToSchema(parseKeyVals(flagList(flags.arg)), tool?.inputSchema);
+	args = { ...args, ...pairs };
+
+	const result = await client.callTool(name, args);
+	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+	return 0;
+}
+
+function asObject(v) {
+	if (v && typeof v === "object" && !Array.isArray(v)) return v;
+	throw new CliError("Arguments must be a JSON object.");
+}
+
+function readStdinJson() {
+	if (process.stdin.isTTY) {
+		throw new CliError("No data on stdin — pipe input in, or omit --stdin.");
+	}
+	let raw;
+	try {
+		raw = readFileSync(0, "utf8");
+	} catch (err) {
+		throw new CliError(`Could not read stdin: ${err.message}`);
+	}
+	if (!raw) return {};
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`Invalid JSON on stdin: ${err.message}`);
+	}
+}
+
+function parseKeyVals(items) {
+	const out = {};
+	for (const item of items) {
+		const eq = item.indexOf("=");
+		if (eq === -1) throw new CliError(`Malformed --arg "${item}", expected key=value.`);
+		out[item.slice(0, eq)] = item.slice(eq + 1);
+	}
+	return out;
+}
+
+function coerceToSchema(raw, schema) {
+	const props = schema?.properties ?? {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) out[key] = coerceValue(value, props[key]);
+	return out;
+}
+
+function coerceValue(value, prop) {
+	switch (resolveType(prop)) {
+		case "integer":
+		case "number": {
+			const n = Number(value);
+			return Number.isNaN(n) ? value : n;
+		}
+		case "boolean":
+			if (value === "true") return true;
+			if (value === "false") return false;
+			return value;
+		case "array":
+			return value
+				.split(",")
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+		case "object":
+			try {
+				return JSON.parse(value);
+			} catch (err) {
+				throw new CliError(`Invalid object value for --arg: ${err.message}`);
+			}
+		default:
+			return value;
+	}
+}
+
+function resolveType(prop) {
+	if (!prop) return undefined;
+	if (typeof prop.type === "string") return prop.type;
+	if (Array.isArray(prop.type)) return prop.type.find((t) => t !== "null");
+	if (prop.anyOf) {
+		for (const alt of prop.anyOf) {
+			const t = resolveType(alt);
+			if (t && t !== "null") return t;
+		}
+	}
+	return undefined;
+}

package/lib/commands/mcp.mjs

@@ -0,0 +1,52 @@
+// `mcp` — print ready-to-paste configuration for wiring the Letterstory MCP server
+// into an agent (Claude Code, Claude Desktop, Cursor, …). Same endpoint/auth header
+// the CLI itself uses (see client.mjs's `mcpEndpoint` / `x-integrations-key`), just
+// packaged for copy-paste instead of for this process's own requests.
+
+import { flagStr } from "./shared.mjs";
+
+export function cmdMcp(ctx) {
+	const { config, flags, io } = ctx;
+	const name = flagStr(flags.name) ?? "letterstory";
+	const endpoint = `${config.url}/api/mcp`;
+	const header = "x-integrations-key";
+	const printKey = Boolean(flags["print-key"]);
+	const keyValue = printKey && config.key ? config.key : "${LETTERSTORY_API_KEY}";
+
+	const jsonConfig = {
+		mcpServers: {
+			[name]: {
+				type: "http",
+				url: endpoint,
+				headers: { [header]: keyValue },
+			},
+		},
+	};
+
+	if (flags.json) {
+		io.log(JSON.stringify(jsonConfig, null, 2));
+		return 0;
+	}
+
+	const masked = config.key ? `${config.key.slice(0, 6)}…${config.key.slice(-4)}` : undefined;
+
+	io.log(`Letterstory MCP`);
+	io.log(`  endpoint:  ${endpoint}`);
+	io.log(`  transport: streamable-http`);
+	io.log(`  auth:      ${header}: ${masked ?? "(no key found — run `" + ctx.bin + " login` first)"}`);
+
+	io.log(``);
+	io.log(`Claude Code:`);
+	io.log(`  claude mcp add --transport http ${name} ${endpoint} \\`);
+	io.log(`      --header "${header}: ${printKey && config.key ? config.key : "YOUR_KEY"}"`);
+
+	io.log(``);
+	io.log(`Claude Desktop / Cursor (mcpServers block):`);
+	for (const line of JSON.stringify(jsonConfig, null, 2).split("\n")) io.log(`  ${line}`);
+
+	if (!printKey) {
+		io.log(``);
+		io.log(`Tip: export LETTERSTORY_API_KEY=…, or re-run with --print-key to inline it.`);
+	}
+	return 0;
+}

package/lib/commands.mjs

@@ -7,6 +7,7 @@
 export * from "./commands/auth.mjs";
 export * from "./commands/discovery.mjs";
 export * from "./commands/deploy.mjs";
+export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
 export * from "./commands/collections.mjs";
 export * from "./commands/flows.mjs";

package/lib/update-check.mjs

@@ -0,0 +1,94 @@
+// Best-effort "a newer version is out" nudge. Checks the npm registry at most once
+// every 24h and caches the result next to the config file, so a warm cache never
+// touches the network and a cold/offline check never slows or breaks a command —
+// every failure mode (no network, slow DNS, registry down, unwritable home) is
+// swallowed and just means no nudge gets printed.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@letterstory/cli/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 500;
+
+function cachePath() {
+	const home = process.env.LETTERSTORY_CONFIG_HOME || homedir();
+	return join(home, ".letterstory", "update-check.json");
+}
+
+function readCache() {
+	try {
+		if (!existsSync(cachePath())) return null;
+		return JSON.parse(readFileSync(cachePath(), "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function writeCache(data) {
+	try {
+		const path = cachePath();
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify(data));
+	} catch {
+		// Read-only home, no disk space, etc. — caching is an optimization, not a requirement.
+	}
+}
+
+// Plain dotted-numeric semver compare — this CLI's versions are always X.Y.Z, no
+// prerelease/build metadata to worry about.
+function isNewer(latest, current) {
+	const a = String(latest).split(".").map(Number);
+	const b = String(current).split(".").map(Number);
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const x = a[i] || 0;
+		const y = b[i] || 0;
+		if (x !== y) return x > y;
+	}
+	return false;
+}
+
+async function fetchLatestVersion(fetchImpl) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(REGISTRY_URL, { signal: controller.signal });
+		if (!res.ok) return null;
+		const body = await res.json();
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null; // offline, timed out, registry down, malformed response — no nudge, not an error
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Returns a one-line nudge string if a newer version is published on npm, else null.
+ * Never throws. `fetchImpl`/`now` are injectable for tests; real callers use the
+ * defaults (global fetch, current time).
+ *
+ * @param {{ currentVersion: string, fetchImpl?: (url: string, init?: { signal?: AbortSignal }) => Promise<{ ok: boolean, json: () => Promise<any> }>, now?: number }} opts
+ * @returns {Promise<string | null>}
+ */
+export async function checkForUpdate({ currentVersion, fetchImpl = globalThis.fetch, now = Date.now() }) {
+	if (process.env.LETTERSTORY_NO_UPDATE_CHECK) return null;
+
+	const cache = readCache();
+	let latest = cache?.latestVersion;
+	const stale = !cache || typeof cache.checkedAt !== "number" || now - cache.checkedAt > CHECK_INTERVAL_MS;
+
+	if (stale) {
+		const fetched = await fetchLatestVersion(fetchImpl);
+		if (fetched) {
+			latest = fetched;
+			writeCache({ checkedAt: now, latestVersion: fetched });
+		} else if (!cache) {
+			return null; // first-ever check failed (e.g. offline) — nothing to compare against yet
+		}
+	}
+
+	if (!latest || !isNewer(latest, currentVersion)) return null;
+	return `Update available: ${currentVersion} → ${latest}. Run \`npm install -g @letterstory/cli@latest\` to upgrade. (Set LETTERSTORY_NO_UPDATE_CHECK=1 to silence this.)`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",