@tiny-fish/cli 0.12.1-next.138 → 0.12.1-next.139

package/dist/commands/connect.js

@@ -3,9 +3,12 @@ import * as path from "node:path";
 import spawn from "cross-spawn";
 import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
-import { cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
+import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
+import { runConnectAll } from "../lib/connect-all.js";
+import { detectHumanInitiated } from "../lib/harness.js";
 import { errLine } from "../lib/output.js";
 import { telemetryDisabled, telemetryHeaders } from "../lib/setup-telemetry.js";
+import { verifyMcpAuth } from "../lib/verify.js";
 import { recordInstalledVersion } from "../lib/version-marker.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
@@ -94,7 +97,7 @@ function installSignalGuard(state, telemetry) {
 async function runGuarded(state, telemetry, body) {
     const uninstallSignalGuard = installSignalGuard(state, telemetry);
     try {
-        body();
+        await body();
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError) {
@@ -125,6 +128,7 @@ const CLAUDE_CODE = {
         patterns: [/^\s*login(?:\s|\[)/m],
         unavailableMessage: MCP_LOGIN_UNAVAILABLE_MESSAGE,
     },
+    headerAuthSupported: true,
     loginArgs: ["mcp", "login", "tinyfish"],
     // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
     removals: [
@@ -538,9 +542,17 @@ async function connectNativeMcpClient(client, options) {
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", client.connectClient);
         mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
+        // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
+        const storedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
+        const useKeyAuth = client.headerAuthSupported === true && !!storedKey && validateKeyFormat(storedKey);
         state.stage = client.loginArgs ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
-        const addResult = spawn.sync(client.command, client.addArgs(mcpUrl.toString(), options.mcpUrl), {
+        const addResult = spawn.sync(client.command, [
+            ...client.addArgs(mcpUrl.toString(), options.mcpUrl),
+            // Key rides argv — readable via /proc/<pid>/cmdline. Accepted because these CLIs
+            // take headers no other way.
+            ...(useKeyAuth ? ["--header", `X-API-Key: ${storedKey}`] : []),
+        ], {
             stdio: "inherit",
         });
         if (addResult.error || addResult.status !== 0) {
@@ -550,7 +562,10 @@ async function connectNativeMcpClient(client, options) {
             });
         }
         telemetry.track("checkpoint", { phase: "registered" });
-        if (client.loginArgs) {
+        if (useKeyAuth) {
+            errLine("Using your stored TinyFish API key — no browser sign-in needed.");
+        }
+        if (client.loginArgs && !useKeyAuth) {
             state.stage = "client_oauth";
             errLine("Signing in to TinyFish...");
             const loginResult = spawn.sync(client.command, client.loginArgs, {
@@ -607,15 +622,7 @@ export async function connectOpenClaw(options) {
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         if (options.installCli !== false) {
             state.stage = "cli_install";
-            errLine("Installing the TinyFish CLI...");
-            const cliInstallResult = spawn.sync("npm", ["install", "--global", "@tiny-fish/cli@latest"], {
-                stdio: "inherit",
-                timeout: SKILL_INSTALL_TIMEOUT_MS,
-            });
-            if (cliInstallResult.error || cliInstallResult.status !== 0) {
-                throwIfInterrupted(cliInstallResult);
-                throw new Error("Could not install the TinyFish CLI", { cause: cliInstallResult.error });
-            }
+            installTinyFishCli();
             telemetry.track("checkpoint", { phase: "cli_installed" });
         }
         state.stage = "skill_install";
@@ -672,16 +679,21 @@ export async function connectOpenClaw(options) {
 export async function connectCursor(options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
     const state = { stage: "prerequisite_check", settled: false };
-    await runGuarded(state, telemetry, () => {
+    await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
+        // Auth first: a key lets the config carry an X-API-Key header, removing the sign-in hand-back.
+        state.stage = "authentication";
+        ensureCliAuthenticated("cursor", options.apiKey);
+        telemetry.track("checkpoint", { phase: "authenticated" });
+        const resolvedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
         state.stage = "registration";
         errLine("Adding TinyFish to Cursor...");
         const mcpUrl = new URL(options.mcpUrl);
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", "cursor");
         // Attempt id rides telemetry only; persisting it would break idempotency.
-        const result = writeCursorMcpConfig(mcpUrl.toString());
+        const result = writeCursorMcpConfig(mcpUrl.toString(), resolvedKey);
         if (result.status === "corrupt_skip") {
             throw new Error(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
                 `Fix the file, then re-run: tinyfish connect cursor`);
@@ -689,19 +701,43 @@ export async function connectCursor(options) {
         if (result.backupPath) {
             errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);
         }
+        if (result.repaired) {
+            errLine("Repaired the existing TinyFish entry (updated auth/config to current).");
+        }
         telemetry.track("checkpoint", { phase: "registered" });
-        state.stage = "authentication";
-        ensureCliAuthenticated("cursor", options.apiKey);
-        telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("cursor", telemetry.attemptId);
         recordInstalledVersion();
-        // A server written into mcp.json lands unauthenticated: only Cursor's own "Add to
-        // Cursor" deep link auto-starts OAuth, so name the click or the install never completes.
-        errLine("Added to Cursor. Restart Cursor (or reload the window), then open");
-        errLine('Settings -> Tools & MCP and click Connect on "tinyfish" to sign in.');
+        if (resolvedKey) {
+            // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
+            const verify = await verifyMcpAuth(resolvedKey);
+            if (verify.ok) {
+                errLine("TinyFish is connected and verified (health+auth). Reload the Cursor window (or restart cursor-agent) and it's live.");
+            }
+            else {
+                errLine(`TinyFish is configured, but the authenticated check failed (${verify.reason ?? "unknown"}). ` +
+                    "Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish connect cursor");
+            }
+        }
+        else if (detectHumanInitiated() && launchCursorDeeplink(mcpUrl.toString())) {
+            errLine("Cursor should pop a TinyFish install confirmation — approve it, then sign in when prompted.");
+        }
+        else {
+            errLine("TinyFish is connected. Reload the Cursor window, then approve/sign in under Settings → MCP.");
+        }
         settle(state, telemetry, "completed");
     });
 }
+/** Best-effort: false when no handler/open fails — caller falls back to reload copy. */
+function launchCursorDeeplink(mcpUrl) {
+    const deepLink = cursorInstallDeeplink(mcpUrl);
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [deepLink]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", deepLink]]
+            : ["xdg-open", [deepLink]];
+    const result = spawn.sync(command, args, { stdio: "ignore" });
+    return !result.error && result.status === 0;
+}
 export function launchAgent(client) {
     if (client === "claude-code") {
         launchNativeMcpClient(CLAUDE_CODE);
@@ -728,7 +764,11 @@ export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("<client>", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
+        .argument("[client]", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
+        .option("--all", "Detect and connect every supported harness found on this machine")
+        .option("--dry-run", "Print planned writes per harness without touching anything (--all only)")
+        .option("--uninstall", "Remove TinyFish entries written by connect --all")
+        .option("--skip-launch", "Skip the end-of-install agent launch (--all only)")
         .option("--api-key <apiKey>", "TinyFish API key to persist for the installed skill")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
@@ -750,6 +790,31 @@ export function registerConnect(program) {
         if (!["http:", "https:"].includes(parsedUrl.protocol)) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
+        if (options.all) {
+            if (client) {
+                throw new Error("Pass either a client or --all, not both.");
+            }
+            if (options.launch) {
+                throw new Error("--launch is not supported with --all. Connect a single client to launch it.");
+            }
+            const exitCode = await runConnectAll({
+                apiKey: options.apiKey,
+                mcpUrl,
+                dryRun: options.dryRun ?? false,
+                uninstall: options.uninstall ?? false,
+                noLaunch: options.skipLaunch === true,
+            });
+            // Preserve the 130 runGuarded set on Ctrl+C.
+            if (!process.exitCode)
+                process.exitCode = exitCode;
+            return;
+        }
+        if (options.dryRun || options.uninstall) {
+            throw new Error("--dry-run and --uninstall are only supported with --all.");
+        }
+        if (!client) {
+            throw new Error("Pass a client (claude-code, codex, cursor, hermes, openclaw) or --all.");
+        }
         const connectOptions = { apiKey: options.apiKey, mcpUrl, launch: options.launch ?? false };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);

package/dist/lib/connect-all.d.ts

@@ -0,0 +1,9 @@
+export interface ConnectAllOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    dryRun: boolean;
+    uninstall: boolean;
+    /** Skip the end-of-install agent launch (finale still prints the ask). */
+    noLaunch?: boolean;
+}
+export declare function runConnectAll(opts: ConnectAllOptions): Promise<number>;

package/dist/lib/connect-all.js

@@ -0,0 +1,345 @@
+import * as readline from "node:readline/promises";
+import spawn from "cross-spawn";
+import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, } from "../commands/connect.js";
+import { loadConfig, validateKeyFormat } from "./auth.js";
+import { detectInstalledHarnesses, FIVE_HARNESSES, } from "./harness-detect.js";
+import { detectHumanInitiated } from "./harness.js";
+import { removeCursorMcpServer, planCursorWrite } from "./cursor-config.js";
+import { errLine, outLine } from "./output.js";
+import { sendSetupCompleted } from "./setup-telemetry.js";
+import { verifyMcpAuth, verifyMcpHealth } from "./verify.js";
+import { printUpdateNoticeIfDrifted, recordInstalledVersion } from "./version-marker.js";
+const DISPLAY_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    hermes: "Hermes",
+    openclaw: "OpenClaw",
+};
+// `codex mcp add` succeeds unauthenticated; OAuth lands at first tool use.
+const AUTH_DEFERRED_AT_INSTALL = new Set(["codex"]);
+// Harnesses that drive their own OAuth at install — a stored TinyFish key says nothing
+// about their session, so it must never unlock a headless run for them.
+const HARNESS_OWN_AUTH = new Set(["claude-code", "codex", "hermes"]);
+const AUTH_CHECK_CAPABLE = new Set(["cursor", "openclaw"]);
+// Real removal commands — harness id is not the binary name.
+const UNINSTALL_POINTERS = {
+    "claude-code": "claude mcp remove tinyfish --scope user",
+    codex: "codex mcp remove tinyfish",
+    hermes: "hermes mcp remove tinyfish",
+    openclaw: "openclaw skills uninstall @tinyfish/tinyfish --global",
+};
+function resolvedApiKey(explicitApiKey) {
+    if (explicitApiKey)
+        return explicitApiKey;
+    const envKey = process.env["TINYFISH_API_KEY"];
+    if (envKey)
+        return envKey;
+    try {
+        return loadConfig().api_key;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasStoredAuth(explicitApiKey) {
+    const key = resolvedApiKey(explicitApiKey);
+    return !!key && validateKeyFormat(key);
+}
+async function runHarnessConnect(harness, opts) {
+    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false };
+    if (harness === "claude-code")
+        return connectClaudeCode(base);
+    if (harness === "codex")
+        return connectCodex(base);
+    if (harness === "hermes")
+        return connectHermes(base);
+    if (harness === "openclaw")
+        return connectOpenClaw({ mcpUrl: opts.mcpUrl, launch: false });
+    return connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+}
+async function verifyHarness(harness, mcpUrl, apiKey) {
+    const health = await verifyMcpHealth(mcpUrl);
+    // claude-code is auth-checkable only in key mode (header-authed config).
+    const capable = AUTH_CHECK_CAPABLE.has(harness) || (harness === "claude-code" && !!apiKey);
+    if (!capable || !health.ok)
+        return health;
+    if (!apiKey)
+        return { depth: "health+auth", ok: false, reason: "no stored API key" };
+    return verifyMcpAuth(apiKey);
+}
+function planText(harness, mcpUrl, apiKey) {
+    if (harness === "cursor")
+        return planCursorWrite(mcpUrl, apiKey);
+    return `would run \`tinyfish connect ${harness}\` (harness-owned MCP write; no local file touched by the CLI)`;
+}
+function uninstallPlanText(harness) {
+    if (harness === "cursor") {
+        return "would remove the tinyfish entry from ~/.cursor/mcp.json";
+    }
+    return `would print the removal command \`${UNINSTALL_POINTERS[harness]}\` (config is harness-owned; the CLI removes nothing)`;
+}
+function uninstallHarness(harness, configPath) {
+    const detection = { harness, detected: true, configPath, installed: false };
+    if (harness !== "cursor") {
+        // Harness-owned config — removal happens via each tool's own CLI.
+        return { ...detection, outcome: "uninstall_pointer", fixCommand: UNINSTALL_POINTERS[harness] };
+    }
+    let result;
+    try {
+        result = removeCursorMcpServer();
+    }
+    catch (e) {
+        result = { status: "corrupt_skip", error: e instanceof Error ? e.message : String(e) };
+    }
+    if (result.status === "corrupt_skip") {
+        return {
+            ...detection,
+            outcome: "uninstalled",
+            errorMessage: `could not update Cursor's mcp.json (${result.error}) — nothing removed.`,
+            fixCommand: "Fix ~/.cursor/mcp.json by hand, then re-run: tinyfish connect --all --uninstall",
+        };
+    }
+    if (result.status === "unchanged") {
+        return { ...detection, outcome: "uninstall_noop" };
+    }
+    return { ...detection, outcome: "uninstalled" };
+}
+async function processHarness(detection, opts, prompt) {
+    const { harness, configPath } = detection;
+    if (!detection.detected) {
+        return { harness, detected: false, configPath, installed: false, outcome: "not_detected" };
+    }
+    const base = { harness, detected: true, configPath, installed: false };
+    // dryRun first: --dry-run --uninstall must plan, never reach removeCursorMcpServer().
+    if (opts.dryRun) {
+        const plan = opts.uninstall ? uninstallPlanText(harness) : planText(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+        return { ...base, outcome: "dry_run", fixCommand: plan };
+    }
+    if (opts.uninstall)
+        return uninstallHarness(harness, configPath);
+    const isTTY = detectHumanInitiated();
+    // claude-code leaves the own-OAuth set when a key is stored: `mcp add --header
+    // X-API-Key` replaces its login. codex/hermes have no header path, so they keep the skip.
+    const keyed = hasStoredAuth(opts.apiKey);
+    const ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
+    const alreadyAuthed = !ownAuthHarness && keyed;
+    if (!isTTY && !alreadyAuthed) {
+        return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+    }
+    if (isTTY && !alreadyAuthed && prompt) {
+        errLine(`step: waiting for browser sign-in to TinyFish for ${DISPLAY_NAMES[harness]}`);
+        try {
+            await prompt(`Press enter to open the browser and sign in to TinyFish for ${DISPLAY_NAMES[harness]}... `);
+        }
+        catch {
+            // Ctrl+D closed stdin — treat like the no-TTY skip.
+            return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+        }
+    }
+    // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
+    const interruptedBefore = process.exitCode === 130;
+    try {
+        await runHarnessConnect(harness, opts);
+    }
+    catch (e) {
+        return {
+            ...base,
+            outcome: "failed",
+            errorMessage: e instanceof Error ? e.message : String(e),
+            fixCommand: `tinyfish connect ${harness}`,
+        };
+    }
+    if (!interruptedBefore && process.exitCode === 130) {
+        return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
+    }
+    recordInstalledVersion();
+    const verify = await verifyHarness(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+    return {
+        ...base,
+        installed: true,
+        outcome: "installed",
+        verifyDepth: verify.depth,
+        verifyOk: verify.ok,
+        verifyReason: verify.reason,
+    };
+}
+function summaryLine(result, uninstall) {
+    const name = DISPLAY_NAMES[result.harness];
+    if (!result.detected) {
+        const next = uninstall
+            ? "nothing to remove"
+            : `Install ${name}, then run: tinyfish connect ${result.harness}`;
+        return `- ${name} — not detected (searched ${result.configPath}). ${next}`;
+    }
+    if (result.outcome === "not_reached") {
+        return `… ${name} — not reached, the run stopped early. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "dry_run") {
+        return `… ${name} — ${result.fixCommand}`;
+    }
+    if (result.outcome === "no_tty_auth_skip") {
+        return `… ${name} — skipped, no stored credentials and no terminal to sign in. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "uninstall_pointer") {
+        return `… ${name} — not removed automatically (config is owned by ${name}). Run: ${result.fixCommand}`;
+    }
+    if (result.outcome === "uninstall_noop") {
+        return `… ${name} — no tinyfish entry found, nothing removed`;
+    }
+    if (result.outcome === "uninstalled") {
+        return result.errorMessage
+            ? `✗ ${name} — ${result.errorMessage} Fix: ${result.fixCommand}`
+            : `✓ ${name} — removed`;
+    }
+    if (result.outcome === "interrupted") {
+        return `✗ ${name} — interrupted before finishing. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "failed") {
+        return `✗ ${name} — install failed: ${result.errorMessage}. Fix: ${result.fixCommand}`;
+    }
+    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness);
+    const verifyLabel = result.verifyDepth ? `verified: ${result.verifyDepth}` : "not verified";
+    if (authDeferred || result.verifyOk === false) {
+        const reason = authDeferred
+            ? "one step left: sign in when your agent first runs"
+            : `verify warning (${verifyLabel}): ${result.verifyReason ?? "unknown"}`;
+        return `⚠ ${name} — installed, ${reason}. Fix: run \`/tinyfish:doctor\` in ${name} once it's open.`;
+    }
+    return `✓ ${name} — installed, ${verifyLabel}`;
+}
+function computeExitCode(results) {
+    const detected = results.filter((r) => r.detected);
+    if (detected.length === 0)
+        return 1;
+    // Only real install attempts count toward the success/failure denominator.
+    const attempted = detected.filter((r) => r.outcome === "installed" || r.outcome === "failed" || r.outcome === "interrupted");
+    if (attempted.length === 0)
+        return 0;
+    return attempted.some((r) => r.outcome === "installed") ? 0 : 1;
+}
+export async function runConnectAll(opts) {
+    const isTTY = detectHumanInitiated();
+    const rl = isTTY
+        ? readline.createInterface({ input: process.stdin, output: process.stderr })
+        : undefined;
+    let prompt;
+    if (rl) {
+        // Without a close-linked signal, question() never settles on Ctrl+D.
+        const closed = new AbortController();
+        rl.on("close", () => closed.abort());
+        prompt = (question) => rl.question(question, { signal: closed.signal });
+    }
+    const detections = detectInstalledHarnesses();
+    const results = [];
+    try {
+        for (const [index, detection] of detections.entries()) {
+            const { harness } = detection;
+            errLine(`step ${index + 1} of ${detections.length} — ${DISPLAY_NAMES[harness]}`);
+            let result;
+            try {
+                result = await processHarness(detection, opts, prompt);
+            }
+            catch (e) {
+                // Isolation: one harness throwing never stops the others.
+                result = {
+                    harness,
+                    detected: detection.detected,
+                    configPath: detection.configPath,
+                    installed: false,
+                    outcome: "failed",
+                    errorMessage: e instanceof Error ? e.message : String(e),
+                    fixCommand: `tinyfish connect ${harness}`,
+                };
+            }
+            results.push(result);
+            // Ctrl+C means stop, not continue to the next harness.
+            if (result.outcome === "interrupted")
+                break;
+        }
+    }
+    finally {
+        rl?.close();
+    }
+    // The interrupt break truncates `results`; pad so the 5-entry telemetry schema still parses.
+    for (const detection of detections) {
+        if (results.some((r) => r.harness === detection.harness))
+            continue;
+        results.push({
+            ...detection,
+            installed: false,
+            outcome: detection.detected ? "not_reached" : "not_detected",
+            fixCommand: `tinyfish connect ${detection.harness}`,
+        });
+    }
+    outLine("");
+    outLine("TinyFish setup summary:");
+    for (const result of results)
+        outLine(summaryLine(result, opts.uninstall));
+    if (results.every((r) => !r.detected)) {
+        outLine("");
+        outLine("No supported harness found. Install one of: " + FIVE_HARNESSES.join(", "));
+        if (!opts.uninstall)
+            outLine("Then run: npx @tiny-fish/cli connect --all");
+        return 1;
+    }
+    if (!opts.dryRun && !opts.uninstall) {
+        const harnessTelemetry = results.map((r) => ({
+            harness: r.harness,
+            detected: r.detected,
+            installed: r.installed,
+            verify_depth: r.verifyDepth ?? null,
+            verify_ok: r.verifyOk ?? null,
+        }));
+        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
+        await printUpdateNoticeIfDrifted();
+    }
+    const exitCode = computeExitCode(results);
+    const interrupted = results.some((r) => r.outcome === "interrupted");
+    if (exitCode === 0 && !interrupted && !opts.dryRun && !opts.uninstall && results.some((r) => r.installed)) {
+        outLine("");
+        if (isTTY && !opts.noLaunch && (await launchFirstTask(results))) {
+            return exitCode;
+        }
+        outLine('Now ask your agent: "use TinyFish to find today\'s top Hacker News story"');
+    }
+    return exitCode;
+}
+const FIRST_TASK_PROMPT = "My TinyFish setup just finished — verify it with a real run: use the TinyFish search tool to " +
+    "find today's top Hacker News story, then fetch that page with the TinyFish fetch tool and give " +
+    "me a two-line summary. Show which tools you call.";
+// Launchable seeded agents, best-first — cursor-agent shares ~/.cursor/mcp.json with the IDE.
+const LAUNCHERS = [
+    { harness: "cursor", command: "cursor-agent", args: [FIRST_TASK_PROMPT] },
+    { harness: "claude-code", command: "claude", args: [FIRST_TASK_PROMPT] },
+];
+async function launchFirstTask(results) {
+    const candidates = LAUNCHERS.filter((l) => results.some((r) => r.harness === l.harness && r.installed));
+    if (candidates.length === 0)
+        return false;
+    // Several installs: ask rather than pick a favorite; plain enter skips.
+    let chosen = candidates[0];
+    if (candidates.length > 1) {
+        const menu = candidates.map((l, i) => `[${i + 1}] ${DISPLAY_NAMES[l.harness]}`).join("  ");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        let answer;
+        try {
+            answer = await rl.question(`Try your first TinyFish task now? ${menu}  [enter] skip: `);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rl.close();
+        }
+        const pick = Number.parseInt(answer.trim(), 10);
+        if (!pick || pick < 1 || pick > candidates.length)
+            return false;
+        chosen = candidates[pick - 1];
+    }
+    if (!chosen)
+        return false;
+    outLine(`Starting ${DISPLAY_NAMES[chosen.harness]} with your first TinyFish task...`);
+    const result = spawn.sync(chosen.command, chosen.args, { stdio: "inherit" });
+    return !result.error;
+}

package/dist/lib/cursor-config.d.ts

@@ -4,10 +4,14 @@ export interface CursorMcpWriteResult {
     status: "written" | "unchanged" | "corrupt_skip";
     backupPath?: string;
     error?: string;
+    /** A pre-existing tinyfish entry was replaced — a repair, not a fresh install. */
+    repaired?: boolean;
 }
 /** Dry-run description of the pending write; touches nothing. */
-export declare function planCursorWrite(mcpUrl: string): string;
+export declare function planCursorWrite(mcpUrl: string, apiKey?: string): string;
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
-export declare function writeCursorMcpConfig(mcpUrl: string): CursorMcpWriteResult;
+export declare function writeCursorMcpConfig(mcpUrl: string, apiKey?: string): CursorMcpWriteResult;
+/** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */
+export declare function cursorInstallDeeplink(mcpUrl: string): string;
 /** Removes only the `tinyfish` key. */
 export declare function removeCursorMcpServer(): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -12,8 +12,9 @@ export function cursorMcpPath() {
 function isPlainRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function buildTinyfishServerEntry(mcpUrl) {
-    return { url: mcpUrl };
+// Footgun: the key lands plaintext in mcp.json (0600) — per-device keys are the GA hardening.
+function buildTinyfishServerEntry(mcpUrl, apiKey) {
+    return apiKey ? { url: mcpUrl, headers: { "X-API-Key": apiKey } } : { url: mcpUrl };
 }
 function parseMcpJson(raw) {
     try {
@@ -46,20 +47,23 @@ function readExisting() {
     return { raw, parsed: parsed.value };
 }
 /** Dry-run description of the pending write; touches nothing. */
-export function planCursorWrite(mcpUrl) {
+export function planCursorWrite(mcpUrl, apiKey) {
     const existing = readExisting();
     const filePath = cursorMcpPath();
     if ("error" in existing) {
         return `${filePath}: existing file is corrupt (${existing.error}) — would skip and leave it untouched`;
     }
+    const authNote = apiKey
+        ? " with an API-key header — the key is stored in plaintext in that file (value not shown here)"
+        : "";
     const servers = existing.parsed.mcpServers;
     const current = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
-    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl))) {
+    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl, apiKey))) {
         return `${filePath}: already has the tinyfish MCP entry — no change`;
     }
     return existing.raw === undefined
-        ? `${filePath}: would create with a "tinyfish" MCP server entry`
-        : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry`;
+        ? `${filePath}: would create with a "tinyfish" MCP server entry${authNote}`
+        : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry${authNote}`;
 }
 // Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
 function commitServers(filePath, existing, servers) {
@@ -82,7 +86,7 @@ function commitServers(filePath, existing, servers) {
     return { status: "written", backupPath };
 }
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
-export function writeCursorMcpConfig(mcpUrl) {
+export function writeCursorMcpConfig(mcpUrl, apiKey) {
     const filePath = cursorMcpPath();
     const existing = readExisting();
     if ("error" in existing)
@@ -90,12 +94,18 @@ export function writeCursorMcpConfig(mcpUrl) {
     const servers = isPlainRecord(existing.parsed.mcpServers)
         ? { ...existing.parsed.mcpServers }
         : {};
-    const nextEntry = buildTinyfishServerEntry(mcpUrl);
+    const nextEntry = buildTinyfishServerEntry(mcpUrl, apiKey);
     if (JSON.stringify(servers[TINYFISH_SERVER_KEY]) === JSON.stringify(nextEntry)) {
         return { status: "unchanged" };
     }
+    const repaired = TINYFISH_SERVER_KEY in servers;
     servers[TINYFISH_SERVER_KEY] = nextEntry;
-    return commitServers(filePath, existing, servers);
+    return { ...commitServers(filePath, existing, servers), repaired };
+}
+/** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */
+export function cursorInstallDeeplink(mcpUrl) {
+    const config = Buffer.from(JSON.stringify(buildTinyfishServerEntry(mcpUrl))).toString("base64");
+    return `cursor://anysphere.cursor-deeplink/mcp/install?name=${TINYFISH_SERVER_KEY}&config=${encodeURIComponent(config)}`;
 }
 /** Removes only the `tinyfish` key. */
 export function removeCursorMcpServer() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.12.1-next.138",
+  "version": "0.12.1-next.139",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {