@letterstory/cli 0.1.1 → 0.2.0

package/lib/commands/auth.mjs

@@ -0,0 +1,125 @@
+// Auth / config: login, logout, config, whoami. `letterstory login` (no --key)
+// opens the browser for OAuth 2.1 + PKCE; `--key <ls_…>` keeps the static-key
+// path for CI/automation, where there's no browser to open. Both save to the
+// same config file, but under different keys (`oauth` vs `key`) so
+// resolveConfig() can tell them apart. cmdWhoami mirrors phantomstory-cli's
+// `phantom whoami` (alias `status`) — verify the resolved credential by
+// calling get_company_info, same probe `login` uses to verify a fresh key.
+
+import { LetterstoryClient, resolveConfig, writeConfigFile, clearConfigFile, configPath } from "../client.mjs";
+import { flagStr } from "./shared.mjs";
+import { browserLogin, revokeToken } from "../oauth.mjs";
+
+export async function cmdLogin(ctx) {
+	const { flags, io } = ctx;
+	const url = flagStr(flags.url) || resolveConfig({}).url;
+	const key = flagStr(flags.key);
+
+	if (key) {
+		if (!key.startsWith("ls_") && !key.startsWith("lb_")) {
+			io.error(
+				"Warning: Letterstory API keys usually start with 'ls_' (legacy keys start with 'lb_'). Saving anyway."
+			);
+		}
+		const saved = { key, ...(flagStr(flags.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;
+		}
+	}
+
+	const tokens = await browserLogin({ url, io });
+	const oauth = {
+		access_token: tokens.access_token,
+		refresh_token: tokens.refresh_token,
+		expires_at: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+		scope: tokens.scope,
+	};
+	const saved = { oauth, ...(flagStr(flags.url) ? { url } : {}) };
+	const path = writeConfigFile(saved);
+	io.log(`Saved credentials to ${path}`);
+
+	try {
+		const client = new LetterstoryClient({ url, oauth });
+		const tools = await client.listTools();
+		io.log(`Authenticated to ${url} — ${tools.length} tools available.`);
+	} catch (err) {
+		io.error(`Saved, but could not verify the session: ${err.message}`);
+	}
+	return 0;
+}
+
+export async function cmdLogout(ctx) {
+	const { config, io } = ctx;
+	if (config.oauth?.access_token) {
+		await revokeToken({ url: config.url, token: config.oauth.access_token });
+		if (config.oauth.refresh_token) await revokeToken({ url: config.url, token: config.oauth.refresh_token });
+	}
+	const path = clearConfigFile();
+	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)}`
+		: config.oauth
+			? "(browser session)"
+			: "(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;
+}
+
+// `whoami` (alias `status`): confirm the resolved credential actually works and
+// show who it's for. get_onboarding_status is best-effort (older orgs may not
+// have onboarding state).
+export async function cmdWhoami(ctx) {
+	const { client, config, io, flags } = ctx;
+	const company = await client.callTool("get_company_info", {});
+	let onboarding;
+	try {
+		onboarding = await client.callTool("get_onboarding_status", {});
+	} catch {
+		onboarding = undefined;
+	}
+	const masked = config.key
+		? `${config.key.slice(0, 6)}…${config.key.slice(-4)}`
+		: config.oauth
+			? "(browser session)"
+			: "(none)";
+	if (flags.json) {
+		io.log(
+			JSON.stringify({ url: config.url, key: masked, key_source: config.keySource, company, onboarding }, null, 2)
+		);
+		return 0;
+	}
+	io.log(`url:         ${config.url}`);
+	io.log(`key:         ${masked} (from ${config.keySource})`);
+	io.log(`company:     ${JSON.stringify(company)}`);
+	if (onboarding !== undefined) io.log(`onboarding:  ${JSON.stringify(onboarding)}`);
+	return 0;
+}

package/lib/commands/collections.mjs

@@ -0,0 +1,93 @@
+// `collections` — group articles into collections and set a publishing cadence.
+// Ported from phantomstory-cli's collections.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdCollections(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return collectionsList(rest);
+		case "new":
+		case "create":
+			return collectionsNew(rest);
+		case "update":
+			return collectionsUpdate(rest);
+		case "delete":
+		case "rm":
+			return collectionsDelete(rest);
+		case "assign":
+			return collectionsAssign(rest);
+		default:
+			throw new CliError(
+				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign`
+			);
+	}
+}
+
+async function collectionsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_collections", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionsNew(ctx) {
+	const { client, flags, io } = ctx;
+	const name = requireFlag(flags, "name");
+	const args = compact({ name, description: flagStr(flags.description) });
+	const result = await client.callTool("create_collection", args);
+	ok(ctx, `Created collection "${name}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionsUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "collection-id");
+	const patch = compact({
+		collection_id: id,
+		name: flagStr(flags.name),
+		description: flagStr(flags.description),
+		cadence_target: flagNum(flags["cadence-target"]),
+		cadence_period: flagStr(flags["cadence-period"]),
+	});
+	if (Object.keys(patch).length <= 1) {
+		throw new CliError(
+			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period."
+		);
+	}
+	const result = await client.callTool("update_collection", patch);
+	ok(ctx, "Updated collection.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "collection-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} collections delete ${id} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("delete_collection", { collection_id: id });
+	ok(ctx, "Collection deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionsAssign(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const articleId = requirePositional(positionals, 0, "article-id");
+	const collectionId = requirePositional(positionals, 1, "collection-id");
+	const result = await client.callTool("assign_article_to_collection", {
+		article_id: articleId,
+		collection_id: collectionId,
+	});
+	ok(ctx, "Article assigned.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/connectors.mjs

@@ -0,0 +1,56 @@
+// `connectors` — export finished articles to external CMSs/doc tools (Webflow,
+// Framer, Google Docs, Contentful) and check publish status. Ported from
+// phantomstory-cli's connectors.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdConnectors(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+		case "targets":
+			return connectorsList(rest);
+		case "publish":
+			return connectorsPublish(rest);
+		case "status":
+			return connectorsStatus(rest);
+		default:
+			throw new CliError(`Unknown connectors subcommand: ${sub ?? "(none)"}. Try: list, publish, status`);
+	}
+}
+
+async function connectorsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_publish_targets", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function connectorsPublish(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const articleId = requirePositional(positionals, 0, "article-id");
+	const to = requireFlag(flags, "to");
+	const target = requireFlag(flags, "target");
+	const args = compact({
+		article_id: articleId,
+		connector: to,
+		target_id: target,
+		flow_run_id: flagStr(flags["flow-run"]),
+	});
+	const result = await client.callTool("publish_to_connector", args);
+	ok(ctx, `Publishing to ${to}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function connectorsStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const connector = requireFlag(flags, "connector");
+	const publishId = requireFlag(flags, "publish-id");
+	const result = await client.callTool("get_publish_status", { connector, publish_id: publishId });
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/deploy.mjs

@@ -0,0 +1,241 @@
+// Phantom blogs (deployments) and custom domains. `cmdDeploy`/`cmdDomain` are the
+// original, stable command surface; `blogs`/`domains` are Mathew's phantomstory-cli
+// names for the exact same operations. Rather than duplicate handler bodies, `blogs`
+// and `domains` are literal references to `cmdDeploy`/`cmdDomain` (see the bottom of
+// this file) and Mathew's verb spellings (ls/new/show/rm/diag) are additional cases
+// in the same switch statements below — one implementation, two vocabularies.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, requireFlag, requirePositional, printResult, compact } from "./shared.mjs";
+
+function stripScheme(domain) {
+	return domain.replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+}
+
+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, bin) {
+	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: ${bin} deploy get ${id}`,
+		url: null,
+	};
+}
+
+// --- 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":
+		case "new":
+			return deployCreate(rest);
+		case "list":
+		case "ls":
+			return deployList(rest);
+		case "get":
+		case "status":
+		case "show":
+			return deployGet(rest);
+		case "update":
+			return deployUpdate(rest);
+		case "rebuild":
+			return deployRebuild(rest);
+		case "diagnostics":
+		case "diag":
+			return deployDiagnostics(rest);
+		case "delete":
+		case "rm":
+			return deployDelete(rest);
+		default:
+			throw new CliError(
+				`Unknown deploy subcommand: ${sub ?? "(none)"}. Try: create, list, get, update, 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;
+
+	if (flags["dry-run"]) {
+		io.log(`Dry run — would create a phantom blog with:`);
+		io.log(JSON.stringify(args, null, 2));
+		return 0;
+	}
+
+	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: ${ctx.bin} deploy get ${created.deployment_id}`);
+		return 0;
+	}
+
+	const final = await pollUntilTerminal(client, created.deployment_id, io, ctx.bin);
+	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: ${ctx.bin} 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 deployUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	const patch = compact({
+		deployment_id: id,
+		name: flagStr(flags.name),
+		description: flagStr(flags.description),
+		theme: flagStr(flags.theme),
+		collection_id: flagStr(flags.collection),
+	});
+	if (Object.keys(patch).length <= 1) {
+		throw new CliError("Nothing to update — pass at least one of --name/--description/--theme/--collection.");
+	}
+	const d = await client.callTool("update_deployment", patch);
+	io.log(`Updated deployment ${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: ${ctx.bin} 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 = stripScheme(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;
+}
+
+// No confirm gate: the app's BuyDomainDialog charges on a single "Get this domain"
+// click, and the CLI mirrors the app's user-facing flow. The spend is bounded on the
+// server, not by a client prompt — `buy_domain` is server-priced and hard-capped
+// (≤2 domains/org, <$30, blog must be live with no domain yet).
+async function domainBuy(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "deployment-id");
+	const domain = stripScheme(requirePositional(positionals, 1, "domain"));
+	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: ${ctx.bin} deploy get ${id}`);
+	if (flags.json) io.log(JSON.stringify(result, null, 2));
+	return 0;
+}
+
+// `blogs`/`domains` are phantomstory-cli's names for these exact same commands — a
+// literal reference, not a wrapper, so they can never drift from deploy/domain.
+export const cmdBlogs = cmdDeploy;
+export const cmdDomains = cmdDomain;

package/lib/commands/discovery.mjs

@@ -0,0 +1,43 @@
+// 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.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional } from "./shared.mjs";
+
+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;
+}

package/lib/commands/flows.mjs

@@ -0,0 +1,83 @@
+// `flows` — run editorial passes over articles, check run status, and manage the
+// flow_run.completed completion webhook. Ported from phantomstory-cli's flows.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdFlows(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return flowsList(rest);
+		case "run":
+			return flowsRun(rest);
+		case "status":
+			return flowsStatus(rest);
+		case "webhook":
+			return flowsWebhook(rest);
+		default:
+			throw new CliError(`Unknown flows subcommand: ${sub ?? "(none)"}. Try: list, run, status, webhook`);
+	}
+}
+
+async function flowsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_flows", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsRun(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const flowId = requirePositional(positionals, 0, "flow-id");
+	const articleId = requirePositional(positionals, 1, "article-id");
+	const result = await client.callTool("run_flow", { flow_id: flowId, article_id: articleId });
+	ok(ctx, "Flow run started.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const runId = requirePositional(positionals, 0, "run-id");
+	const result = await client.callTool("get_run_status", { flow_run_id: runId });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsWebhook(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "get":
+			return webhookGet(rest);
+		case "set":
+			return webhookSet(rest);
+		default:
+			throw new CliError(`Unknown flows webhook subcommand: ${sub ?? "(none)"}. Try: get, set`);
+	}
+}
+
+async function webhookGet(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_webhook", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function webhookSet(ctx) {
+	const { client, flags, io } = ctx;
+	const url = flagStr(flags.url);
+	if (url === undefined) throw new CliError('Missing required --url (an https URL, or "none"/"off" to disable)');
+	const disable = ["none", "off", ""].includes(url.toLowerCase());
+	const args = compact({ webhook_secret: flagStr(flags.secret) });
+	// webhook_url is required and may legitimately be null; set it after compact()
+	// since compact() drops undefined (not null) — this assignment is deliberate.
+	args.webhook_url = disable ? null : url;
+	const result = await client.callTool("set_webhook", args);
+	ok(ctx, disable ? "Webhook disabled." : "Webhook set.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/insights.mjs

@@ -0,0 +1,51 @@
+// `insights` — Search Console impressions/clicks across the phantom network, at the
+// network, single-post, and top-posts levels. Ported from phantomstory-cli's
+// insights.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, requirePositional, printResult, compact } from "./shared.mjs";
+
+export async function cmdInsights(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "site":
+			return insightsSite(rest);
+		case "post":
+			return insightsPost(rest);
+		case "top":
+			return insightsTop(rest);
+		default:
+			throw new CliError(`Unknown insights subcommand: ${sub ?? "(none)"}. Try: site, post, top`);
+	}
+}
+
+async function insightsSite(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ period: flagStr(flags.period), collection_id: flagStr(flags.collection) });
+	const result = await client.callTool("get_site_performance", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function insightsPost(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const articleId = requirePositional(positionals, 0, "article-id");
+	const args = compact({ article_id: articleId, period: flagStr(flags.period) });
+	const result = await client.callTool("get_post_performance", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function insightsTop(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		period: flagStr(flags.period),
+		collection_id: flagStr(flags.collection),
+		limit: flagNum(flags.limit),
+		sort: flagStr(flags.sort),
+	});
+	const result = await client.callTool("list_top_posts", args);
+	printResult(io, flags, result);
+	return 0;
+}