@letterstory/cli 0.1.1 → 0.2.1

package/README.md

@@ -11,25 +11,42 @@ The CLI is plain ESM with **zero dependencies** and needs no build step (Node
 ```bash
 # from a checkout of this repo
 cd cli
-npm link          # puts `letterstory` on your PATH
+npm link          # puts `letterstory` (and `phantom`) on your PATH
 # …or run it directly without linking:
 node cli/bin/letterstory.mjs --help
 ```
 
+## `phantom` — the same CLI, Phantomstory-branded
+
+`phantom` is a ghost-branded entry point for demos and presentations — same binary, same
+commands, same auth, same guardrails as `letterstory`, just a different printed name:
+
+```bash
+phantom deploy create --name "My Blog" --theme gazette
+# 👻 phantom — deploy and manage Phantomstory blogs from your terminal
+```
+
+There is no separate implementation to keep in sync: `bin/phantom.mjs` sets one env var
+before importing `lib/cli.mjs`, which swaps the banner and command-hint strings and
+otherwise runs the exact same code path as `letterstory`.
+
 ## Authenticate
 
-You need a Letterstory API key (starts with `lb_`) with the `deployment:read` and
+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.
 
 ```bash
-letterstory login --key lb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+letterstory login --key ls_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).
 
+Run `letterstory whoami` (alias `status`) any time to confirm which key/url resolved and
+see your company profile.
+
 ## Spin up a blog
 
 ```bash
@@ -43,11 +60,32 @@ letterstory deploy create --name "My Blog" --theme gazette
 
 letterstory deploy list
 letterstory deploy get <deployment-id>
+letterstory deploy update <deployment-id> --name "New Name"
 letterstory deploy rebuild <deployment-id>      # after publishing new articles
+letterstory deploy diagnostics <deployment-id>  # why is my blog empty?
 letterstory deploy delete <deployment-id> --yes
 ```
 
-Pass `--no-wait` to return immediately and poll later with `deploy get`.
+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
 
@@ -56,22 +94,117 @@ letterstory domain check myblog.com                       # price it (no charge)
 letterstory domain buy <deployment-id> myblog.com        # buys + attaches the domain
 ```
 
+`blogs` and `domains` are aliases for `deploy` and `domain` — the exact same commands
+under Phantomstory's vocabulary (`blogs ls`, `blogs new`, `blogs rm`, `blogs update`,
+`domains buy`, etc. all call the identical handler as their `deploy`/`domain`
+counterpart). Use whichever set of verbs you prefer; both are always available from
+both `letterstory` and `phantom`.
+
+## Content
+
+```bash
+letterstory posts list [--limit <n>] [--collection <uuid>]
+letterstory posts show <article-id>
+letterstory posts new --title "…" --collection <uuid> --body "…"     # or --file <path|->
+letterstory posts publish <article-id>
+letterstory posts unpublish <article-id>
+
+letterstory published list [--limit <n>] [--collection <uuid>] [--format html|md]
+letterstory published show --slug my-post-slug [--format html|md]    # or --id <uuid>
+```
+
+## Collections
+
+```bash
+letterstory collections list
+letterstory collections new --name "Launches" --description "…"
+letterstory collections update <id> --cadence-target 4 --cadence-period week
+letterstory collections delete <id> --yes
+letterstory collections assign <article-id> <collection-id>
+```
+
+## Flows
+
+Run an editorial pass over an article, check on it, and manage the completion webhook:
+
+```bash
+letterstory flows list
+letterstory flows run <flow-id> <article-id>
+letterstory flows status <run-id>
+
+letterstory flows webhook get
+letterstory flows webhook set --url https://hooks.example.com/x --secret s3cr3t
+letterstory flows webhook set --url none        # disable it
+```
+
+## Connectors
+
+Publish a finished article out to an external CMS or doc target:
+
+```bash
+letterstory connectors list
+letterstory connectors publish <article-id> --to webflow --target <target-uuid>
+letterstory connectors status --connector webflow --publish-id <id>
+```
+
+## Strategy & onboarding
+
+```bash
+letterstory strategy company get
+letterstory strategy company set --name "Acme" --domain acme.com --manifesto "…"
+
+letterstory strategy positioning get
+letterstory strategy positioning set --topic seo --topic ai --stance "…" --clear-avoid
+
+letterstory strategy competitors list
+letterstory strategy competitors add "Rival Co" rival.com
+
+letterstory strategy sitemap --collection <uuid> --url https://x.com/sitemap.xml
+
+letterstory onboarding status
+letterstory onboarding step --complete connect_domain
+```
+
+## Insights
+
+Search Console performance, network-wide, per post, or top posts:
+
+```bash
+letterstory insights site [--period 14d|30d|90d] [--collection <uuid>]
+letterstory insights post <article-id> [--period 14d|30d|90d]
+letterstory insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]
+```
+
 ## Anything else
 
-Every Letterstory tool is reachable, not just the deployment ones:
+Every Letterstory tool is reachable, not just the ones with a dedicated command group:
 
 ```bash
-letterstory tools                                  # list all tools
+letterstory whoami                                 # or: status — verify your key + who it's for
+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                |
-| `--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/bin/phantom.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Ghost-branded entry point for Phantomstory demos/presentations. Sets the brand
+// flag `lib/cli.mjs` reads before importing it, then defers to the exact same
+// run() as `letterstory.mjs` — same auth, same commands, same guardrails, only
+// the printed name and banner differ.
+process.env.LETTERSTORY_CLI_BRAND = "phantom";
+
+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

@@ -2,24 +2,69 @@
 // 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";
+import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import {
+	cmdLogin,
+	cmdLogout,
+	cmdConfig,
+	cmdWhoami,
+	cmdTools,
+	cmdCall,
+	cmdTool,
+	cmdMcp,
+	cmdDeploy,
+	cmdDomain,
+	cmdBlogs,
+	cmdDomains,
+	cmdPosts,
+	cmdPublished,
+	cmdCollections,
+	cmdFlows,
+	cmdConnectors,
+	cmdStrategy,
+	cmdOnboarding,
+	cmdInsights,
+} from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.1";
 
 // 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"]);
+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
+// positioning set`) accumulates into an array; a single occurrence stays a plain
+// string, so every existing single-value flag read is unaffected.
 /**
  * @param {string[]} argv
- * @returns {{ positionals: string[], flags: Record<string, string | boolean> }}
+ * @returns {{ positionals: string[], flags: Record<string, string | boolean | string[]> }}
  */
 export function parseArgs(argv) {
 	const positionals = [];
 	const flags = {};
+	const setFlag = (name, value) => {
+		if (Object.prototype.hasOwnProperty.call(flags, name)) {
+			flags[name] = [].concat(flags[name], value);
+		} else {
+			flags[name] = value;
+		}
+	};
 	for (let i = 0; i < argv.length; i++) {
 		const tok = argv[i];
 		if (!tok.startsWith("--")) {
@@ -28,7 +73,7 @@ export function parseArgs(argv) {
 		}
 		const eq = tok.indexOf("=");
 		if (eq !== -1) {
-			flags[tok.slice(2, eq)] = tok.slice(eq + 1);
+			setFlag(tok.slice(2, eq), tok.slice(eq + 1));
 			continue;
 		}
 		const name = tok.slice(2);
@@ -36,7 +81,7 @@ export function parseArgs(argv) {
 		if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) {
 			flags[name] = true;
 		} else {
-			flags[name] = next;
+			setFlag(name, next);
 			i++;
 		}
 	}
@@ -47,17 +92,34 @@ function str(v) {
 	return typeof v === "string" ? v : undefined;
 }
 
-export const HELP = `letterstory — spin up and manage Letterstory phantom blogs from your terminal
+// Same binary, two names: `phantom` is a ghost-branded entry point for Phantomstory
+// demos (bin/phantom.mjs sets this before importing us) that shares every code path —
+// auth, config, commands — with `letterstory`. No behavior differs, only this string.
+export function binName() {
+	return process.env.LETTERSTORY_CLI_BRAND === "phantom" ? "phantom" : "letterstory";
+}
+
+function buildHelp(bin) {
+	const heading =
+		bin === "phantom"
+			? "👻 phantom — deploy and manage Phantomstory blogs from your terminal"
+			: "letterstory — spin up and manage Letterstory phantom blogs from your terminal";
+	return `${heading}
 
 Usage:
-  letterstory <command> [args] [--flags]
+  ${bin} <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)
+  login [--url <url>]                Sign in via your browser (default url: https://app.letterstory.com)
+  login --key <ls_…> [--url <url>]   Save a static API key instead (for CI/automation)
+  logout                             Forget saved credentials (revokes an OAuth session, if any)
+  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
@@ -70,28 +132,101 @@ Custom domains:
   domain check <domain>                              Price a domain (read-only, no charge)
   domain buy <deployment-id> <domain>                Buy + attach a custom domain
 
+  "blogs" and "domains" are aliases for "deploy" and "domain" (same commands, ls/new/
+  show/update/rm verbs also accepted) — use whichever vocabulary you prefer.
+
+Content:
+  posts list [--limit <n>] [--collection <uuid>]     List your articles
+  posts show <article-id>                            Show one article
+  posts new --title <t> --collection <uuid> (--body <text> | --file <path|->)
+  posts publish <article-id>                         Publish an article
+  posts unpublish <article-id>                       Unpublish an article
+  published list [--limit <n>] [--collection <uuid>] [--format html|md]
+  published show (--id <uuid> | --slug <slug>) [--format html|md]
+
+Collections:
+  collections list                                   List your collections
+  collections new --name <n> [--description <text>]
+  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month]
+  collections delete <id> --yes
+  collections assign <article-id> <collection-id>
+
+Flows:
+  flows list                                          List available editorial flows
+  flows run <flow-id> <article-id>                    Start a flow run
+  flows status <run-id>                                Show a flow run's status
+  flows webhook get                                    Show the completion webhook
+  flows webhook set --url <https://…|none|off> [--secret <secret>]
+
+Connectors:
+  connectors list                                      List external publish destinations
+  connectors publish <article-id> --to <connector> --target <uuid> [--flow-run <uuid>]
+  connectors status --connector <connector> --publish-id <id>
+
+Strategy & onboarding:
+  strategy company get | set [--name] [--domain] [--manifesto <text>|--manifesto-file <path>]
+  strategy positioning get | set [--topic <t> …] [--stance <s> …] [--avoid <t> …]
+                                 [--clear-topics] [--clear-stances] [--clear-avoid]
+  strategy competitors list | add <name> <domain>
+  strategy sitemap --collection <uuid> --url <sitemap_url> [--sub <url> …] [--pattern <glob>]
+  onboarding status                                    Show the onboarding checklist
+  onboarding step [--current <step>] [--complete <step>] [--skip <step>] [--status <status>]
+
+Insights:
+  insights site [--period 14d|30d|90d] [--collection <uuid>]
+  insights post <article-id> [--period 14d|30d|90d]
+  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:
   --json          Machine-readable output
+  --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, or bare deploy: print what would happen, don't call the API
   --url <url>     Override the API base URL for this invocation
-  --key <lb_…>    Override the API key for this invocation
+  --key <ls_…>    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,
+	whoami: cmdWhoami,
+	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.
+	blogs: cmdBlogs,
+	domains: cmdDomains,
+	posts: cmdPosts,
+	published: cmdPublished,
+	collections: cmdCollections,
+	flows: cmdFlows,
+	connectors: cmdConnectors,
+	strategy: cmdStrategy,
+	onboarding: cmdOnboarding,
+	insights: cmdInsights,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an
@@ -120,27 +255,42 @@ export function defaultIo() {
 export async function run(argv, io = defaultIo()) {
 	const { positionals, flags } = parseArgs(argv);
 	const command = positionals[0];
+	const bin = binName();
 
 	if (flags.version || command === "version") {
 		io.log(VERSION);
 		return 0;
 	}
 	if (!command || command === "help" || flags.help) {
-		io.log(HELP);
+		io.log(buildHelp(bin));
 		return 0;
 	}
 
 	const handler = CLIENT_COMMANDS[command];
 	if (!handler) {
 		io.error(`Unknown command: ${command}`);
-		io.error(`Run \`letterstory help\` for usage.`);
+		io.error(`Run \`${bin} 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 };
+		// A silent refresh mid-command should persist the new tokens so the next
+		// invocation doesn't have to refresh again — but only when the config we
+		// resolved actually came from a saved OAuth session (a --key/env override
+		// for this one call shouldn't get written back to disk as a login).
+		const onTokensRefreshed =
+			config.keySource === "oauth" ? (oauth) => writeConfigFile({ ...readConfigFile(), oauth }) : undefined;
+		const client = new LetterstoryClient({
+			url: config.url,
+			key: config.key,
+			oauth: config.oauth,
+			onTokensRefreshed,
+			verbose: Boolean(flags.verbose),
+			verboseLog: io.error,
+			bin,
+		});
+		const ctx = { client, config, positionals: positionals.slice(1), flags, io, bin };
 		return await handler(ctx);
 	} catch (err) {
 		if (err instanceof CliError) {

package/lib/client.mjs

@@ -30,7 +30,7 @@ export function readConfigFile() {
 	}
 }
 
-// The file holds an lb_ API key, so it's written owner-only (0600) and the mode is
+// The file holds an ls_ 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();
@@ -46,23 +46,41 @@ export function clearConfigFile() {
 	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.
+// Precedence: explicit flags > env > config file (OAuth tokens from a browser
+// login, then a static key) > built-in default. keySource is surfaced so
+// `config` can show where the credential came from. The URL defaults to prod.
+//
+// A static --key/env key always wins over a saved browser login — that's the
+// CI/automation path and it should never silently fall back to a stale OAuth
+// session saved on the same machine.
 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,
-	};
+	const resolvedUrl = url || process.env.LETTERSTORY_API_URL || file.url || DEFAULT_API_URL;
+
+	const explicitKey = key || process.env.LETTERSTORY_API_KEY || null;
+	if (explicitKey) {
+		return { url: resolvedUrl, key: explicitKey, oauth: null, keySource: key ? "flag" : "env" };
+	}
+	if (file.oauth?.access_token) {
+		return { url: resolvedUrl, key: null, oauth: file.oauth, keySource: "oauth" };
+	}
+	return { url: resolvedUrl, key: file.key || null, oauth: null, keySource: file.key ? "file" : "none" };
 }
 
 export class LetterstoryClient {
-	constructor({ url, key, fetchImpl } = {}) {
+	// `oauth` is { access_token, refresh_token, expires_at, scope } from a
+	// browser login. `onTokensRefreshed(oauth)` is called after a successful
+	// silent refresh so the caller can persist the new tokens to disk —
+	// this class never touches the config file itself.
+	constructor({ url, key, oauth, fetchImpl, onTokensRefreshed, verbose, verboseLog, bin } = {}) {
 		this.url = (url || DEFAULT_API_URL).replace(/\/+$/, "");
 		this.key = key || null;
+		this.oauth = oauth || null;
 		this.fetch = fetchImpl || globalThis.fetch;
+		this.onTokensRefreshed = onTokensRefreshed || (() => {});
+		this.bin = bin || "letterstory";
+		this.verbose = Boolean(verbose);
+		this.verboseLog = verboseLog || ((m) => process.stderr.write(`${m}\n`));
 	}
 
 	get mcpEndpoint() {
@@ -72,22 +90,36 @@ export class LetterstoryClient {
 	// Unauthenticated discovery (GET /api/mcp): tool names + descriptions, no schema.
 	// Lets `letterstory tools` work before you've logged in.
 	async discover() {
+		if (this.verbose) this.verboseLog(`» GET ${this.mcpEndpoint}`);
 		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 (this.verbose) this.verboseLog(`« ${res.status}`);
 		if (!res.ok) throw new CliError(`Discovery failed (HTTP ${res.status}) at ${this.mcpEndpoint}`);
 		return res.json();
 	}
 
+	authHeaders() {
+		if (this.oauth?.access_token) return { authorization: `Bearer ${this.oauth.access_token}` };
+		if (this.key) return { "x-integrations-key": this.key };
+		return null;
+	}
+
 	// 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.");
+	// needs no prior initialize handshake. When authenticated via OAuth, a single
+	// 401 triggers one silent refresh-and-retry before giving up — a static key
+	// has no such recovery, since a rejected key is just wrong.
+	async rpc(method, params, { _retried = false } = {}) {
+		const authHeaders = this.authHeaders();
+		if (!authHeaders) {
+			throw new CliError(
+				`Not logged in. Run \`${this.bin} login\` (opens your browser) or \`${this.bin} login --key <ls_…>\`.`
+			);
 		}
+		if (this.verbose) this.verboseLog(`» POST ${this.mcpEndpoint} (${method})`);
 		let res;
 		try {
 			res = await this.fetch(this.mcpEndpoint, {
@@ -95,16 +127,23 @@ export class LetterstoryClient {
 				headers: {
 					"content-type": "application/json",
 					accept: "application/json",
-					"x-integrations-key": this.key,
+					...authHeaders,
 				},
 				body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
 			});
 		} catch (err) {
 			throw new CliError(`Could not reach ${this.mcpEndpoint}: ${err.message}`);
 		}
+		if (this.verbose) this.verboseLog(`« ${res.status}`);
 		// 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.`);
+			if (!_retried && this.oauth?.refresh_token && (await this.tryRefresh())) {
+				return this.rpc(method, params, { _retried: true });
+			}
+			const hint = this.oauth
+				? `Your session has expired. Run \`${this.bin} login\` again.`
+				: "Check your API key and its capabilities.";
+			throw new CliError(`Authentication failed (HTTP ${res.status}). ${hint}`);
 		}
 		const body = await res.json().catch(() => null);
 		if (!body) throw new CliError(`Unexpected non-JSON response (HTTP ${res.status}) from ${this.mcpEndpoint}`);
@@ -115,6 +154,29 @@ export class LetterstoryClient {
 		return body.result;
 	}
 
+	// Best-effort silent refresh. Returns false (never throws) so rpc() can
+	// fall through to its normal "please log in again" error on any failure.
+	async tryRefresh() {
+		try {
+			const { refreshAccessToken } = await import("./oauth.mjs");
+			const tokens = await refreshAccessToken({
+				url: this.url,
+				refreshToken: this.oauth.refresh_token,
+				fetchImpl: this.fetch,
+			});
+			this.oauth = {
+				access_token: tokens.access_token,
+				refresh_token: tokens.refresh_token || this.oauth.refresh_token,
+				expires_at: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+				scope: tokens.scope,
+			};
+			this.onTokensRefreshed(this.oauth);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
 	async listTools() {
 		const result = await this.rpc("tools/list", {});
 		return result?.tools ?? [];