@sprid/cli 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.8 - 2026-09-25
+
+- `sprid screenshots` draws a device that looks like one: a metal band with side
+  buttons, a thin bezel, and the camera each platform has. `frameImages` in the
+  config swaps in device artwork you hold a licence for (`@sprid/shots` 0.1.2).
+
+## 0.1.7 - 2026-09-24
+
+- `sprid connect meta-ads --account <slug>` connects the Meta ad account Sprid
+  runs campaigns in. `--page` and `--ad-account` pick among several, `--dataset`
+  binds the Events Manager dataset conversion campaigns report to. `sprid docs
+  meta-ads` is the setup guide.
+- Usage telemetry. When signed in, each command reports its name, a documented
+  subcommand, exit code, error kind, duration and versions to your Sprid
+  account, so failures and slow commands show up without anyone filing a bug.
+  Never arguments, paths or file contents, never a third party. The first run
+  only prints a notice. `sprid telemetry off`, `DO_NOT_TRACK=1` or
+  `SPRID_TELEMETRY=0` turns it off; `sprid telemetry` shows which setting
+  decided.
+
 ## 0.1.6 - 2026-09-24
 
 - `sprid connect <service> --key-from-clipboard` reads a copied key from the

package/README.md

@@ -216,8 +216,19 @@ body of `PATCH /api/app-profiles/:id`. They are stored encrypted and no route ev
 returns them. `sprid connect <platform>` only opens the platform’s OAuth page and waits for the
 result. Publishing requires the relevant approval or publishing command.
 
-No background telemetry. Credentials stay out of normal output. Build tools can
-print their own logs; do not include secrets in custom build commands.
+Usage telemetry: when you are signed in, each command ends with one request to
+`POST /api/cli/events` on the API you are signed in to, carrying the command name,
+a documented subcommand (`post push`, never a slug or a file name), the exit code,
+an error kind (an HTTP status, or usage/network/other, never the message), the
+duration, the CLI and Node versions, the OS and whether `CI` is set. Never
+arguments, paths, output or file contents, and nothing goes to any third party.
+The first run that could send only prints a notice. It waits at most one second
+and a failure is ignored. Turn it off with `sprid telemetry off` (saved in
+`~/.sprid/telemetry.json`), or for one shell with `DO_NOT_TRACK=1` or
+`SPRID_TELEMETRY=0`; `help`, `version`, `completion` and `mcp` never send.
+
+Credentials stay out of normal output. Build tools can print their own logs; do
+not include secrets in custom build commands.
 
 ## Updates
 

package/bin.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { run } from "./src/cli.mjs";
 
-run(process.argv.slice(2), { notifyUpdates: true }).then(
+run(process.argv.slice(2), { notifyUpdates: true, telemetry: true }).then(
   // Let stdout drain. An explicit exit truncates large review packets when
   // another process is reading the CLI through a pipe.
   (code) => { process.exitCode = code ?? 0; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -38,8 +38,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@sprid/shots": "0.1.1",
-    "@sprid/release": "0.1.1"
+    "@sprid/shots": "0.1.2",
+    "@sprid/release": "0.1.2"
   },
   "publishConfig": {
     "access": "public"

package/src/args.mjs

@@ -15,7 +15,10 @@ export const VALUE_FLAGS = new Set([
   "platform",
   "entry",
   "account",
+  "accounts",
   "page",
+  "ad-account",
+  "dataset",
   "app",
   "key",
   "key-id",
@@ -62,9 +65,27 @@ export const VALUE_FLAGS = new Set([
   "alt-text",
   "ai-disclosures",
   "bookmark",
+  // tool, events, inbox, ads, schedule
+  "args",
+  "kind",
+  "label",
+  "areas",
+  "why",
+  "at",
+  "intent",
+  "count",
+  "daily-cents",
+  "objective",
+  "platforms",
+  "options",
+  "ids",
+  "cadence",
+  "times",
+  "start",
+  "time",
 ]);
 
-export const BOOL_FLAGS = new Set(["json", "offline", "check", "no-browser", "from-local", "help", "version", "unanswered", "yes", "clear", "refresh", "cached-only"]);
+export const BOOL_FLAGS = new Set(["json", "offline", "check", "no-browser", "from-local", "help", "version", "unanswered", "yes", "clear", "refresh", "cached-only", "next", "queue-end", "shift-later", "dry-run", "skip-busy"]);
 
 /**
  * `sprid connect asc --app myapp --key ./k.p8 --json`

package/src/cli.mjs

@@ -39,6 +39,11 @@ import { getHelp, renderHelp, suggest } from "./docs/help.mjs";
 import { completion } from "./commands/completion.mjs";
 
 import { doctor, update, notifyUpdate } from './commands/update.mjs';
+import { telemetry, reportCommand } from './telemetry.mjs';
+import { tool } from "./commands/tool.mjs";
+import { events } from "./commands/events.mjs";
+import { inbox } from "./commands/inbox.mjs";
+import { ads } from "./commands/ads.mjs";
 
 export const VERSION = readVersion();
 
@@ -54,7 +59,7 @@ function readVersion() {
 export const COMMANDS = {
   plan, research,
   media, capabilities, completion,
-  screenshots, release, doctor, update,
+  screenshots, release, doctor, update, telemetry,
   apps, insights, account,
   docs,
   login: auth.login,
@@ -75,6 +80,10 @@ export const COMMANDS = {
   reviews: reviews.reviews,
   "marketing-review": marketingReview,
   post: post.post,
+  tool,
+  events,
+  inbox,
+  ads,
   pinterest,
   help: help,
 };
@@ -240,18 +249,31 @@ export async function run(argv, io = {}) {
     return 2;
   }
 
+  const startedAt = Date.now();
+  let code, failure = null;
   try {
     if (io.notifyUpdates && !flags.offline && ["status", "next"].includes(command)) await notifyUpdate(ctx).catch(() => {});
-    const code = await fn(ctx);
-    return code ?? 0;
+    code = (await fn(ctx)) ?? 0;
   } catch (e) {
-    const code = e && e.exitCode ? e.exitCode : 1;
+    failure = e;
+    code = e && e.exitCode ? e.exitCode : 1;
     const message = e && e.message ? e.message : String(e);
     if (json) {
       write(JSON.stringify({ ok: false, error: message, status: e?.status ?? null }) + "\n");
     } else {
       writeErr(`  ${C.bad("✗")} ${message}\n`);
     }
-    return code;
   }
+  // Only the installed binary reports (bin.mjs passes this); tests and
+  // embedders do not. See telemetry.mjs for exactly what is sent.
+  if (io.telemetry) {
+    await reportCommand(ctx, {
+      command,
+      words: passthrough ? parsed.commandArgv : positionals,
+      exitCode: code,
+      durationMs: Date.now() - startedAt,
+      error: failure,
+    });
+  }
+  return code;
 }

package/src/commands/ads.mjs

@@ -0,0 +1,110 @@
+// sprid ads: paid campaigns on Meta through the same tools the ads skill
+// calls. Everything is created paused. The two verbs that change what is spent
+// (launch, budget) show what they commit and ask, and need a token holding
+// ads:spend; the server refuses them otherwise.
+
+import { UsageError } from "../args.mjs";
+import { C, OK } from "../format.mjs";
+import { callTool, needInt, readJson, show } from "../tools.mjs";
+import { confirm } from "./reviews.mjs";
+
+const USAGE = [
+  "sprid ads [overview] --account <slug>",
+  "sprid ads status|council|metrics <adSetId> --account <slug> [--days N]",
+  "sprid ads create campaign|set|creative|ad|batch --file <args.json> --account <slug>",
+  "sprid ads launch <adSetId> --account <slug> [--yes]",
+  "sprid ads budget <adSetId> --daily-cents N --account <slug> [--yes]",
+  "sprid ads pause <adSetId> --account <slug> [--yes]",
+  "sprid ads close <adSetId> --account <slug>",
+].join("\n  ");
+
+/** What `create <thing>` calls. The file carries the tool's arguments. */
+const CREATE = {
+  campaign: "create_ad_campaign",
+  set: "create_ad_set",
+  creative: "create_ad_creative",
+  ad: "create_ad",
+  batch: "create_ad_batch",
+};
+const READS = { status: "ad_status", council: "ad_council", metrics: "ad_metrics" };
+
+export async function ads(ctx) {
+  const [sub, arg] = ctx.positionals;
+  const account = ctx.flags.account;
+  if (typeof account !== "string") throw new UsageError(USAGE);
+  if (!sub || sub === "overview") {
+    show(ctx, await callTool(ctx, "ads_overview", { account }));
+    return 0;
+  }
+  if (READS[sub]) {
+    const adSetId = needInt(arg, `sprid ads ${sub} <adSetId> --account <slug>`);
+    const days = ctx.flags.days && sub !== "status" ? { days: Number(ctx.flags.days) } : {};
+    show(ctx, await callTool(ctx, READS[sub], { account, adSetId, ...days }));
+    return 0;
+  }
+  if (sub === "create") {
+    const tool = CREATE[arg];
+    if (!tool || typeof ctx.flags.file !== "string") throw new UsageError(`sprid ads create ${Object.keys(CREATE).join("|")} --file <args.json> --account <slug>\n  Arguments: sprid tool describe ${tool ?? "create_ad_campaign"}`);
+    show(ctx, await callTool(ctx, tool, { ...(await readJson(ctx, ctx.flags.file)), account }));
+    return 0;
+  }
+  if (sub === "launch") return launch(ctx, account, needInt(arg, "sprid ads launch <adSetId> --account <slug> [--yes]"));
+  if (sub === "budget") return budget(ctx, account, needInt(arg, "sprid ads budget <adSetId> --daily-cents N --account <slug> [--yes]"));
+  if (sub === "pause") return pause(ctx, account, needInt(arg, "sprid ads pause <adSetId> --account <slug> [--yes]"));
+  if (sub === "close") {
+    show(ctx, await callTool(ctx, "close_ad_set", { account, adSetId: needInt(arg, "sprid ads close <adSetId> --account <slug>") }));
+    return 0;
+  }
+  throw new UsageError(USAGE);
+}
+
+/**
+ * Ask before a call that spends or resets learning. --yes skips the prompt.
+ * Without a terminal (or with --json) there is nobody to ask, so it stops
+ * with exit 2; a person who answers no gets exit 1.
+ */
+async function approve(ctx, summary, question) {
+  if (ctx.flags.yes) return 0;
+  if (ctx.json || !ctx.stdin?.isTTY) {
+    const msg = "Re-run with --yes to go ahead without the prompt.";
+    if (ctx.json) ctx.out({ ok: false, error: msg, summary });
+    else {
+      ctx.print(`  ${summary}`);
+      ctx.warn(`  ✗ ${msg}`);
+    }
+    return 2;
+  }
+  ctx.print(`  ${summary}\n`);
+  if (await confirm(ctx, `  ${question} [y/N] `)) return 0;
+  ctx.print("  Nothing changed.");
+  return 1;
+}
+
+async function launch(ctx, account, adSetId) {
+  const preview = await callTool(ctx, "launch_ads", { account, adSetId, confirmed: false });
+  const stop = await approve(ctx, preview?.message ?? `Launch ad set ${adSetId}.`, "Launch and start spending?");
+  if (stop) return stop;
+  const res = await callTool(ctx, "launch_ads", { account, adSetId, confirmed: true });
+  if (ctx.json) ctx.out(res);
+  else ctx.print(`  ${C.ok(OK)} Ad set ${adSetId} is live. Leave it alone for 3 days: every edit resets Meta's learning phase.`);
+  return 0;
+}
+
+async function budget(ctx, account, adSetId) {
+  const cents = Number(ctx.flags["daily-cents"]);
+  if (!Number.isInteger(cents) || cents <= 0) throw new UsageError("Pass the new daily budget in cents: --daily-cents 1500 is 15.00 a day.");
+  const summary = `Set ad set ${adSetId}'s daily budget to ${(cents / 100).toFixed(2)}. It is checked against the account's daily and per-campaign caps.`;
+  const stop = await approve(ctx, summary, "Change the budget?");
+  if (stop) return stop;
+  show(ctx, await callTool(ctx, "update_ad_budget", { account, adSetId, dailyBudgetCents: cents }));
+  return 0;
+}
+
+async function pause(ctx, account, adSetId) {
+  const stop = await approve(ctx, `Pause ad set ${adSetId}. Pausing resets Meta's learning phase when it resumes.`, "Pause it?");
+  if (stop) return stop;
+  const res = await callTool(ctx, "pause_ad_set", { account, adSetId });
+  if (ctx.json) ctx.out(res);
+  else ctx.print(`  ${C.ok(OK)} Ad set ${adSetId} paused.`);
+  return 0;
+}

package/src/commands/connect.mjs

@@ -22,6 +22,25 @@ import { confirm } from "./reviews.mjs";
 import { expandHome, listProfiles, patchProfile, readKeyFile, readLocalApp, resolveProfile } from "../profiles.mjs";
 
 export const CHANNEL_PLATFORMS = ["instagram", "tiktok", "youtube", "linkedin", "facebook", "pinterest", "x"];
+// Connects like a channel, through the platform's sign-in, but never publishes:
+// it is the ad account Sprid runs campaigns in. The CLI spells it with a hyphen
+// like every other target; the server's platform id has an underscore.
+const AD_CHANNELS = {
+  "meta-ads": "meta_ads",
+  meta_ads: "meta_ads",
+  "google-ads": "google_ads",
+  google_ads: "google_ads",
+  "tiktok-ads": "tiktok_ads",
+  tiktok_ads: "tiktok_ads",
+};
+// Connects like a channel but neither publishes nor pays: the TikTok account
+// holder's grant that lets the Inbox read and answer comments on its posts.
+const INBOX_CHANNELS = {
+  "tiktok-comments": "tiktok_accounts",
+  "tiktok-accounts": "tiktok_accounts",
+  tiktok_accounts: "tiktok_accounts",
+};
+const channelPlatform = (what) => (CHANNEL_PLATFORMS.includes(what) ? what : AD_CHANNELS[what] ?? INBOX_CHANNELS[what]);
 export const SENSOR_SERVICES = [
   "asc",
   "play",
@@ -85,11 +104,11 @@ export async function connect(ctx) {
   const [what] = ctx.positionals;
   if (ctx.flags["from-local"]) return fromLocal(ctx);
   if (!what) return wizard(ctx);
-  if (CHANNEL_PLATFORMS.includes(what)) return connectChannel(ctx, what);
+  if (channelPlatform(what)) return connectChannel(ctx, channelPlatform(what));
   if (SENSOR_SERVICES.includes(what)) return connectSensor(ctx, what);
   if (PROVIDERS.includes(what)) return connectProvider(ctx, what);
   throw new UsageError(
-    `Unknown target "${what}". Channels: ${CHANNEL_PLATFORMS.join(", ")}. Keys: ${SENSOR_SERVICES.join(", ")}. Model keys: ${PROVIDERS.join(", ")}.`,
+    `Unknown target "${what}". Channels: ${CHANNEL_PLATFORMS.join(", ")}, meta-ads. Keys: ${SENSOR_SERVICES.join(", ")}. Model keys: ${PROVIDERS.join(", ")}.`,
   );
 }
 
@@ -215,10 +234,19 @@ async function connectChannel(ctx, platform) {
   const returnUrl = `${ctx.appUrl()}/connected`;
   const auth = ctx.auth();
   const pageId = ctx.flags.page;
-  if (pageId && platform !== "facebook") throw new UsageError("--page is only supported for Facebook connections.");
-  const pending = pendingGrant(ctx, `channel:${auth.apiUrl}:${auth.token}:${account}:${platform}:${pageId ?? ""}`);
+  const adAccountId = ctx.flags["ad-account"];
+  const pixelId = ctx.flags.dataset;
+  if (pageId && platform !== "facebook" && platform !== "meta_ads") throw new UsageError("--page is only supported for Facebook and Meta Ads connections.");
+  if (adAccountId && !["meta_ads", "google_ads", "tiktok_ads"].includes(platform)) throw new UsageError("--ad-account is only supported for Meta Ads, Google Ads and TikTok Ads connections.");
+  if (pixelId && platform !== "meta_ads") throw new UsageError("--dataset is only supported for Meta Ads connections.");
+  const selection = {
+    ...(pageId ? { pageId: String(pageId) } : {}),
+    ...(adAccountId ? { adAccountId: String(adAccountId) } : {}),
+    ...(pixelId ? { pixelId: String(pixelId) } : {}),
+  };
+  const pending = pendingGrant(ctx, `channel:${auth.apiUrl}:${auth.token}:${account}:${platform}:${pageId ?? ""}:${adAccountId ?? ""}:${pixelId ?? ""}`);
   const previous = pending.read();
-  const { url, pendingId } = previous ?? await ctx.api().post(`/api/channels/connect/${platform}`, { accountSlug: account, returnUrl, ...(pageId ? { pageId } : {}) });
+  const { url, pendingId } = previous ?? await ctx.api().post(`/api/channels/connect/${platform}`, { accountSlug: account, returnUrl, ...selection });
   if (!url) throw new ApiError(500, "The server returned no authorize URL.");
   if (!previous && pendingId) pending.write({ url, pendingId, expiresAt: Date.now() + PENDING_TIMEOUT_MS });
 
@@ -244,7 +272,8 @@ async function connectChannel(ctx, platform) {
   const s = last?.status ?? "pending";
   if (s === "connected") {
     pending.clear();
-    const handle = last.channel?.displayName ? `@${last.channel.displayName}` : label(platform);
+    const handle = !last.channel?.displayName ? label(platform)
+      : ["meta_ads", "google_ads", "tiktok_ads"].includes(platform) ? last.channel.displayName : `@${last.channel.displayName}`;
     if (ctx.json) ctx.out({ ok: true, status: s, channel: last.channel, account });
     else ctx.print(`  ${C.ok(OK)} ${handle} connected to ${account}`);
     return 0;
@@ -254,7 +283,7 @@ async function connectChannel(ctx, platform) {
       ? `${last.error || "That login is already connected to another account."} Move it in Settings → Accounts, or connect a different login.`
       : s === "expired" || s === "pending"
         ? "Timed out waiting for the browser (10 minutes). Run the command again."
-      : last?.error || `Connect ${s}.`;
+      : cliFlags(last?.error) || `Connect ${s}.`;
   if (s !== "pending") pending.clear();
   if (ctx.json) {
     ctx.out({ ok: false, status: s, error: message, channel: last?.channel ?? null });
@@ -264,7 +293,12 @@ async function connectChannel(ctx, platform) {
 }
 
 function label(platform) {
-  return { instagram: "Instagram", tiktok: "TikTok", youtube: "YouTube", linkedin: "LinkedIn", facebook: "Facebook", pinterest: "Pinterest", x: "X" }[platform] ?? platform;
+  return { instagram: "Instagram", tiktok: "TikTok", youtube: "YouTube", linkedin: "LinkedIn", facebook: "Facebook", pinterest: "Pinterest", x: "X", meta_ads: "Meta Ads", google_ads: "Google Ads", tiktok_ads: "TikTok Ads", tiktok_accounts: "TikTok comments" }[platform] ?? platform;
+}
+
+/** The server names the fields to re-run with; here they are flags. */
+function cliFlags(message) {
+  return message?.replace(/\bpageId\b/g, "--page").replace(/\badAccountId\b/g, "--ad-account");
 }
 
 // ─── sensors (keys) ──────────────────────────────────────────────────────────
@@ -595,12 +629,12 @@ async function fromLocal(ctx) {
  *              server refuses to forget a channel that has published.
  */
 export async function disconnect(ctx) {
-  const [platform] = ctx.positionals;
+  const platform = channelPlatform(ctx.positionals[0]);
   const account = ctx.flags.account;
   const forget = !!ctx.flags.forget;
-  if (!platform || !CHANNEL_PLATFORMS.includes(platform)) {
+  if (!platform) {
     throw new UsageError(
-      `sprid disconnect <${CHANNEL_PLATFORMS.join("|")}> --account <slug> [--forget]`,
+      `sprid disconnect <${[...CHANNEL_PLATFORMS, "meta-ads"].join("|")}> --account <slug> [--forget]`,
     );
   }
   if (!account) throw new UsageError(`sprid disconnect ${platform} --account <slug>`);

package/src/commands/events.mjs

@@ -0,0 +1,60 @@
+// sprid events: the milestones Insights draws on its graphs. A change that
+// can move a number gets logged with the graphs it explains (--areas) and why,
+// or the next read of that graph cannot be explained.
+
+import { UsageError } from "../args.mjs";
+import { C, OK } from "../format.mjs";
+import { callTool, listFlag } from "../tools.mjs";
+
+const KINDS = ["release", "listing", "screenshots", "submission", "note"];
+const USAGE = `sprid events [list] [--days N] | add --kind ${KINDS.join("|")} --label "…" [--app <slug>] [--areas social,store,…] [--why "…"] [--at ISO]`;
+
+export async function events(ctx) {
+  const [sub] = ctx.positionals;
+  if (!sub || sub === "list") return list(ctx);
+  if (sub === "add") return add(ctx);
+  throw new UsageError(USAGE);
+}
+
+function workspaceArg(ctx) {
+  return ctx.flags.workspace ? { workspace: String(ctx.flags.workspace) } : {};
+}
+
+async function list(ctx) {
+  const days = ctx.flags.days ? Number(ctx.flags.days) : undefined;
+  const res = await callTool(ctx, "list_events", { ...workspaceArg(ctx), ...(days ? { days } : {}) });
+  if (ctx.json) {
+    ctx.out(res);
+    return 0;
+  }
+  const rows = Array.isArray(res) ? res : res?.events ?? [];
+  if (rows.length === 0) {
+    ctx.print("  No events in this window.");
+    return 0;
+  }
+  for (const e of rows) {
+    const areas = e.meta?.areas?.length ? C.dim(` [${e.meta.areas.join(", ")}]`) : "";
+    ctx.print(`  ${String(e.at ?? e.createdAt ?? "").slice(0, 10)}  ${e.kind.padEnd(11)}  ${e.label}${areas}`);
+    if (e.meta?.why) ctx.print(C.dim(`              ${e.meta.why}`));
+  }
+  return 0;
+}
+
+async function add(ctx) {
+  const kind = ctx.flags.kind;
+  const label = ctx.flags.label;
+  if (!KINDS.includes(kind) || typeof label !== "string") throw new UsageError(USAGE);
+  const args = {
+    ...workspaceArg(ctx),
+    kind,
+    label,
+    ...(ctx.flags.app ? { app: String(ctx.flags.app) } : {}),
+    ...(listFlag(ctx.flags.areas) ? { areas: listFlag(ctx.flags.areas) } : {}),
+    ...(typeof ctx.flags.why === "string" ? { why: ctx.flags.why } : {}),
+    ...(typeof ctx.flags.at === "string" ? { at: ctx.flags.at } : {}),
+  };
+  const res = await callTool(ctx, "add_event", args);
+  if (ctx.json) ctx.out(res);
+  else ctx.print(`  ${C.ok(OK)} Logged ${kind}: ${label}`);
+  return 0;
+}

package/src/commands/inbox.mjs

@@ -0,0 +1,124 @@
+// sprid inbox: comments on posts and ads plus store reviews, as the one ranked
+// queue the app's Inbox shows. Replying is public, so `reply` shows the text
+// and asks, the way `reviews reply` does. Store reviews are replied to with
+// `sprid reviews reply`; here they can only be filed.
+
+import { UsageError } from "../args.mjs";
+import { C, OK } from "../format.mjs";
+import { callTool, listFlag } from "../tools.mjs";
+import { confirm, stars, truncate } from "./reviews.mjs";
+
+const USAGE = "sprid inbox [--view needs_you|all|done] [--kind all|comment|review] [--accounts a,b] [--app <slug>] [--limit N] | draft <commentId> | reply <commentId> --text \"…\" [--yes] | done|flag|reopen <c:id|r:id>";
+const SOURCE = { instagram: "Instagram", youtube: "YouTube", app_store: "App Store", google_play: "Google Play" };
+
+export async function inbox(ctx) {
+  const [sub, ref] = ctx.positionals;
+  if (!sub) return list(ctx);
+  if (sub === "draft") return draft(ctx, ref);
+  if (sub === "reply") return reply(ctx, ref);
+  if (sub === "done" || sub === "flag" || sub === "reopen") return file(ctx, sub, ref);
+  throw new UsageError(USAGE);
+}
+
+async function list(ctx) {
+  const args = {
+    ...(ctx.flags.workspace ? { workspace: String(ctx.flags.workspace) } : {}),
+    ...(listFlag(ctx.flags.accounts ?? ctx.flags.account) ? { accounts: listFlag(ctx.flags.accounts ?? ctx.flags.account) } : {}),
+    ...(ctx.flags.app ? { app: String(ctx.flags.app) } : {}),
+    ...(typeof ctx.flags.view === "string" ? { view: ctx.flags.view } : {}),
+    ...(typeof ctx.flags.kind === "string" ? { kind: ctx.flags.kind } : {}),
+    ...(typeof ctx.flags.intent === "string" ? { intent: ctx.flags.intent } : {}),
+    ...(ctx.flags.limit ? { limit: Number(ctx.flags.limit) } : {}),
+  };
+  const res = await callTool(ctx, "list_inbox", args);
+  if (ctx.json) {
+    ctx.out(res);
+    return 0;
+  }
+  const items = res?.items ?? [];
+  if (items.length === 0) {
+    ctx.print("  Nothing here.");
+    return 0;
+  }
+  ctx.print(items.map(render).join("\n\n"));
+  if (res.more) ctx.print(C.dim(`\n  ${res.more} more. Raise --limit to see them.`));
+  return 0;
+}
+
+function render(item) {
+  const where = item.account?.slug ?? item.app?.slug ?? "";
+  const flag = item.urgent ? C.bad(" urgent") : item.overdue ? C.warn(" overdue") : "";
+  const rating = item.kind === "review" && item.rating ? ` ${stars(item.rating)}` : "";
+  const head = `  ${item.kind === "comment" ? "c" : "r"}:${item.id}  ${where}  ${SOURCE[item.source] ?? item.source}${item.onAd ? " ad" : ""}  ${item.intent}${rating}${flag}  ${C.dim(String(item.at ?? "").slice(0, 10))}`;
+  const lines = [head];
+  const text = [item.title, item.text].filter(Boolean).join(" · ");
+  lines.push(`  ${item.author ? `${item.author}: ` : ""}${truncate(text, 200)}`);
+  if (item.post?.title || item.post?.caption) lines.push(C.dim(`  on: ${truncate(item.post.title ?? item.post.caption, 80)}`));
+  lines.push(C.dim(item.kind === "comment" ? `  sprid inbox draft ${item.id}` : `  sprid reviews draft ${item.id}`));
+  return lines.join("\n");
+}
+
+/** `c:12` or a bare `12` is a comment; `r:41` is a store review. */
+function parseRef(ref, usage) {
+  const m = String(ref ?? "").match(/^(?:(c|r):)?([1-9]\d*)$/i);
+  if (!m) throw new UsageError(usage);
+  return { kind: (m[1] ?? "c").toLowerCase() === "r" ? "review" : "comment", id: Number(m[2]) };
+}
+
+async function draft(ctx, ref) {
+  const { kind, id } = parseRef(ref, "sprid inbox draft <commentId>");
+  if (kind === "review") throw new UsageError(`Store reviews are drafted with: sprid reviews draft ${id}`);
+  const res = await callTool(ctx, "draft_comment_reply", { commentId: id, ...(ctx.flags.count ? { count: Number(ctx.flags.count) } : {}) });
+  if (ctx.json) {
+    ctx.out(res);
+    return 0;
+  }
+  const suggestions = res?.suggestions ?? [];
+  if (res?.shouldEscalate) ctx.print(C.warn("  This one should be answered by a person, not a template."));
+  if (res?.note) ctx.print(C.dim(`  ${res.note}`));
+  suggestions.forEach((s, i) => ctx.print(`  ${i + 1}. ${typeof s === "string" ? s : s.text ?? JSON.stringify(s)}`));
+  if (suggestions.length) ctx.print(C.dim(`\n  Send one: sprid inbox reply ${id} --text "…"`));
+  return 0;
+}
+
+async function reply(ctx, ref) {
+  const { kind, id } = parseRef(ref, "sprid inbox reply <commentId> --text \"…\" [--yes]");
+  if (kind === "review") throw new UsageError(`Store reviews are replied to with: sprid reviews reply ${id}`);
+  const text = typeof ctx.flags.text === "string" ? ctx.flags.text.trim() : "";
+  if (!text) throw new UsageError(`Pass the reply with --text. Suggestions: sprid inbox draft ${id}`);
+  if (text.length > 500) throw new UsageError(`${text.length} characters; a comment reply allows 500.`);
+  if (!ctx.flags.yes) {
+    const msg = "Replying is public. Re-run with --yes to send without the prompt.";
+    if (ctx.json || !ctx.stdin?.isTTY) {
+      if (ctx.json) ctx.out({ ok: false, error: msg, commentId: id, text });
+      else {
+        ctx.print(`  Will reply to comment ${id}:\n  ${text}`);
+        ctx.warn(`  ✗ ${msg}`);
+      }
+      return 2;
+    }
+    ctx.print(`  Will reply publicly to comment ${id}:\n\n  ${text}\n`);
+    if (!(await confirm(ctx, "  Send it? [y/N] "))) {
+      ctx.print("  Not sent.");
+      return 1;
+    }
+  }
+  const res = await callTool(ctx, "reply_comment", { commentId: id, text });
+  if (ctx.json) ctx.out(res);
+  else ctx.print(`  ${C.ok(OK)} Reply sent to comment ${id}.`);
+  return 0;
+}
+
+async function file(ctx, verb, ref) {
+  const { kind, id } = parseRef(ref, `sprid inbox ${verb} <c:id|r:id>`);
+  let res;
+  if (kind === "review") {
+    if (verb === "flag") throw new UsageError("Store reviews cannot be flagged; file them with done or put them back with reopen.");
+    res = await callTool(ctx, "dismiss_store_review", { reviewId: id, dismissed: verb === "done" });
+  } else {
+    res = await callTool(ctx, "update_comment", { commentId: id, state: verb === "reopen" ? "needs_you" : verb });
+  }
+  if (ctx.json) ctx.out(res);
+  else ctx.print(`  ${C.ok(OK)} ${kind === "review" ? "Review" : "Comment"} ${id} ${verb === "done" ? "filed" : verb === "flag" ? "flagged" : "back in Needs you"}.`);
+  return 0;
+}

package/src/commands/post.mjs

@@ -2,8 +2,10 @@
 import { fork } from "node:child_process";
 import { run as runPost } from "../post/cli.mjs";
 import { remotePost } from './studio.mjs';
+import { publishing, PUBLISHING_VERBS } from './publishing.mjs';
 
 export async function post(ctx) {
+  if (PUBLISHING_VERBS.includes(ctx.positionals[0])) return publishing(ctx);
   if (await remotePost(ctx)) return 0;
   return localPost(ctx);
 }