@tiny-fish/cli 0.23.1-next.201 → 0.23.1-next.204

package/README.md

@@ -142,7 +142,18 @@ tinyfish agent run "Check checkout" \
   --url https://example.com \
   --browser-profile stealth \
   --mode strict \
-  --max-steps 75
+  --max-steps 75 \
+  --max-duration-seconds 300 \
+  --cursor-style standard
+
+# Capture run artifacts, send a webhook, and use a saved profile
+tinyfish agent run "Check checkout" \
+  --url https://example.com \
+  --capture-screenshots \
+  --capture-html \
+  --capture-recording \
+  --webhook-url https://example.com/tinyfish-webhook \
+  --use-profile
 
 # Wait for result without streaming
 tinyfish agent run "Find the pricing page" --url https://example.com --sync
@@ -163,6 +174,15 @@ tinyfish agent run "Extract the product price" \
   --output-schema-file ./schemas/product-price.json
 ```
 
+### Agent option flags
+
+- `--cursor-style`, `--max-duration-seconds`, `--mode`, `--max-steps` — agent behavior, sent as `agent_config`
+- `--capture-elements`, `--capture-snapshots`, `--capture-screenshots`, `--capture-recording`, `--capture-html` — artifacts to capture, sent as `capture_config`
+- `--webhook-url` — HTTPS URL notified on run lifecycle events; validated locally
+- `--use-profile`, `--profile-id` — start from a Browser Context Profile; `--profile-id` requires `--use-profile`
+
+`--capture-elements` and `--capture-recording` are gated capabilities: an account without them enabled gets a 403 saying the capability is not enabled. The other capture flags are ungated.
+
 ### Structured output
 
 Use `--output-schema <json>` for short inline schemas and `--output-schema-file <path>` for schemas you want to reuse, review, or keep in source control.

package/dist/commands/run.js

@@ -7,6 +7,7 @@ import { err, errLine, handleApiError, out, outLine } from "../lib/output.js";
 import { BASE_URL } from "../lib/constants.js";
 const VALID_BROWSER_PROFILES = ["lite", "stealth"];
 const VALID_MODES = ["default", "strict"];
+const VALID_CURSOR_STYLES = ["fish", "standard", "green-pointer"];
 const MAX_STEPS_LIMIT = 500;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function parseSessionId(value) {
@@ -69,19 +70,36 @@ function parseChoice(value, valid, flag) {
     err({ error: `Invalid ${flag} "${value}". Must be one of: ${valid.join(", ")}` });
     process.exit(1);
 }
-function parseMaxSteps(value) {
+function parsePositiveInteger(value, flag, max) {
     if (value === undefined)
         return undefined;
-    if (!/^\d+$/.test(value)) {
-        err({ error: `Invalid --max-steps "${value}". Must be a positive integer.` });
+    const parsed = Number(value);
+    if (!/^\d+$/.test(value) || parsed < 1 || (max !== undefined && parsed > max)) {
+        err({
+            error: max === undefined
+                ? `Invalid ${flag} "${value}". Must be a positive integer.`
+                : `${flag} must be between 1 and ${max}.`,
+        });
+        process.exit(1);
+    }
+    return parsed;
+}
+function parseHttpsUrl(value, flag) {
+    if (value === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        err({ error: `Invalid ${flag} "${value}". Provide a valid URL.` });
         process.exit(1);
     }
-    const maxSteps = Number(value);
-    if (maxSteps < 1 || maxSteps > MAX_STEPS_LIMIT) {
-        err({ error: `--max-steps must be between 1 and ${MAX_STEPS_LIMIT}.` });
+    if (parsed.protocol !== "https:") {
+        err({ error: `${flag} must use HTTPS.` });
         process.exit(1);
     }
-    return maxSteps;
+    return value;
 }
 async function loadOutputSchema(opts) {
     if (opts.outputSchema !== undefined && opts.outputSchemaFile !== undefined) {
@@ -114,7 +132,18 @@ export function registerRun(agentCmd) {
         .option("--output-schema-file <path>", "Path to a JSON file containing the output schema")
         .option("--browser-profile <profile>", "Browser profile for execution (lite|stealth)")
         .option("--max-steps <n>", `Maximum tool-call steps before stopping (1-${MAX_STEPS_LIMIT})`)
+        .option("--max-duration-seconds <n>", "Maximum wall-clock seconds before stopping")
         .option("--mode <mode>", "Agent behavior mode (default|strict)")
+        .option("--cursor-style <style>", "Cursor style (fish|standard|green-pointer)")
+        .option("--capture-elements", "Capture page element metadata (gated capability; returns 403 if not enabled for your account)")
+        .option("--capture-snapshots", "Capture page snapshots")
+        .option("--capture-screenshots", "Capture screenshots")
+        .option("--no-capture-screenshots", "Disable screenshot capture")
+        .option("--capture-recording", "Capture a browser recording (gated capability; returns 403 if not enabled for your account)")
+        .option("--capture-html", "Capture HTML snapshots")
+        .option("--webhook-url <url>", "HTTPS webhook URL for run lifecycle events")
+        .option("--use-profile", "Use an attached browser profile")
+        .option("--profile-id <id>", "Browser Context Profile ID to start from (requires --use-profile)")
         .option("--session-id <uuid>", "Caller-provided UUID for idempotency / parallel-safe --sync")
         .option("--use-vault", "Consume vault credentials in this run")
         .option("--credential-item-id <id>", "Scope vault to a specific credential item ID (repeat for multiple; get IDs from `vault item list`; requires --use-vault)", (v, acc) => [...acc, v], [])
@@ -161,18 +190,58 @@ export function registerRun(agentCmd) {
             err({ error: "--credential-item-id requires --use-vault" });
             process.exit(1);
         }
+        // The server rejects profile_id without use_profile (400); fail fast here.
+        if (opts.profileId !== undefined && !opts.useProfile) {
+            err({ error: "--profile-id requires --use-profile" });
+            process.exit(1);
+        }
         const outputSchema = await loadOutputSchema(opts);
         const browserProfile = parseChoice(opts.browserProfile, VALID_BROWSER_PROFILES, "--browser-profile");
         const mode = parseChoice(opts.mode, VALID_MODES, "--mode");
-        const maxSteps = parseMaxSteps(opts.maxSteps);
+        const cursorStyle = parseChoice(opts.cursorStyle, VALID_CURSOR_STYLES, "--cursor-style");
+        const maxSteps = parsePositiveInteger(opts.maxSteps, "--max-steps", MAX_STEPS_LIMIT);
+        const maxDurationSeconds = parsePositiveInteger(opts.maxDurationSeconds, "--max-duration-seconds");
         const sessionId = parseSessionId(opts.sessionId);
+        const webhookUrl = parseHttpsUrl(opts.webhookUrl, "--webhook-url");
+        const agentConfig = mode !== undefined ||
+            cursorStyle !== undefined ||
+            maxSteps !== undefined ||
+            maxDurationSeconds !== undefined
+            ? {
+                ...(mode !== undefined ? { mode } : {}),
+                ...(cursorStyle !== undefined ? { cursor_style: cursorStyle } : {}),
+                ...(maxSteps !== undefined ? { max_steps: maxSteps } : {}),
+                ...(maxDurationSeconds !== undefined
+                    ? { max_duration_seconds: maxDurationSeconds }
+                    : {}),
+            }
+            : undefined;
+        const captureConfig = opts.captureElements !== undefined ||
+            opts.captureSnapshots !== undefined ||
+            opts.captureScreenshots !== undefined ||
+            opts.captureRecording !== undefined ||
+            opts.captureHtml !== undefined
+            ? {
+                ...(opts.captureElements !== undefined ? { elements: opts.captureElements } : {}),
+                ...(opts.captureSnapshots !== undefined ? { snapshots: opts.captureSnapshots } : {}),
+                ...(opts.captureScreenshots !== undefined
+                    ? { screenshots: opts.captureScreenshots }
+                    : {}),
+                ...(opts.captureRecording !== undefined ? { recording: opts.captureRecording } : {}),
+                ...(opts.captureHtml !== undefined ? { html: opts.captureHtml } : {}),
+            }
+            : undefined;
         const apiKey = getApiKey();
         const req = {
             goal,
             url: normalizedUrl,
             ...(outputSchema !== undefined ? { output_schema: outputSchema } : {}),
             ...(browserProfile !== undefined ? { browser_profile: browserProfile } : {}),
-            ...(mode !== undefined || maxSteps !== undefined ? { agent_config: { mode, max_steps: maxSteps } } : {}),
+            ...(agentConfig !== undefined ? { agent_config: agentConfig } : {}),
+            ...(captureConfig !== undefined ? { capture_config: captureConfig } : {}),
+            ...(webhookUrl !== undefined ? { webhook_url: webhookUrl } : {}),
+            ...(opts.useProfile !== undefined ? { use_profile: opts.useProfile } : {}),
+            ...(opts.profileId !== undefined ? { profile_id: opts.profileId } : {}),
             ...(sessionId !== undefined ? { session_id: sessionId } : {}),
             ...(opts.useVault ? { use_vault: true } : {}),
             ...(hasCredentialItemIds ? { credential_item_ids: opts.credentialItemId } : {}),

package/dist/lib/client.js

@@ -54,6 +54,9 @@ class TinyFishCliClient extends TinyFish {
             headers["X-TF-Client-Version"] = clientVersion;
         // Agent-vs-human signal, independent of harness detection or skill install.
         headers["X-TF-Human-Initiated"] = detectHumanInitiated() ? "true" : "false";
+        if (process.env["TF_SETUP_VERIFICATION"] === "1") {
+            headers["X-TF-Setup-Verification"] = "true";
+        }
         // Reuse the already-resolved client_name so connect_client can never diverge from it
         // (same sanitize + precedence, not a second raw read of TF_CLIENT_NAME).
         const connectCaller = clientName || null;

package/dist/lib/connect-all.js

@@ -3,6 +3,8 @@ import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, connectOpencode, } from "../commands/connect.js";
 import { validatedApiKey } from "./auth.js";
 import { NATIVE_MCP_CLIENTS } from "./connect-clients.js";
+import { ensureCliAuthenticated, installTinyFishCli, TINYFISH_CLI_NOT_FOUND_MESSAGE, } from "./connect-install.js";
+import { commandNotFound, ConnectInterruptedError, ConnectStepError, throwIfInterrupted, } from "./connect-runtime.js";
 import { detectInstalledHarnesses, ALL_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -234,6 +236,72 @@ function computeExitCode(results) {
         return 0;
     return attempted.some((r) => r.outcome === "installed") ? 0 : 1;
 }
+const SEARCH_RETRY = 'tinyfish search query --pretty -- "<your query>"';
+function searchRetry(query) {
+    if (process.platform === "win32")
+        return SEARCH_RETRY;
+    return `tinyfish search query --pretty -- '${query.replaceAll("'", "'\\''")}'`;
+}
+async function runCliFallback(opts, prompt) {
+    try {
+        installTinyFishCli({ verbose: true });
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        errLine(error instanceof Error ? error.message : String(error));
+        outLine("Retry: npx @tiny-fish/cli connect --all");
+        return 1;
+    }
+    const apiKey = opts.apiKey ?? process.env["TINYFISH_API_KEY"];
+    if (!prompt && !apiKey) {
+        outLine("Retry in a terminal: npx @tiny-fish/cli connect --all");
+        return 1;
+    }
+    try {
+        ensureCliAuthenticated("cli", apiKey);
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        errLine(error instanceof Error ? error.message : String(error));
+        outLine(error instanceof ConnectStepError && error.failureReason === "command_not_found"
+            ? "Retry in a new terminal: tinyfish auth login"
+            : "Retry: tinyfish auth login");
+        return 1;
+    }
+    if (!prompt) {
+        outLine(`Retry in a terminal: ${SEARCH_RETRY}`);
+        return 1;
+    }
+    let query;
+    try {
+        query = (await prompt("What would you like to search? ")).trim();
+    }
+    catch {
+        outLine(`Retry: ${SEARCH_RETRY}`);
+        return 1;
+    }
+    if (!query) {
+        outLine(`Retry: ${SEARCH_RETRY}`);
+        return 1;
+    }
+    const search = spawn.sync("tinyfish", ["search", "query", "--pretty", "--", query], {
+        stdio: "inherit",
+        env: { ...process.env, TF_SETUP_VERIFICATION: "1" },
+    });
+    if (commandNotFound(search.error)) {
+        errLine(TINYFISH_CLI_NOT_FOUND_MESSAGE);
+        outLine(`Retry in a new terminal: ${searchRetry(query)}`);
+        return 1;
+    }
+    throwIfInterrupted(search);
+    if (search.error || search.status !== 0) {
+        outLine(`Retry: ${searchRetry(query)}`);
+        return 1;
+    }
+    return 0;
+}
 export async function runConnectAll(opts) {
     const isTTY = detectHumanInitiated();
     let stdinClosed = false;
@@ -300,6 +368,18 @@ export async function runConnectAll(opts) {
     for (const result of results)
         outLine(summaryLine(result, opts.uninstall));
     if (results.every((r) => !r.detected)) {
+        if (!opts.dryRun && !opts.uninstall) {
+            try {
+                return await runCliFallback(opts, prompt);
+            }
+            catch (error) {
+                if (!(error instanceof ConnectInterruptedError))
+                    throw error;
+                errLine("Setup interrupted — run the command again to finish.");
+                process.exitCode = 130;
+                return 130;
+            }
+        }
         outLine("");
         outLine("No supported harness found. Install one of: " + ALL_HARNESSES.join(", "));
         if (!opts.uninstall)

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

@@ -20,4 +20,4 @@ export declare function installWebSkill(client: NativeMcpClient): void;
  * Returns whether a skill was actually rewritten.
  */
 export declare function updateWebSkill({ verbose }: InstallOptions): boolean;
-export declare function ensureCliAuthenticated(source: AgentClient, apiKey?: string): void;
+export declare function ensureCliAuthenticated(source: AgentClient | "cli", apiKey?: string): void;

package/dist/lib/types.d.ts

@@ -4,8 +4,18 @@ export interface CliAgentRunParams extends AgentRunParams {
     output_schema?: OutputSchema;
     agent_config?: {
         mode?: "default" | "strict";
+        cursor_style?: "fish" | "standard" | "green-pointer";
         max_steps?: number;
+        max_duration_seconds?: number;
     };
+    capture_config?: {
+        elements?: boolean;
+        snapshots?: boolean;
+        screenshots?: boolean;
+        recording?: boolean;
+        html?: boolean;
+    };
+    webhook_url?: string;
     browser_profile?: BrowserProfile;
     session_id?: string;
     use_vault?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.23.1-next.201",
+  "version": "0.23.1-next.204",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@tiny-fish/sdk": "^0.4.0",
+    "@tiny-fish/sdk": "^0.5.0",
     "chrome-cookies-secure": "^3.0.2",
     "commander": "^12.0.0",
     "cross-spawn": "^7.0.6",