@tiny-fish/cli 0.1.0

package/dist/commands/auth.d.ts

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

package/dist/commands/auth.js

@@ -0,0 +1,180 @@
+import { spawn } from "child_process";
+import * as readline from "readline";
+import { DASHBOARD_URL, clearConfig, loadConfig, maskKey, saveConfig, validateKeyFormat, } from "../lib/auth.js";
+import { err, out, outLine } from "../lib/output.js";
+/**
+ * Read a key from stdin without echoing it to the terminal.
+ * Uses setRawMode on TTY so characters are never written to the screen.
+ * Falls back to plain readline when stdin is not a TTY (piped CI/CD input).
+ */
+async function readKeyHidden(prompt) {
+    process.stderr.write(prompt);
+    if (!process.stdin.isTTY) {
+        // Non-interactive (piped): read stdin line as-is — no echo suppression needed
+        const rl = readline.createInterface({ input: process.stdin, terminal: false });
+        return new Promise((resolve) => {
+            rl.once("line", (line) => {
+                rl.close();
+                resolve(line.trim());
+            });
+        });
+    }
+    // Interactive TTY: use raw mode so keystrokes are never echoed
+    return new Promise((resolve) => {
+        let input = "";
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onData = (char) => {
+            if (char === "\r" || char === "\n") {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+                process.stdin.removeListener("data", onData);
+                process.stderr.write("\n");
+                resolve(input);
+            }
+            else if (char === "\u0003") {
+                // Ctrl+C — restore terminal state before exiting
+                process.stdin.setRawMode(false);
+                process.exit(130);
+            }
+            else if (char === "\u007f" || char === "\b") {
+                // Backspace / Delete
+                input = input.slice(0, -1);
+            }
+            else {
+                input += char;
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
+/**
+ * Read key from piped stdin (CI/CD) or hidden TTY prompt (interactive).
+ * Never reads from a positional arg — avoids shell history / process list exposure.
+ */
+async function readKeyFromStdinOrPrompt() {
+    if (!process.stdin.isTTY) {
+        // Piped input: echo $KEY | tinyfish auth set
+        return new Promise((resolve) => {
+            let data = "";
+            process.stdin.setEncoding("utf8");
+            process.stdin.on("data", (chunk) => (data += chunk));
+            process.stdin.on("end", () => resolve(data.trim()));
+        });
+    }
+    return readKeyHidden("Paste your API key: ");
+}
+export function registerAuth(program) {
+    const auth = program.command("auth").description("Manage your TinyFish API key");
+    auth
+        .command("login")
+        .description("Open the API keys page and save your key interactively")
+        .action(async () => {
+        process.stderr.write(`Opening ${DASHBOARD_URL} in your browser...\n`);
+        try {
+            // Use spawn with an explicit args array — no shell, no interpolation
+            let cmd;
+            let args;
+            if (process.platform === "darwin") {
+                cmd = "open";
+                args = [DASHBOARD_URL];
+            }
+            else if (process.platform === "win32") {
+                // "start" treats the first quoted arg as a window title — empty string avoids it
+                cmd = "cmd";
+                args = ["/c", "start", "", DASHBOARD_URL];
+            }
+            else {
+                cmd = "xdg-open";
+                args = [DASHBOARD_URL];
+            }
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            child.unref();
+            child.on("error", () => { }); // headless — ignore
+        }
+        catch {
+            // headless — ignore
+        }
+        process.stderr.write(`If the browser didn't open, visit: ${DASHBOARD_URL}\n\n`);
+        const key = await readKeyHidden("Paste your API key: ");
+        if (!key) {
+            err("API key cannot be empty");
+            process.exit(1);
+        }
+        if (!validateKeyFormat(key)) {
+            err("Invalid key format. Expected sk-tinyfish-... or sk-mino-...");
+            process.exit(1);
+        }
+        saveConfig(key);
+        out({ status: "ok", message: "API key saved", key_preview: maskKey(key) });
+    });
+    auth
+        .command("set")
+        .description("Save an API key. Pass via stdin: echo $KEY | tinyfish auth set (safe for CI/CD)")
+        .action(async () => {
+        // Read from stdin pipe (CI/CD) or hidden TTY prompt (interactive)
+        const key = await readKeyFromStdinOrPrompt();
+        if (!key) {
+            err("API key cannot be empty");
+            process.exit(1);
+        }
+        if (!validateKeyFormat(key)) {
+            err("Invalid key format. Expected sk-tinyfish-... or sk-mino-...");
+            process.exit(1);
+        }
+        saveConfig(key);
+        out({ status: "ok", message: "API key saved", key_preview: maskKey(key) });
+    });
+    auth
+        .command("status")
+        .description("Show which API key is active and its source")
+        .option("--pretty", "Human-readable output")
+        .action((opts) => {
+        const envKey = process.env.TINYFISH_API_KEY;
+        if (envKey) {
+            const authenticated = validateKeyFormat(envKey);
+            const result = { source: "env", key_preview: maskKey(envKey), authenticated };
+            if (opts.pretty) {
+                outLine(`Source:  environment variable (TINYFISH_API_KEY)\nKey:     ${maskKey(envKey)}`);
+            }
+            else {
+                out(result);
+            }
+            return;
+        }
+        const config = loadConfig();
+        if (config.api_key) {
+            const authenticated = validateKeyFormat(config.api_key);
+            const result = {
+                source: "config",
+                key_preview: maskKey(config.api_key),
+                authenticated,
+            };
+            if (opts.pretty) {
+                outLine(`Source:  ~/.tinyfish/config.json\nKey:     ${maskKey(config.api_key)}`);
+            }
+            else {
+                out(result);
+            }
+            return;
+        }
+        const result = { source: "none", key_preview: null, authenticated: false };
+        if (opts.pretty) {
+            outLine("No API key configured. Run: tinyfish auth login");
+        }
+        else {
+            out(result);
+        }
+    });
+    auth
+        .command("logout")
+        .description("Remove stored API key")
+        .action(() => {
+        if (!clearConfig()) {
+            out({ status: "ok", message: "No API key stored" });
+            return;
+        }
+        out({ status: "ok", message: "API key removed" });
+    });
+}

package/dist/commands/run.d.ts

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

package/dist/commands/run.js

@@ -0,0 +1,153 @@
+import { getApiKey } from "../lib/auth.js";
+import { runAsync, runStream, runSync } from "../lib/client.js";
+import { err, handleApiError, out, outLine } from "../lib/output.js";
+import { RunStatus, StreamEventType } from "../lib/types.js";
+const RUN_TIMEOUT_MS = 20 * 60 * 1000; // 20 minutes
+function checkRunResult(result, expectComplete = true) {
+    if (result.error) {
+        err({ error: result.error, runId: result.runId, status: result.status });
+        process.exit(1);
+    }
+    if (expectComplete && result.status && result.status !== RunStatus.COMPLETED) {
+        err({ error: `Run ${result.status}`, runId: result.runId, status: result.status });
+        process.exit(1);
+    }
+}
+export function registerRun(program) {
+    program
+        .command("run <goal>")
+        .description("Run a browser automation")
+        .requiredOption("--url <url>", "Target URL for the automation")
+        .option("--sync", "Wait for result without streaming steps")
+        .option("--async", "Submit without waiting for result")
+        .option("--pretty", "Human-readable output")
+        .action(async (goal, opts) => {
+        if (opts.sync && opts.async) {
+            err({ error: "--sync and --async are mutually exclusive" });
+            process.exit(1);
+        }
+        // Reject obviously invalid input — accepts bare hostnames like "google.com"
+        try {
+            new URL(opts.url);
+        }
+        catch {
+            try {
+                new URL(`https://${opts.url}`);
+            }
+            catch {
+                err({ error: "--url does not look like a valid URL" });
+                process.exit(1);
+            }
+        }
+        const apiKey = getApiKey();
+        const req = { goal, url: opts.url };
+        if (opts.async) {
+            let result;
+            try {
+                result = await runAsync(req, apiKey);
+            }
+            catch (e) {
+                handleApiError(e);
+            }
+            checkRunResult(result, false); // async = PENDING is expected
+            if (opts.pretty) {
+                outLine(`Run submitted\nID:     ${result.runId}\nStatus: ${result.status}`);
+            }
+            else {
+                out(result);
+            }
+            return;
+        }
+        if (opts.sync) {
+            process.stderr.write("Waiting for result...\n");
+            let result;
+            try {
+                result = await runSync(req, apiKey, AbortSignal.timeout(RUN_TIMEOUT_MS));
+            }
+            catch (e) {
+                handleApiError(e);
+            }
+            checkRunResult(result);
+            if (opts.pretty) {
+                outLine(`Status: ${result.status}\n\n${JSON.stringify(result.resultJson ?? {}, null, 2)}`);
+            }
+            else {
+                out(result);
+            }
+            return;
+        }
+        // Default: SSE stream — 20 min timeout + Ctrl+C cancellation
+        const controller = new AbortController();
+        let siginted = false;
+        const timeout = setTimeout(() => controller.abort(), RUN_TIMEOUT_MS);
+        const onSigint = () => {
+            siginted = true;
+            controller.abort();
+        };
+        process.once("SIGINT", onSigint);
+        let streamFailed = false;
+        try {
+            for await (const event of runStream(req, apiKey, controller.signal)) {
+                if (!handleStreamEvent(event, opts.pretty)) {
+                    streamFailed = true;
+                    break;
+                }
+            }
+        }
+        catch (e) {
+            if (controller.signal.aborted) {
+                if (siginted) {
+                    process.stderr.write("\n");
+                    process.exit(130);
+                }
+                err({ error: "Run timed out after 20 minutes" });
+                process.exit(1);
+            }
+            handleApiError(e);
+        }
+        finally {
+            clearTimeout(timeout);
+            process.removeListener("SIGINT", onSigint);
+        }
+        if (streamFailed)
+            process.exit(1);
+    });
+}
+/**
+ * Handle one SSE event from the stream.
+ * Returns false on terminal error (caller should exit 1); true otherwise.
+ */
+function handleStreamEvent(event, pretty) {
+    if (event.type === StreamEventType.ERROR) {
+        err({ error: event.error, runId: event.runId, status: StreamEventType.ERROR });
+        return false;
+    }
+    if (event.type === StreamEventType.COMPLETE && event.status !== RunStatus.COMPLETED) {
+        err({ error: event.error ?? `Run ${event.status}`, runId: event.runId, status: event.status });
+        return false;
+    }
+    if (pretty) {
+        switch (event.type) {
+            case StreamEventType.STARTED:
+                outLine(`▶ Run started`);
+                break;
+            case StreamEventType.STREAMING_URL:
+                outLine(`🔗 Live view: ${event.streamingUrl}`);
+                break;
+            case StreamEventType.PROGRESS:
+                outLine(`• ${event.purpose}`);
+                break;
+            case StreamEventType.COMPLETE:
+                outLine(`✓ Completed\n\n${JSON.stringify(event.resultJson ?? {}, null, 2)}`);
+                break;
+            case StreamEventType.HEARTBEAT:
+                // silently skip — keep-alive noise
+                break;
+        }
+    }
+    else {
+        // Raw JSON: emit all events (STREAMING_URL and HEARTBEAT are useful for agents)
+        out(event);
+    }
+    return true;
+}

package/dist/commands/runs.d.ts

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

package/dist/commands/runs.js

@@ -0,0 +1,101 @@
+import { getApiKey } from "../lib/auth.js";
+import { getRun, listRuns } from "../lib/client.js";
+import { err, handleApiError, out, outLine } from "../lib/output.js";
+import { RunStatus } from "../lib/types.js";
+const VALID_STATUSES = Object.values(RunStatus);
+export function registerRuns(program) {
+    const runs = program
+        .command("runs")
+        .description("Manage past automation runs");
+    // ── runs list ──────────────────────────────────────────────────────────────
+    runs
+        .command("list")
+        .description("List your automation runs")
+        .option("--status <status>", "Filter by status (PENDING|RUNNING|COMPLETED|FAILED|CANCELLED)")
+        .option("--limit <n>", "Max number of runs to return (default: 20)")
+        .option("--cursor <cursor>", "Pagination cursor from a previous response")
+        .option("--pretty", "Human-readable output")
+        .action(async (opts) => {
+        // Validate --status
+        if (opts.status != null && !VALID_STATUSES.includes(opts.status)) {
+            err({ error: `Invalid --status "${opts.status}". Must be one of: ${VALID_STATUSES.join(", ")}` });
+            process.exit(1);
+        }
+        // Validate --limit
+        const MAX_LIMIT = 100;
+        let limit;
+        if (opts.limit != null) {
+            limit = parseInt(opts.limit, 10);
+            if (!isFinite(limit) || limit <= 0) {
+                err({ error: `Invalid --limit "${opts.limit}". Must be a positive integer.` });
+                process.exit(1);
+            }
+            if (limit > MAX_LIMIT) {
+                err({ error: `--limit cannot exceed ${MAX_LIMIT}.` });
+                process.exit(1);
+            }
+        }
+        const apiKey = getApiKey();
+        const filter = {
+            status: opts.status,
+            limit,
+            cursor: opts.cursor,
+        };
+        try {
+            const body = await listRuns(filter, apiKey);
+            if (opts.pretty) {
+                if (body.data.length === 0) {
+                    outLine("No runs found.");
+                    return;
+                }
+                outLine(`${"RUN ID".padEnd(36)}  ${"STATUS".padEnd(10)}  ${"CREATED AT".padEnd(24)}  GOAL`);
+                outLine(`${"-".repeat(36)}  ${"-".repeat(10)}  ${"-".repeat(24)}  ${"-".repeat(30)}`);
+                for (const run of body.data) {
+                    outLine(`${run.run_id.padEnd(36)}  ${run.status.padEnd(10)}  ${run.created_at.padEnd(24)}  ${run.goal}`);
+                }
+                if (body.pagination.has_more) {
+                    outLine(`\nNext cursor: ${body.pagination.next_cursor}`);
+                }
+            }
+            else {
+                out(body);
+            }
+        }
+        catch (e) {
+            handleApiError(e);
+        }
+    });
+    // ── runs get ───────────────────────────────────────────────────────────────
+    runs
+        .command("get <run_id>")
+        .description("Get a run by ID")
+        .option("--pretty", "Human-readable output")
+        .action(async (runId, opts) => {
+        const apiKey = getApiKey();
+        try {
+            const run = await getRun(runId, apiKey);
+            if (opts.pretty) {
+                outLine(`Run ID:   ${run.run_id}`);
+                outLine(`Status:   ${run.status}`);
+                outLine(`Goal:     ${run.goal}`);
+                outLine(`Created:  ${run.created_at}`);
+                if (run.started_at)
+                    outLine(`Started:  ${run.started_at}`);
+                if (run.finished_at)
+                    outLine(`Finished: ${run.finished_at}`);
+                outLine(`Steps:    ${run.num_of_steps}`);
+                if (run.result !== null && run.result !== undefined) {
+                    outLine(`\nResult:\n${JSON.stringify(run.result, null, 2)}`);
+                }
+                if (run.error)
+                    outLine(`\nError: ${run.error.message}`);
+            }
+            else {
+                out(run);
+            }
+        }
+        catch (e) {
+            handleApiError(e);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { createRequire } from "module";
+import { Command } from "commander";
+import { registerAuth } from "./commands/auth.js";
+import { registerRun } from "./commands/run.js";
+import { registerRuns } from "./commands/runs.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+const program = new Command();
+program
+    .name("tinyfish")
+    .description("TinyFish CLI — run web automations from your terminal or agent.")
+    .version(version, "-V, --version", "Show version")
+    .helpOption("-h, --help", "Show help")
+    .addHelpCommand(false)
+    .option("--debug", "Print HTTP requests and responses to stderr (or set TINYFISH_DEBUG=1)")
+    .hook("preAction", (cmd) => {
+    if (cmd.opts().debug) {
+        process.env["TINYFISH_DEBUG"] = "1";
+    }
+});
+registerAuth(program);
+registerRun(program);
+registerRuns(program);
+// Await parseAsync so async command handlers complete before the process exits
+program.parseAsync(process.argv).catch((e) => {
+    process.stderr.write(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) + "\n");
+    process.exit(1);
+});

package/dist/lib/auth.d.ts

@@ -0,0 +1,10 @@
+export { DASHBOARD_URL } from "./constants.js";
+interface TinyfishConfig {
+    api_key?: string;
+}
+export declare function loadConfig(): TinyfishConfig;
+export declare function saveConfig(apiKey: string): void;
+export declare function clearConfig(): boolean;
+export declare function validateKeyFormat(key: string): boolean;
+export declare function maskKey(key: string): string;
+export declare function getApiKey(): string;

package/dist/lib/auth.js

@@ -0,0 +1,90 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { err } from "./output.js";
+const KEY_PREFIXES = ["sk-tinyfish-", "sk-mino-"];
+const MIN_KEY_LENGTH = 20;
+export { DASHBOARD_URL } from "./constants.js";
+function configDir() {
+    // os.homedir() is cross-platform; process.env.HOME is undefined on Windows
+    return path.join(os.homedir(), ".tinyfish");
+}
+function configFile() {
+    return path.join(configDir(), "config.json");
+}
+export function loadConfig() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(configFile(), "utf8"));
+        if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+            const obj = raw;
+            return { api_key: typeof obj["api_key"] === "string" ? obj["api_key"] : undefined };
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(apiKey) {
+    const dir = configDir();
+    try {
+        // 0o700: only owner can read/write/execute the directory
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const existing = loadConfig();
+        // 0o600: only owner can read/write the config file (key is sensitive)
+        fs.writeFileSync(configFile(), JSON.stringify({ ...existing, api_key: apiKey }), {
+            mode: 0o600,
+        });
+    }
+    catch (e) {
+        err({ error: `Could not write config: ${e instanceof Error ? e.message : String(e)}` });
+        process.exit(1);
+    }
+}
+export function clearConfig() {
+    const config = loadConfig();
+    if (!config.api_key)
+        return false;
+    delete config.api_key;
+    try {
+        fs.writeFileSync(configFile(), JSON.stringify(config), { mode: 0o600 });
+        return true;
+    }
+    catch {
+        // Write failed — key was not actually removed
+        return false;
+    }
+}
+export function validateKeyFormat(key) {
+    // Reject control characters (covers CR, LF, and others) — guards against header injection
+    for (let i = 0; i < key.length; i += 1) {
+        if (key.charCodeAt(i) < 0x20)
+            return false;
+    }
+    return KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
+}
+export function maskKey(key) {
+    if (key.length <= 8)
+        return "***";
+    return key.slice(0, 12) + "..." + key.slice(-4);
+}
+export function getApiKey() {
+    const envKey = process.env.TINYFISH_API_KEY;
+    if (envKey) {
+        if (!validateKeyFormat(envKey)) {
+            err({ error: "TINYFISH_API_KEY has invalid format. Expected sk-tinyfish-... or sk-mino-..." });
+            process.exit(1);
+        }
+        return envKey;
+    }
+    const config = loadConfig();
+    if (config.api_key) {
+        if (!validateKeyFormat(config.api_key)) {
+            err({ error: "Stored API key has invalid format. Run: tinyfish auth login" });
+            process.exit(1);
+        }
+        return config.api_key;
+    }
+    err({ error: "No API key found. Run: tinyfish auth login" });
+    process.exit(1);
+}

package/dist/lib/client.d.ts

@@ -0,0 +1,6 @@
+import type { ListRunsOptions, ListRunsResponse, RunApiResponse, RunRequest, RunResult, StreamEvent } from "./types.js";
+export declare function runSync(req: RunRequest, apiKey: string, signal?: AbortSignal): Promise<RunResult>;
+export declare function runAsync(req: RunRequest, apiKey: string): Promise<RunResult>;
+export declare function runStream(req: RunRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+export declare function listRuns(opts: ListRunsOptions, apiKey: string): Promise<ListRunsResponse>;
+export declare function getRun(runId: string, apiKey: string): Promise<RunApiResponse>;

package/dist/lib/client.js

@@ -0,0 +1,116 @@
+import { BASE_URL } from "./constants.js";
+import { ApiError } from "./output.js";
+// ── Debug logging ─────────────────────────────────────────────────────────────
+const DEBUG_ENABLED = /^(1|true)$/i.test(process.env["TINYFISH_DEBUG"] ?? "");
+function debugLog(msg) {
+    if (DEBUG_ENABLED) {
+        process.stderr.write(`[debug] ${msg}\n`);
+    }
+}
+// ── Shared HTTP helpers ───────────────────────────────────────────────────────
+function headers(apiKey) {
+    return {
+        "X-API-Key": apiKey,
+        "Content-Type": "application/json",
+        "X-TF-Request-Origin": "tinyfish-cli",
+    };
+}
+async function throwIfError(res) {
+    if (!res.ok) {
+        const json = await res.json().catch(() => ({}));
+        const message = json.detail ?? `HTTP ${res.status}`;
+        throw new ApiError(res.status, message);
+    }
+}
+/** POST JSON to a path and return the raw Response, throwing ApiError on non-2xx. */
+async function postJson(path, body, apiKey, signal) {
+    const start = Date.now();
+    debugLog(`--> POST ${path}`);
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers: headers(apiKey),
+        body: JSON.stringify(body),
+        signal,
+    });
+    debugLog(`<-- ${res.status} (${Date.now() - start}ms)`);
+    await throwIfError(res);
+    return res;
+}
+/** GET a path and return the parsed JSON body, throwing ApiError on non-2xx. */
+async function getJson(path, apiKey, signal) {
+    const start = Date.now();
+    debugLog(`--> GET ${path}`);
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "GET",
+        headers: headers(apiKey),
+        signal,
+    });
+    debugLog(`<-- ${res.status} (${Date.now() - start}ms)`);
+    await throwIfError(res);
+    return res.json();
+}
+/** Yield parsed StreamEvents from a single SSE data line. */
+function* parseSseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("data:"))
+        return;
+    const data = trimmed.slice(5).trim();
+    if (!data || data === "[DONE]")
+        return;
+    try {
+        yield JSON.parse(data);
+    }
+    catch {
+        // malformed SSE line — skip
+    }
+}
+// ── Automation run ────────────────────────────────────────────────────────────
+export async function runSync(req, apiKey, signal) {
+    const res = await postJson("/v1/automation/run", req, apiKey, signal);
+    return res.json();
+}
+export async function runAsync(req, apiKey) {
+    // Async just submits the job — 30 s is plenty to get an ACK
+    const res = await postJson("/v1/automation/run-async", req, apiKey, AbortSignal.timeout(30_000));
+    return res.json();
+}
+export async function* runStream(req, apiKey, signal) {
+    const res = await postJson("/v1/automation/run-sse", req, apiKey, signal);
+    if (!res.body) {
+        throw new ApiError(200, "Empty response body");
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            // Flush remaining buffer — handles final event without trailing newline
+            for (const line of buffer.split("\n")) {
+                yield* parseSseLine(line);
+            }
+            break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            yield* parseSseLine(line);
+        }
+    }
+}
+// ── Run history ───────────────────────────────────────────────────────────────
+export async function listRuns(opts, apiKey) {
+    const params = new URLSearchParams();
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.limit != null)
+        params.set("limit", String(opts.limit));
+    if (opts.cursor)
+        params.set("cursor", opts.cursor);
+    const qs = params.size ? `?${params}` : "";
+    return getJson(`/v1/runs${qs}`, apiKey, AbortSignal.timeout(30_000));
+}
+export async function getRun(runId, apiKey) {
+    return getJson(`/v1/runs/${encodeURIComponent(runId)}`, apiKey, AbortSignal.timeout(30_000));
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const BASE_URL: string;
+/** URL where users can create and manage API keys */
+export declare const DASHBOARD_URL: string;

package/dist/lib/constants.js

@@ -0,0 +1,5 @@
+/** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted. */
+const apiUrlOverride = process.env["TINYFISH_API_URL"]?.trim();
+export const BASE_URL = apiUrlOverride || "https://agent.tinyfish.ai";
+/** URL where users can create and manage API keys */
+export const DASHBOARD_URL = `${BASE_URL}/api-keys`;

package/dist/lib/output.d.ts

@@ -0,0 +1,9 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export declare function out(data: unknown): void;
+export declare function outLine(line: string): void;
+export declare function err(data: unknown): void;
+export declare function handleApiError(e: unknown): never;

package/dist/lib/output.js

@@ -0,0 +1,35 @@
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ApiError";
+    }
+}
+export function out(data) {
+    process.stdout.write(JSON.stringify(data) + "\n");
+}
+export function outLine(line) {
+    process.stdout.write(line + "\n");
+}
+export function err(data) {
+    const payload = typeof data === "string" ? { error: data } : data;
+    process.stderr.write(JSON.stringify(payload) + "\n");
+}
+export function handleApiError(e) {
+    if (e instanceof ApiError) {
+        const payload = { error: e.message, status: e.status };
+        if (e.code)
+            payload.code = e.code;
+        err(payload);
+    }
+    else if (e instanceof Error) {
+        err({ error: e.message });
+    }
+    else {
+        err({ error: String(e) });
+    }
+    process.exit(1);
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,96 @@
+export interface RunRequest {
+    goal: string;
+    url: string;
+}
+export declare const RunStatus: {
+    readonly PENDING: "PENDING";
+    readonly RUNNING: "RUNNING";
+    readonly COMPLETED: "COMPLETED";
+    readonly FAILED: "FAILED";
+    readonly CANCELLED: "CANCELLED";
+};
+export type RunStatus = (typeof RunStatus)[keyof typeof RunStatus];
+export declare const StreamEventType: {
+    readonly STARTED: "STARTED";
+    readonly STREAMING_URL: "STREAMING_URL";
+    readonly HEARTBEAT: "HEARTBEAT";
+    readonly PROGRESS: "PROGRESS";
+    readonly COMPLETE: "COMPLETE";
+    readonly ERROR: "ERROR";
+};
+export type StreamEventType = (typeof StreamEventType)[keyof typeof StreamEventType];
+export interface RunResult {
+    runId: string;
+    status: RunStatus;
+    resultJson?: unknown;
+    error?: string;
+}
+/** Discriminated union of all real SSE event shapes from the API */
+export type StreamEvent = {
+    type: typeof StreamEventType.STARTED;
+    runId: string;
+    timestamp: string;
+} | {
+    type: typeof StreamEventType.STREAMING_URL;
+    runId: string;
+    streamingUrl: string;
+    timestamp: string;
+} | {
+    type: typeof StreamEventType.HEARTBEAT;
+    timestamp: string;
+} | {
+    type: typeof StreamEventType.PROGRESS;
+    runId: string;
+    purpose: string;
+    timestamp: string;
+} | {
+    type: typeof StreamEventType.COMPLETE;
+    runId: string;
+    status: RunStatus;
+    timestamp: string;
+    resultJson?: unknown;
+    error?: string;
+    help_url?: string;
+    help_message?: string;
+} | {
+    type: typeof StreamEventType.ERROR;
+    runId?: string;
+    error: string;
+    timestamp: string;
+};
+export interface RunError {
+    message: string;
+    category: string;
+    retry_after: string | null;
+    help_url: string | null;
+    help_message: string | null;
+}
+export interface RunApiResponse {
+    run_id: string;
+    status: RunStatus;
+    goal: string;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+    num_of_steps: number;
+    result: unknown;
+    error: RunError | null;
+    streaming_url: string | null;
+    browser_config: {
+        proxy_enabled: boolean | null;
+        proxy_country_code: string | null;
+    } | null;
+}
+export interface ListRunsResponse {
+    data: RunApiResponse[];
+    pagination: {
+        total: number;
+        next_cursor: string | null;
+        has_more: boolean;
+    };
+}
+export interface ListRunsOptions {
+    status?: RunStatus;
+    limit?: number;
+    cursor?: string;
+}

package/dist/lib/types.js

@@ -0,0 +1,18 @@
+// ── Automation run request ────────────────────────────────────────────────────
+// ── Run status enum ───────────────────────────────────────────────────────────
+export const RunStatus = {
+    PENDING: "PENDING",
+    RUNNING: "RUNNING",
+    COMPLETED: "COMPLETED",
+    FAILED: "FAILED",
+    CANCELLED: "CANCELLED",
+};
+// ── SSE event types ───────────────────────────────────────────────────────────
+export const StreamEventType = {
+    STARTED: "STARTED",
+    STREAMING_URL: "STREAMING_URL",
+    HEARTBEAT: "HEARTBEAT",
+    PROGRESS: "PROGRESS",
+    COMPLETE: "COMPLETE",
+    ERROR: "ERROR",
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tiny-fish/cli",
+  "version": "0.1.0",
+  "description": "TinyFish CLI — run web automations from your terminal",
+  "type": "module",
+  "bin": {
+    "tinyfish": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "vitest --run",
+    "test:file": "vitest --run",
+    "test:watch": "vitest",
+    "test:integration": "vitest --run --config vitest.integration.config.ts",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "type-check": "tsc --noEmit --project tsconfig.all.json"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "globals": "^17.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}