@sprid/cli 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 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
+  clipboard, saves it to Sprid and then empties the clipboard, so the key never
+  reaches the screen, shell history or a file. It covers every service whose
+  key is a copied string (RevenueCat, Stripe, PostHog, Polar, Paddle, Lemon
+  Squeezy, Plausible, Umami, Cloudflare); the ones whose credential is a
+  downloaded file keep `--key <file>`. macOS, Windows, and Linux through
+  `wl-paste`, `xclip` or `xsel`.
+
 ## 0.1.5 - 2026-09-24
 
 - `sprid connect ga4|plausible|umami` saves a website-analytics key beside 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.5",
+  "version": "0.1.7",
   "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",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@sprid/shots": "0.1.1",
-    "@sprid/release": "0.1.1"
+    "@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/clipboard.mjs

@@ -0,0 +1,75 @@
+// The clipboard as a key source. A key copied out of a provider's dashboard
+// goes straight from the clipboard into the request: it never reaches the
+// screen, a chat, shell history or a file on disk. Nothing here prints what it
+// read.
+
+import { spawnSync } from "node:child_process";
+import { UsageError } from "./args.mjs";
+
+// First reader that exists wins. Linux has no single clipboard tool, so try
+// Wayland, then the two X11 ones.
+const READERS = {
+  darwin: [["pbpaste", []]],
+  win32: [["powershell", ["-NoProfile", "-Command", "Get-Clipboard -Raw"]]],
+  linux: [
+    ["wl-paste", ["--no-newline"]],
+    ["xclip", ["-selection", "clipboard", "-o"]],
+    ["xsel", ["--clipboard", "--output"]],
+  ],
+};
+const CLEARERS = {
+  darwin: [["pbcopy", []]],
+  win32: [["powershell", ["-NoProfile", "-Command", "Set-Clipboard -Value $null"]]],
+  linux: [
+    ["wl-copy", ["--clear"]],
+    ["xclip", ["-selection", "clipboard", "-i"]],
+    ["xsel", ["--clipboard", "--clear"]],
+  ],
+};
+
+// A clearer's stdout is ignored, not piped: xclip forks a child that keeps
+// owning the selection, and a pipe it inherits would hold spawnSync open.
+function run(candidates, input) {
+  const clearing = input !== undefined;
+  for (const [cmd, args] of candidates ?? []) {
+    const r = spawnSync(cmd, args, { input: input ?? "", encoding: "utf8", stdio: ["pipe", clearing ? "ignore" : "pipe", "ignore"] });
+    if (r.error?.code === "ENOENT") continue;
+    if (r.status === 0) return { ok: true, out: r.stdout ?? "" };
+  }
+  return { ok: false, out: "" };
+}
+
+/**
+ * Check what the clipboard holds looks like a key, not what is usually there
+ * by mistake: nothing, or the command itself (copied out of a guide or a chat
+ * a moment before). Keys and tokens from every provider we read are one
+ * unbroken string, so any whitespace means it is not one.
+ */
+export function checkClipboardKey(raw, what = "the key") {
+  const text = String(raw ?? "").trim();
+  if (!text) throw new UsageError(`The clipboard is empty. Copy ${what}, then run this again.`);
+  if (/\s/.test(text)) {
+    throw new UsageError(
+      `The clipboard holds text with spaces, not a key (often this command itself). Copy ${what}, then run this again.`,
+    );
+  }
+  if (text.length < 8) throw new UsageError(`The clipboard holds something too short to be a key. Copy ${what}, then run this again.`);
+  return text;
+}
+
+export function readClipboardKey(what, platform = process.platform, exec = run) {
+  const r = exec(READERS[platform]);
+  if (!r.ok) {
+    throw new UsageError(
+      platform === "linux"
+        ? "Could not read the clipboard. Install wl-clipboard, xclip or xsel, or save the key to a file and pass --key <file>."
+        : "Could not read the clipboard. Save the key to a file and pass --key <file> instead.",
+    );
+  }
+  return checkClipboardKey(r.out, what);
+}
+
+/** Best effort: a key left on the clipboard is the next paste's accident. */
+export function clearClipboard(platform = process.platform, exec = run) {
+  return exec(CLEARERS[platform], "").ok;
+}

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

@@ -15,12 +15,32 @@ import { UsageError } from "../args.mjs";
 import { secretsPath } from "../creds.mjs";
 import { ApiError } from "../http.mjs";
 import { pendingGrant } from "../pending.mjs";
+import { clearClipboard, readClipboardKey } from "../clipboard.mjs";
 import { C, BAD, EXPIRING, NONE, OK, table, wrap } from "../format.mjs";
 import { connectionRows } from "./status.mjs";
 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",
@@ -84,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(", ")}.`,
   );
 }
 
@@ -214,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 });
 
@@ -243,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;
@@ -253,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 });
@@ -263,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) ──────────────────────────────────────────────────────────
@@ -283,13 +318,25 @@ export function fileOrValue(arg, cwd) {
   return String(arg);
 }
 
-/** Flags → the PATCH body for one service. Reads files; never echoes them. */
-export function sensorPatch(service, flags, cwd) {
+// Services whose credential is a downloaded file (a .p8, a service-account
+// JSON). There is nothing to copy, so the clipboard is not offered for them.
+const FILE_KEY_SERVICES = new Set(["asc", "play", "gsc", "ga4"]);
+
+/**
+ * Flags → the PATCH body for one service. Reads files; never echoes them.
+ * `pasted` is a key already read from the clipboard (`--key-from-clipboard`);
+ * it takes the place of the --key / --token file.
+ */
+export function sensorPatch(service, flags, cwd, pasted) {
   const need = (name) => {
     const v = flags[name];
-    if (!v || v === true) throw new UsageError(`sprid connect ${service} needs --${name}`);
+    if (!v || v === true) {
+      const hint = !FILE_KEY_SERVICES.has(service) && (name === "key" || name === "token") ? ` (or --key-from-clipboard)` : "";
+      throw new UsageError(`sprid connect ${service} needs --${name}${hint}`);
+    }
     return String(v);
   };
+  const secret = (name) => pasted ?? fileOrValue(need(name), cwd);
   switch (service) {
     case "asc":
       return {
@@ -307,7 +354,7 @@ export function sensorPatch(service, flags, cwd) {
         secrets: { gscServiceAccountJson: readKeyFile(need("key"), cwd) },
       };
     case "posthog": {
-      const body = { posthogProjectId: need("project"), secrets: { posthogApiKey: fileOrValue(need("key"), cwd) } };
+      const body = { posthogProjectId: need("project"), secrets: { posthogApiKey: secret("key") } };
       if (flags.host && flags.host !== true) {
         const host = String(flags.host);
         body.posthogHost = host === "eu" || host === "us" ? `https://${host}.posthog.com` : host;
@@ -331,7 +378,7 @@ export function sensorPatch(service, flags, cwd) {
     case "plausible": {
       const body = {
         plausibleSiteId: String(need("site")).replace(/^https?:\/\//, "").replace(/\/+$/, ""),
-        secrets: { plausibleApiKey: fileOrValue(need("key"), cwd) },
+        secrets: { plausibleApiKey: secret("key") },
       };
       if (flags.host && flags.host !== true) body.plausibleHost = String(flags.host).replace(/\/+$/, "");
       if (flags.use) body.trafficProvider = "plausible";
@@ -340,7 +387,7 @@ export function sensorPatch(service, flags, cwd) {
     case "umami": {
       const body = {
         umamiWebsiteId: String(need("site")),
-        secrets: { umamiApiKey: fileOrValue(need("key"), cwd) },
+        secrets: { umamiApiKey: secret("key") },
       };
       // A self-hosted Umami serves its API under /api. Leaving that off is the
       // commonest setup mistake, and it fails as a 404 on every read, so add
@@ -353,41 +400,65 @@ export function sensorPatch(service, flags, cwd) {
       return body;
     }
     case "revenuecat":
-      return { revenuecatProjectId: need("project"), secrets: { revenuecatApiKey: fileOrValue(need("key"), cwd) } };
+      return { revenuecatProjectId: need("project"), secrets: { revenuecatApiKey: secret("key") } };
     // Stripe and Paddle need no id: the key names the account. Polar takes an
     // optional organization id (an org token already implies one), Lemon
     // Squeezy needs its store id.
     case "stripe":
-      return { secrets: { stripeApiKey: fileOrValue(need("key"), cwd) } };
+      return { secrets: { stripeApiKey: secret("key") } };
     case "polar": {
-      const body = { secrets: { polarApiKey: fileOrValue(need("key"), cwd) } };
+      const body = { secrets: { polarApiKey: secret("key") } };
       if (flags.org && flags.org !== true) body.polarOrganizationId = String(flags.org);
       return body;
     }
     case "lemonsqueezy":
       return {
         lemonSqueezyStoreId: String(need("store")),
-        secrets: { lemonSqueezyApiKey: fileOrValue(need("key"), cwd) },
+        secrets: { lemonSqueezyApiKey: secret("key") },
       };
     case "paddle": {
-      const body = { secrets: { paddleApiKey: fileOrValue(need("key"), cwd) } };
+      const body = { secrets: { paddleApiKey: secret("key") } };
       if (flags.env && flags.env !== true) body.paddleEnvironment = String(flags.env) === "sandbox" ? "sandbox" : "live";
       return body;
     }
     case "cloudflare":
-      return { cloudflareZoneId: need("zone"), secrets: { cloudflareApiToken: fileOrValue(need("token"), cwd) } };
+      return { cloudflareZoneId: need("zone"), secrets: { cloudflareApiToken: secret("token") } };
     default:
       throw new UsageError(`Unknown key type "${service}"`);
   }
 }
 
+/**
+ * `--key-from-clipboard`: the key a provider just showed, read at run time.
+ * Refused with a file flag beside it (which one would win is a guess) and for
+ * services whose credential is a download.
+ */
+function pastedKey(ctx, service, label) {
+  if (!ctx.flags["key-from-clipboard"]) return undefined;
+  if (FILE_KEY_SERVICES.has(service)) {
+    throw new UsageError(`${label} uses a downloaded key file. Pass --key <path to the file> instead of --key-from-clipboard.`);
+  }
+  if ((ctx.flags.key && ctx.flags.key !== true) || (ctx.flags.token && ctx.flags.token !== true)) {
+    throw new UsageError("Pass either --key-from-clipboard or a key file, not both.");
+  }
+  return readClipboardKey(`the ${label} key`);
+}
+
+function clearPasted(ctx, pasted) {
+  if (pasted === undefined) return;
+  const cleared = clearClipboard();
+  if (!ctx.json) ctx.print(C.dim(cleared ? "  Clipboard cleared." : "  Could not clear the clipboard. Copy something else over the key."));
+}
+
 async function connectSensor(ctx, service) {
   if (ctx.flags.clear) return clearSensor(ctx, service);
-  const body = sensorPatch(service, ctx.flags, ctx.cwd);
+  const pasted = pastedKey(ctx, service, SENSOR_LABEL[service]);
+  const body = sensorPatch(service, ctx.flags, ctx.cwd, pasted);
   const wid = await ctx.workspaceId();
   const profile = await resolveProfile(ctx, wid);
   const updated = await patchProfile(ctx, wid, profile.id, body);
   report(ctx, updated, Object.keys(body.secrets), `${SENSOR_LABEL[service]} key`, wid, service);
+  clearPasted(ctx, pasted);
   return 0;
 }
 
@@ -432,9 +503,10 @@ function report(ctx, profile, keys, what, workspaceId, service) {
  */
 async function connectProvider(ctx, provider) {
   if (ctx.flags.clear) return clearProvider(ctx, provider);
+  const pasted = pastedKey(ctx, provider, provider);
   const raw = ctx.flags.key;
-  if (!raw || raw === true) throw new UsageError(`sprid connect ${provider} --key <file or key>`);
-  const apiKey = fileOrValue(raw, ctx.cwd);
+  if (pasted === undefined && (!raw || raw === true)) throw new UsageError(`sprid connect ${provider} --key <file or key> (or --key-from-clipboard)`);
+  const apiKey = pasted ?? fileOrValue(raw, ctx.cwd);
   if (apiKey.length < 8) throw new UsageError("That key is too short to be one.");
   const wid = await ctx.workspaceId();
   let created;
@@ -452,6 +524,7 @@ async function connectProvider(ctx, provider) {
     ctx.print(`  ${C.ok(OK)} ${provider} key set on the workspace${hint ? `  ${C.dim(hint)}` : ""}`);
     if (provider === "anthropic" || provider === "openai") ctx.print(C.dim("  Review replies and other drafting now run on your own key."));
   }
+  clearPasted(ctx, pasted);
   return 0;
 }
 
@@ -556,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>`);