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

package/dist/commands/connect.d.ts

@@ -1,6 +1,7 @@
 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;
@@ -16,5 +17,7 @@ export declare function connectHermes(options: {
 export declare function connectOpenClaw(options: {
     mcpUrl: string;
     launch: boolean;
+    installCli?: boolean;
 }): Promise<void>;
+export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -44,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",
@@ -53,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",
@@ -182,6 +198,38 @@ function removeExistingRegistration(client, removal) {
     }
     throw new Error(`Could not remove existing ${removal.label}: ${details}`);
 }
+function launchNativeMcpClient(client) {
+    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
+    if (client.launchWalkthrough) {
+        client.launchWalkthrough();
+        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 false;
+    if (result.status !== 0) {
+        throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+    return true;
+}
+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 });
+    }
+    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";
@@ -223,21 +271,8 @@ async function connectNativeMcpClient(client, options) {
             return;
         }
         failureStage = "walkthrough_launch";
-        errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
-        if (client.launchWalkthrough) {
-            client.launchWalkthrough();
-            await telemetry.track("completed");
+        if (!launchNativeMcpClient(client))
             return;
-        }
-        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;
-        if (result.status !== 0) {
-            throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
-        }
         await telemetry.track("completed");
     }
     catch (error) {
@@ -260,13 +295,15 @@ export async function connectOpenClaw(options) {
     try {
         await telemetry.track("started");
         requireCommandSupport(OPENCLAW);
-        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 });
+        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...");
@@ -301,18 +338,8 @@ export async function connectOpenClaw(options) {
             return;
         }
         failureStage = "walkthrough_launch";
-        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 });
-        }
-        if (launchResult.signal === "SIGINT" || launchResult.signal === "SIGTERM")
+        if (!launchOpenClawWalkthrough())
             return;
-        if (launchResult.status !== 0) {
-            throw new Error(`OpenClaw walkthrough exited with status ${launchResult.status ?? "unknown"}`);
-        }
         await telemetry.track("completed");
     }
     catch (error) {
@@ -320,6 +347,20 @@ export async function connectOpenClaw(options) {
         throw error;
     }
 }
+export function launchAgent(client) {
+    if (client === "claude-code") {
+        launchNativeMcpClient(CLAUDE_CODE);
+    }
+    else if (client === "codex") {
+        launchNativeMcpClient(CODEX);
+    }
+    else if (client === "hermes") {
+        launchNativeMcpClient(HERMES);
+    }
+    else {
+        launchOpenClawWalkthrough();
+    }
+}
 export function registerConnect(program) {
     program
         .command("connect")

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.104",
+  "version": "0.6.2-next.105",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {