@tiny-fish/cli 0.6.2-next.102 → 0.6.2-next.105

package/dist/commands/connect.d.ts

@@ -1,19 +1,23 @@
 import { Command } from "commander";
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
+export type AgentClient = "claude-code" | "codex" | "hermes" | "openclaw";
 export declare function connectClaudeCode(options: {
     mcpUrl: string;
     launch: boolean;
-}): void;
+}): Promise<void>;
 export declare function connectCodex(options: {
     mcpUrl: string;
     launch: boolean;
-}): void;
+}): Promise<void>;
 export declare function connectHermes(options: {
     mcpUrl: string;
     launch: boolean;
-}): void;
+}): Promise<void>;
 export declare function connectOpenClaw(options: {
+    mcpUrl: string;
     launch: boolean;
-}): void;
+    installCli?: boolean;
+}): Promise<void>;
+export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -1,8 +1,11 @@
+import { randomUUID } from "node:crypto";
 import spawn from "cross-spawn";
+import { CLI_VERSION } from "../lib/constants.js";
 import { errLine } from "../lib/output.js";
 const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const HERMES_SEED_TIMEOUT_MS = 120_000;
+const TELEMETRY_TIMEOUT_MS = 500;
 const MCP_LOGIN_UNAVAILABLE_MESSAGE = "This Claude Code installation does not expose `claude mcp login`, which is required for " +
     "one-command MCP authentication. Update Claude Code and retry, or authenticate TinyFish " +
     "manually from /mcp.";
@@ -41,6 +44,21 @@ const CLAUDE_CODE = {
     ],
     addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
 };
+function launchCodexWalkthrough() {
+    const deepLink = new URL("codex://new");
+    deepLink.searchParams.set("prompt", DEFAULT_ONBOARDING_PROMPT);
+    deepLink.searchParams.set("path", process.cwd());
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [deepLink.toString()]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", deepLink.toString()]]
+            : ["xdg-open", [deepLink.toString()]];
+    const result = spawn.sync(command, args, { stdio: "ignore" });
+    if (result.error || result.status !== 0) {
+        throw new Error("Could not open Codex", { cause: result.error });
+    }
+    errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
+}
 const CODEX = {
     command: "codex",
     connectClient: "codex",
@@ -50,6 +68,7 @@ const CODEX = {
         patterns: [/--oauth-resource(?:\s|<)/],
         unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
     },
+    launchWalkthrough: launchCodexWalkthrough,
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
     addArgs: (mcpUrl, oauthResource) => [
         "mcp",
@@ -108,6 +127,39 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
+function createConnectTelemetry(mcpUrl, client) {
+    const attemptId = randomUUID();
+    const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
+    let enabled = true;
+    return {
+        attemptId,
+        async track(stage, failedStage) {
+            if (!enabled)
+                return;
+            try {
+                const response = await fetch(endpoint, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        attempt_id: attemptId,
+                        client,
+                        stage,
+                        failed_stage: failedStage,
+                        runtime_platform: process.platform,
+                        node_version: process.version,
+                        cli_version: CLI_VERSION,
+                    }),
+                    signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS),
+                });
+                if (!response.ok)
+                    enabled = false;
+            }
+            catch {
+                enabled = false;
+            }
+        },
+    };
+}
 function requireCommandSupport(client) {
     const result = spawn.sync(client.command, client.supportCheck.args, {
         encoding: "utf8",
@@ -146,111 +198,167 @@ function removeExistingRegistration(client, removal) {
     }
     throw new Error(`Could not remove existing ${removal.label}: ${details}`);
 }
-function connectNativeMcpClient(client, options) {
-    requireCommandSupport(client);
-    for (const removal of client.removals)
-        removeExistingRegistration(client, removal);
-    const mcpUrl = new URL(options.mcpUrl);
-    mcpUrl.searchParams.set("source", "tinyfish_cli");
-    mcpUrl.searchParams.set("client", client.connectClient);
-    errLine(`Adding TinyFish to ${client.displayName}...`);
-    const addResult = spawn.sync(client.command, client.addArgs(mcpUrl.toString(), options.mcpUrl), {
-        stdio: "inherit",
-    });
-    if (addResult.error || addResult.status !== 0) {
-        throw new Error(`Could not add TinyFish to ${client.displayName}`, {
-            cause: addResult.error,
-        });
-    }
-    if (client.loginArgs) {
-        errLine("Signing in to TinyFish...");
-        const loginResult = spawn.sync(client.command, client.loginArgs, {
-            stdio: "inherit",
-        });
-        if (loginResult.error || loginResult.status !== 0) {
-            throw new Error(`Could not authenticate TinyFish in ${client.displayName}`, {
-                cause: loginResult.error,
-            });
-        }
-    }
-    if (!options.launch) {
-        errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
-        return;
-    }
+function launchNativeMcpClient(client) {
     errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
     if (client.launchWalkthrough) {
         client.launchWalkthrough();
-        return;
+        return true;
     }
     const result = spawn.sync(client.command, [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
     if (result.error) {
         throw new Error(`Could not launch ${client.displayName}`, { cause: result.error });
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
-        return;
+        return false;
     if (result.status !== 0) {
         throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
     }
+    return true;
 }
-export function connectClaudeCode(options) {
-    connectNativeMcpClient(CLAUDE_CODE, options);
-}
-export function connectCodex(options) {
-    connectNativeMcpClient(CODEX, options);
-}
-export function connectHermes(options) {
-    connectNativeMcpClient(HERMES, options);
-}
-export function connectOpenClaw(options) {
-    requireCommandSupport(OPENCLAW);
-    errLine("Installing the TinyFish CLI...");
-    const cliInstallResult = spawn.sync("npm", ["install", "--global", "@tiny-fish/cli@latest"], { stdio: "inherit" });
-    if (cliInstallResult.error || cliInstallResult.status !== 0) {
-        throw new Error("Could not install the TinyFish CLI", { cause: cliInstallResult.error });
+function launchOpenClawWalkthrough() {
+    errLine("Starting the TinyFish walkthrough in OpenClaw...");
+    const result = spawn.sync("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], {
+        stdio: "inherit",
+    });
+    if (result.error) {
+        throw new Error("Could not launch OpenClaw", { cause: result.error });
     }
-    errLine("Installing the TinyFish skill in OpenClaw...");
-    const skillInstallResult = spawn.sync("openclaw", [
-        "skills",
-        "install",
-        OPENCLAW_SKILL,
-        "--global",
-        "--force",
-        "--acknowledge-clawhub-risk",
-    ], { stdio: "inherit" });
-    if (skillInstallResult.error || skillInstallResult.status !== 0) {
-        throw new Error("Could not install the TinyFish skill in OpenClaw", {
-            cause: skillInstallResult.error,
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return false;
+    if (result.status !== 0) {
+        throw new Error(`OpenClaw walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+    return true;
+}
+async function connectNativeMcpClient(client, options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient);
+    let failureStage = "prerequisite_check";
+    try {
+        await telemetry.track("started");
+        requireCommandSupport(client);
+        failureStage = "registration_cleanup";
+        for (const removal of client.removals)
+            removeExistingRegistration(client, removal);
+        const mcpUrl = new URL(options.mcpUrl);
+        mcpUrl.searchParams.set("source", "tinyfish_cli");
+        mcpUrl.searchParams.set("client", client.connectClient);
+        mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
+        failureStage = client.loginArgs ? "registration" : "registration_or_authentication";
+        errLine(`Adding TinyFish to ${client.displayName}...`);
+        const addResult = spawn.sync(client.command, client.addArgs(mcpUrl.toString(), options.mcpUrl), {
+            stdio: "inherit",
         });
+        if (addResult.error || addResult.status !== 0) {
+            throw new Error(`Could not add TinyFish to ${client.displayName}`, {
+                cause: addResult.error,
+            });
+        }
+        if (client.loginArgs) {
+            failureStage = "authentication";
+            errLine("Signing in to TinyFish...");
+            const loginResult = spawn.sync(client.command, client.loginArgs, {
+                stdio: "inherit",
+            });
+            if (loginResult.error || loginResult.status !== 0) {
+                throw new Error(`Could not authenticate TinyFish in ${client.displayName}`, {
+                    cause: loginResult.error,
+                });
+            }
+        }
+        if (!options.launch) {
+            errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
+            await telemetry.track("completed");
+            return;
+        }
+        failureStage = "walkthrough_launch";
+        if (!launchNativeMcpClient(client))
+            return;
+        await telemetry.track("completed");
     }
-    const authStatus = spawn.sync("tinyfish", ["auth", "status"], { stdio: "ignore" });
-    if (commandNotFound(authStatus.error)) {
-        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
+    catch (error) {
+        await telemetry.track("failed", failureStage);
+        throw error;
     }
-    if (authStatus.status !== 0) {
-        errLine("Signing in to TinyFish...");
-        const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", "openclaw"], { stdio: "inherit" });
-        if (commandNotFound(loginResult.error)) {
-            throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
+}
+export async function connectClaudeCode(options) {
+    await connectNativeMcpClient(CLAUDE_CODE, options);
+}
+export async function connectCodex(options) {
+    await connectNativeMcpClient(CODEX, options);
+}
+export async function connectHermes(options) {
+    await connectNativeMcpClient(HERMES, options);
+}
+export async function connectOpenClaw(options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw");
+    let failureStage = "prerequisite_check";
+    try {
+        await telemetry.track("started");
+        requireCommandSupport(OPENCLAW);
+        if (options.installCli !== false) {
+            failureStage = "cli_install";
+            errLine("Installing the TinyFish CLI...");
+            const cliInstallResult = spawn.sync("npm", ["install", "--global", "@tiny-fish/cli@latest"], {
+                stdio: "inherit",
+            });
+            if (cliInstallResult.error || cliInstallResult.status !== 0) {
+                throw new Error("Could not install the TinyFish CLI", { cause: cliInstallResult.error });
+            }
+        }
+        failureStage = "skill_install";
+        errLine("Installing the TinyFish skill in OpenClaw...");
+        const skillInstallResult = spawn.sync("openclaw", ["skills", "install", OPENCLAW_SKILL, "--global", "--force", "--acknowledge-clawhub-risk"], { stdio: "inherit" });
+        if (skillInstallResult.error || skillInstallResult.status !== 0) {
+            throw new Error("Could not install the TinyFish skill in OpenClaw", {
+                cause: skillInstallResult.error,
+            });
+        }
+        failureStage = "authentication";
+        const authStatus = spawn.sync("tinyfish", ["auth", "status"], { stdio: "ignore" });
+        if (commandNotFound(authStatus.error)) {
+            throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
         }
-        if (loginResult.error || loginResult.status !== 0) {
-            throw new Error("Could not authenticate TinyFish for OpenClaw", {
-                cause: loginResult.error,
+        if (authStatus.status !== 0) {
+            errLine("Signing in to TinyFish...");
+            const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", "openclaw"], {
+                stdio: "inherit",
             });
+            if (commandNotFound(loginResult.error)) {
+                throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
+            }
+            if (loginResult.error || loginResult.status !== 0) {
+                throw new Error("Could not authenticate TinyFish for OpenClaw", {
+                    cause: loginResult.error,
+                });
+            }
+        }
+        if (!options.launch) {
+            errLine("TinyFish is connected. Open OpenClaw to start using it.");
+            await telemetry.track("completed");
+            return;
         }
+        failureStage = "walkthrough_launch";
+        if (!launchOpenClawWalkthrough())
+            return;
+        await telemetry.track("completed");
     }
-    if (!options.launch) {
-        errLine("TinyFish is connected. Open OpenClaw to start using it.");
-        return;
+    catch (error) {
+        await telemetry.track("failed", failureStage);
+        throw error;
     }
-    errLine("Starting the TinyFish walkthrough in OpenClaw...");
-    const launchResult = spawn.sync("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], { stdio: "inherit" });
-    if (launchResult.error) {
-        throw new Error("Could not launch OpenClaw", { cause: launchResult.error });
+}
+export function launchAgent(client) {
+    if (client === "claude-code") {
+        launchNativeMcpClient(CLAUDE_CODE);
     }
-    if (launchResult.signal === "SIGINT" || launchResult.signal === "SIGTERM")
-        return;
-    if (launchResult.status !== 0) {
-        throw new Error(`OpenClaw walkthrough exited with status ${launchResult.status ?? "unknown"}`);
+    else if (client === "codex") {
+        launchNativeMcpClient(CODEX);
+    }
+    else if (client === "hermes") {
+        launchNativeMcpClient(HERMES);
+    }
+    else {
+        launchOpenClawWalkthrough();
     }
 }
 export function registerConnect(program) {
@@ -260,7 +368,7 @@ export function registerConnect(program) {
         .argument("<client>", "Agent client to connect (claude-code, codex, hermes, or openclaw)")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
-        .action((client, options) => {
+        .action(async (client, options) => {
         const mcpUrl = options.url ?? DEFAULT_MCP_URL;
         if (mcpUrl.startsWith("-")) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
@@ -277,16 +385,16 @@ export function registerConnect(program) {
         }
         const connectOptions = { mcpUrl, launch: options.launch ?? false };
         if (client === "claude-code") {
-            connectClaudeCode(connectOptions);
+            await connectClaudeCode(connectOptions);
         }
         else if (client === "codex") {
-            connectCodex(connectOptions);
+            await connectCodex(connectOptions);
         }
         else if (client === "hermes") {
-            connectHermes(connectOptions);
+            await connectHermes(connectOptions);
         }
         else if (client === "openclaw") {
-            connectOpenClaw({ launch: connectOptions.launch });
+            await connectOpenClaw(connectOptions);
         }
         else {
             throw new Error(`Unsupported client: ${client}. Supported clients: claude-code, codex, hermes, openclaw`);

package/dist/commands/onboard.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerOnboard(program: Command): void;

package/dist/commands/onboard.js

@@ -0,0 +1,230 @@
+import * as readline from "readline/promises";
+import { getApiKey, saveConfig } from "../lib/auth.js";
+import { fetchContentGet, searchQuery } from "../lib/client.js";
+import { BASE_URL } from "../lib/constants.js";
+import { errLine, handleApiError, outLine } from "../lib/output.js";
+import { connectClaudeCode, connectCodex, connectHermes, connectOpenClaw, launchAgent, } from "./connect.js";
+const EXAMPLE_QUERIES = [
+    "What are recent changes in the AI dev stack? Give me the top 5 changes that matter, why they matter, and any action needed.",
+    "Find a new-grad software engineering role posted in the last 24 hours and fetch the job description.",
+    "Analyse today's market and recommend the best investments for $5,000 with expected returns and risks.",
+];
+const AGENTS = [
+    { id: "claude-code", label: "Claude Code", connect: connectClaudeCode },
+    { id: "codex", label: "Codex", connect: connectCodex },
+    { id: "hermes", label: "Hermes", connect: connectHermes },
+    { id: "openclaw", label: "OpenClaw", connect: connectOpenClaw },
+];
+function cleanFetchedContent(text) {
+    const cleaned = text
+        .replace(/!\[[^\]]*\]\([^)]+\)/g, "")
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (cleaned.length <= 1_200)
+        return cleaned;
+    const shortened = cleaned.slice(0, 1_200);
+    return `${shortened.slice(0, shortened.lastIndexOf(" "))}…`;
+}
+function isUsefulFetchedContent(text) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return (normalized.length >= 120 &&
+        normalized.split(" ").length >= 20 &&
+        !/about press copyright contact us creators|there was an error while loading/i.test(normalized));
+}
+function parseAgents(value) {
+    if (!value.trim())
+        return [];
+    const selections = value.split(",").map((item) => item.trim());
+    return selections.map((selection) => {
+        const agent = AGENTS[Number(selection) - 1];
+        if (!agent)
+            throw new Error(`Unknown agent: ${selection}`);
+        return agent.id;
+    });
+}
+async function ask(question) {
+    const prompt = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await prompt.question(question)).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+function sdkSnippet(language, query) {
+    if (language === "python") {
+        return `from tinyfish import TinyFish
+
+client = TinyFish()
+
+# TinyFish Search: discover the right live source
+search = client.search.query(${JSON.stringify(query)})
+top_url = search.results[0].url
+
+# TinyFish Fetch: retrieve clean content from that source
+page = client.fetch.get_contents([top_url], format="markdown")
+print(page.results[0].text)`;
+    }
+    return `import { TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+// TinyFish Search: discover the right live source
+const search = await client.search.query({ query: ${JSON.stringify(query)} });
+const topUrl = search.results[0].url;
+
+// TinyFish Fetch: retrieve clean content from that source
+const page = await client.fetch.getContents({ urls: [topUrl], format: "markdown" });
+console.log(page.results[0]?.text);`;
+}
+async function connectAgent(id) {
+    const agent = AGENTS.find((candidate) => candidate.id === id);
+    if (!agent)
+        return;
+    const mcpUrl = new URL("/mcp", BASE_URL).toString();
+    if (id === "openclaw") {
+        await connectOpenClaw({ mcpUrl, launch: false, installCli: false });
+    }
+    else {
+        await agent.connect({ mcpUrl, launch: false });
+    }
+}
+function parseSelectedAgent(value, selected) {
+    if (!value.trim())
+        return undefined;
+    const agent = selected[Number(value) - 1];
+    if (!agent)
+        throw new Error("Choose one of the agents you connected.");
+    return agent;
+}
+async function chooseQuery(query, interactive) {
+    if (query)
+        return query;
+    if (!interactive)
+        throw new Error("Pass a query, or run `tinyfish onboard` in a terminal.");
+    outLine("\nChoose a live-web job, or type your own:");
+    EXAMPLE_QUERIES.forEach((example, index) => outLine(`   ${index + 1}. ${example}`));
+    const answer = await ask("Job [1]: ");
+    return EXAMPLE_QUERIES[Number(answer || "1") - 1] ?? answer;
+}
+async function runSearchStep(query, apiKey, persistEnvKey) {
+    outLine(`\n1. Searching the live web for: ${query}`);
+    const search = await searchQuery({ query }, apiKey);
+    if (persistEnvKey) {
+        saveConfig(apiKey);
+        outLine("✓ API key saved to ~/.tinyfish/config.json");
+    }
+    if (!search.results.length) {
+        throw new Error("Search returned no results. Try a more specific query.");
+    }
+    outLine("\nSearch results");
+    for (const result of search.results.slice(0, 3)) {
+        outLine(`   ${result.position}. ${result.title}\n` +
+            `      ${result.site_name}${result.date ? ` · ${result.date}` : ""}\n` +
+            `      ${result.snippet}\n` +
+            `      ${result.url}`);
+    }
+    return search.results;
+}
+async function runFetchStep(results, apiKey) {
+    const candidates = results.slice(0, 5);
+    let failedFetches = 0;
+    let lastFetchError;
+    for (const candidate of candidates) {
+        try {
+            const fetched = await fetchContentGet({ urls: [candidate.url], format: "markdown" }, apiKey);
+            const page = fetched.results[0];
+            if (page && typeof page.text === "string" && isUsefulFetchedContent(page.text)) {
+                return { source: candidate, text: cleanFetchedContent(page.text) };
+            }
+        }
+        catch (error) {
+            failedFetches += 1;
+            lastFetchError = error;
+        }
+    }
+    if (failedFetches === candidates.length)
+        throw lastFetchError;
+    throw new Error("Search found sources, but Fetch did not return useful page content.");
+}
+function renderFetchedResult({ source, text }) {
+    outLine(`\n2. Fetched source\n   ${source.title}\n   ${source.site_name} · ${source.url}`);
+    outLine(`\nWhy it matched\n${source.snippet}`);
+    outLine(`\nFetched content\n${text}`);
+    outLine("\n✓ Search found relevant sources; Fetch returned clean, usable content.");
+}
+function agentLabel(id) {
+    return AGENTS.find((agent) => agent.id === id)?.label ?? id;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function runAgentSteps(interactive) {
+    if (!interactive)
+        return;
+    outLine("\n3. Add TinyFish to your agents (choose any, or press Enter to skip):");
+    AGENTS.forEach((agent, index) => outLine(`   ${index + 1}. ${agent.label}`));
+    const selected = parseAgents(await ask("Agents [e.g. 1,2]: "));
+    const connected = [];
+    for (const id of selected) {
+        try {
+            await connectAgent(id);
+            connected.push(id);
+        }
+        catch (error) {
+            errLine(`   Could not connect ${agentLabel(id)}: ${errorMessage(error)}`);
+        }
+    }
+    if (!connected.length)
+        return;
+    outLine("\n4. Open an agent now:");
+    connected.forEach((id, index) => outLine(`   ${index + 1}. ${agentLabel(id)}`));
+    const launchId = parseSelectedAgent(await ask("Open [number or Enter to skip]: "), connected);
+    if (!launchId)
+        return;
+    try {
+        launchAgent(launchId);
+    }
+    catch (error) {
+        errLine(`   Could not open ${agentLabel(launchId)}: ${errorMessage(error)}`);
+    }
+}
+async function runSdkStep(interactive, query) {
+    if (!interactive)
+        return;
+    const choice = await ask("\nShow this as SDK code? [t] TypeScript, [p] Python, [Enter] skip: ");
+    if (!choice)
+        return;
+    const language = choice === "p" || choice === "python" ? "python" : "typescript";
+    outLine(`\n${sdkSnippet(language, query)}\n`);
+}
+export function registerOnboard(program) {
+    program
+        .command("onboard")
+        .description("Run a guided Search → Fetch demo, then add TinyFish to your agents or SDK")
+        .argument("[query]", "A real topic to research")
+        .addHelpText("after", "\nExamples:\n" +
+        '  tinyfish onboard "What changed in the AI dev stack this week?"\n' +
+        "\nAgents: claude-code, codex, hermes, openclaw.\n" +
+        "Run `tinyfish connect <client> --launch` later to add one directly.")
+        .action(async (query) => {
+        const apiKey = getApiKey();
+        const persistEnvKey = Boolean(process.env["TINYFISH_API_KEY"]);
+        delete process.env["TINYFISH_API_KEY"];
+        try {
+            const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+            const selectedQuery = await chooseQuery(query, interactive);
+            const searchResults = await runSearchStep(selectedQuery, apiKey, persistEnvKey);
+            renderFetchedResult(await runFetchStep(searchResults, apiKey));
+            await runAgentSteps(interactive);
+            await runSdkStep(interactive, selectedQuery);
+            outLine('Try another target with `tinyfish onboard "<query>"`, or run `tinyfish onboard --help`.');
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    });
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { registerRuns } from "./commands/runs.js";
 import { registerConfigureClaude } from "./commands/config-claude.js";
 import { registerSearch } from "./commands/search.js";
 import { registerConnect } from "./commands/connect.js";
+import { registerOnboard } from "./commands/onboard.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
 program
@@ -28,6 +29,7 @@ program
     }
 });
 registerAuth(program);
+registerOnboard(program);
 registerConnect(program);
 registerConfigureClaude(program);
 registerBrowser(program);

package/dist/lib/constants.js

@@ -2,7 +2,7 @@ import { createRequire } from "module";
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../../package.json");
 export const CLI_VERSION = _pkg.version;
-/** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted (must be https). */
+/** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted. */
 const apiUrlOverride = process.env["TINYFISH_API_URL"]?.trim();
 if (apiUrlOverride) {
     let parsed;
@@ -13,7 +13,8 @@ if (apiUrlOverride) {
         process.stderr.write("Error: TINYFISH_API_URL must be a valid https URL\n");
         process.exit(1);
     }
-    if (parsed.protocol !== "https:") {
+    const loopbackHttp = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+    if (parsed.protocol !== "https:" && !loopbackHttp) {
         process.stderr.write(`Error: TINYFISH_API_URL must use https:// (got protocol "${parsed.protocol || "unknown"}")\n`);
         process.exit(1);
     }

package/dist/lib/output.js

@@ -1,3 +1,4 @@
+import { stripVTControlCharacters } from "node:util";
 export class ApiError extends Error {
     status;
     code;
@@ -11,21 +12,29 @@ export class ApiError extends Error {
 export function out(data) {
     process.stdout.write(JSON.stringify(data) + "\n");
 }
+function safe(text) {
+    // eslint-disable-next-line no-control-regex
+    return stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
 export function outLine(line) {
-    process.stdout.write(line + "\n");
+    process.stdout.write(safe(line) + "\n");
 }
 export function errLine(line) {
-    process.stderr.write(line + "\n");
+    process.stderr.write(safe(line) + "\n");
 }
 export function err(data) {
     const payload = typeof data === "string" ? { error: data } : data;
-    process.stderr.write(JSON.stringify(payload) + "\n");
+    const serialized = JSON.stringify(payload) ?? "undefined";
+    process.stderr.write(safe(serialized) + "\n");
 }
 export function handleApiError(e) {
     if (e instanceof ApiError) {
         const payload = { error: e.message, status: e.status };
         if (e.code)
             payload.code = e.code;
+        if (e.status === 401)
+            payload.hint =
+                "Clear the TINYFISH_API_KEY environment variable, run `tinyfish auth login`, then try again.";
         err(payload);
     }
     else if (e instanceof Error) {

package/package.json

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