@tiny-fish/cli 0.1.4 → 0.1.5-next.47

package/README.md

@@ -41,6 +41,36 @@ tinyfish agent run "Find the pricing page" --url https://example.com --sync
 
 # Submit and return immediately (don't wait)
 tinyfish agent run "Find the pricing page" --url https://example.com --async
+
+# Request structured output with an inline JSON Schema
+tinyfish agent run "Extract the product price" \
+  --url https://example.com/product \
+  --sync \
+  --output-schema "{\"type\":\"object\",\"properties\":{\"price\":{\"type\":\"string\"}},\"required\":[\"price\"]}"
+
+# Or load the schema from a file
+tinyfish agent run "Extract the product price" \
+  --url https://example.com/product \
+  --sync \
+  --output-schema-file ./schemas/product-price.json
+```
+
+### 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.
+Both flags work with the default streaming mode, `--sync`, and `--async`.
+
+Example schema file:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "price": { "type": "string" },
+    "currency": { "type": "string" }
+  },
+  "required": ["price", "currency"]
+}
 ```
 
 ### Manage runs
@@ -59,12 +89,56 @@ tinyfish agent run get <run_id> --pretty
 tinyfish agent run cancel <run_id> --pretty
 ```
 
+### Search
+
+```bash
+# Query TinyFish Search
+tinyfish search query "agentql pricing"
+
+# Add location and language hints
+tinyfish search query "agentql pricing" --location US --language en
+
+# Human-readable output
+tinyfish search query "agentql pricing" --pretty
+```
+
+### Fetch
+
+```bash
+# Fetch extracted content from one or more URLs
+tinyfish fetch content get https://agentql.com
+
+# Choose the output format
+tinyfish fetch content get https://agentql.com --format markdown
+
+# Include links and image links
+tinyfish fetch content get https://agentql.com --links --image-links
+
+# Human-readable output
+tinyfish fetch content get https://agentql.com --pretty
+```
+
+### Browser
+
+```bash
+# Create a remote browser session
+tinyfish browser session create
+
+# Open a URL when the session starts
+tinyfish browser session create --url https://agentql.com
+
+# Human-readable output
+tinyfish browser session create --pretty
+```
+
 ### Output format
 
 By default all commands output newline-delimited JSON to stdout — pipe-friendly for agents and scripts. Add `--pretty` for human-readable output.
 
 Errors are JSON to stderr with exit code 1. Ctrl+C during a streaming run cancels it automatically.
 
+`--output-schema` and `--output-schema-file` are mutually exclusive. Both inputs must parse to a top-level JSON object. The CLI only validates that outer shape locally; the API performs full schema validation and may return errors such as `INVALID_INPUT` or feature-flag access failures.
+
 ### Debug
 
 ```bash

package/dist/commands/browser.d.ts

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

package/dist/commands/browser.js

@@ -0,0 +1,41 @@
+import { getApiKey } from "../lib/auth.js";
+import { browserSessionCreate } from "../lib/client.js";
+import { handleApiError, out, outLine } from "../lib/output.js";
+function printPrettyBrowserSession(session) {
+    outLine("Browser session created");
+    outLine(`Session ID: ${session.session_id}`);
+    outLine(`CDP URL: ${session.cdp_url}`);
+    outLine(`Base URL: ${session.base_url}`);
+}
+export function registerBrowser(program) {
+    const browserCmd = program
+        .command("browser")
+        .description("Browser commands")
+        .enablePositionalOptions();
+    const sessionCmd = browserCmd
+        .command("session")
+        .description("Manage browser sessions")
+        .enablePositionalOptions();
+    sessionCmd
+        .command("create")
+        .description("Create a remote browser session")
+        .option("--url <value>", "Open a URL after session creation")
+        .option("--pretty", "Human-readable output")
+        .action(async (opts) => {
+        const apiKey = getApiKey();
+        try {
+            const response = await browserSessionCreate({
+                ...(opts.url !== undefined ? { url: opts.url } : {}),
+            }, apiKey);
+            if (opts.pretty) {
+                printPrettyBrowserSession(response);
+            }
+            else {
+                out(response);
+            }
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    });
+}

package/dist/commands/fetch.d.ts

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

package/dist/commands/fetch.js

@@ -0,0 +1,66 @@
+import { getApiKey } from "../lib/auth.js";
+import { fetchContentGet } from "../lib/client.js";
+import { handleApiError, out, outLine } from "../lib/output.js";
+function printPrettyFetch(response) {
+    outLine(`Results: ${response.results.length}`);
+    outLine(`Errors: ${response.errors.length}`);
+    outLine("");
+    if (response.results.length > 0) {
+        outLine("Successful fetches:");
+        for (const result of response.results) {
+            outLine(`- ${result.url}`);
+            outLine(`  Format: ${result.format}`);
+            if (result.title)
+                outLine(`  Title: ${result.title}`);
+            if (result.final_url && result.final_url !== result.url)
+                outLine(`  Final URL: ${result.final_url}`);
+            outLine("");
+        }
+    }
+    if (response.errors.length > 0) {
+        outLine("Errors:");
+        for (const error of response.errors) {
+            outLine(`- ${error.url}`);
+            outLine(`  ${error.error}`);
+            outLine("");
+        }
+    }
+}
+export function registerFetch(program) {
+    const fetchCmd = program
+        .command("fetch")
+        .description("Fetch commands")
+        .enablePositionalOptions();
+    const contentCmd = fetchCmd
+        .command("content")
+        .description("Content extraction commands")
+        .enablePositionalOptions();
+    contentCmd
+        .command("get")
+        .description("Fetch clean content from one or more URLs")
+        .argument("<urls...>", "One or more URLs to fetch")
+        .option("--format <format>", "Output format: markdown, html, or json")
+        .option("--links", "Include extracted links")
+        .option("--image-links", "Include extracted image links")
+        .option("--pretty", "Human-readable output")
+        .action(async (urls, opts) => {
+        const apiKey = getApiKey();
+        try {
+            const response = await fetchContentGet({
+                urls,
+                ...(opts.format !== undefined ? { format: opts.format } : {}),
+                ...(opts.links !== undefined ? { links: opts.links } : {}),
+                ...(opts.imageLinks !== undefined ? { image_links: opts.imageLinks } : {}),
+            }, apiKey);
+            if (opts.pretty) {
+                printPrettyFetch(response);
+            }
+            else {
+                out(response);
+            }
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    });
+}

package/dist/commands/run.js

@@ -1,8 +1,11 @@
 import { EventType, RunStatus } from "@tiny-fish/sdk";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
 import { getApiKey } from "../lib/auth.js";
 import { cancelRun, runAsync, runStream, runSync } from "../lib/client.js";
 import { err, errLine, handleApiError, out, outLine } from "../lib/output.js";
 import { BASE_URL } from "../lib/constants.js";
+const outputSchemaFieldSchema = z.object({}).catchall(z.unknown());
 function extractErrorMessage(error) {
     if (typeof error === "string")
         return error;
@@ -29,6 +32,42 @@ function checkRunResult(result, expectComplete = true) {
         process.exit(1);
     }
 }
+function parseOutputSchema(rawOutputSchema, sourceLabel) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawOutputSchema);
+    }
+    catch {
+        err({ error: `Invalid ${sourceLabel} JSON. Provide a valid JSON object.` });
+        process.exit(1);
+    }
+    const result = outputSchemaFieldSchema.safeParse(parsed);
+    if (!result.success) {
+        err({ error: `${sourceLabel} must be a JSON object` });
+        process.exit(1);
+    }
+    return result.data;
+}
+async function loadOutputSchema(opts) {
+    if (opts.outputSchema !== undefined && opts.outputSchemaFile !== undefined) {
+        err({ error: "--output-schema and --output-schema-file are mutually exclusive" });
+        process.exit(1);
+    }
+    if (opts.outputSchema !== undefined) {
+        return parseOutputSchema(opts.outputSchema, "--output-schema");
+    }
+    if (opts.outputSchemaFile === undefined)
+        return undefined;
+    let fileContents;
+    try {
+        fileContents = await readFile(opts.outputSchemaFile, "utf8");
+    }
+    catch {
+        err({ error: `Unable to read --output-schema-file "${opts.outputSchemaFile}"` });
+        process.exit(1);
+    }
+    return parseOutputSchema(fileContents, "--output-schema-file");
+}
 export function registerRun(agentCmd) {
     const runCmd = agentCmd
         .command("run")
@@ -36,6 +75,8 @@ export function registerRun(agentCmd) {
         .option("--url <url>", "Target URL for the automation")
         .option("--sync", "Wait for result without streaming steps")
         .option("--async", "Submit without waiting for result")
+        .option("--output-schema <json>", "Inline JSON Schema object for structured output")
+        .option("--output-schema-file <path>", "Path to a JSON file containing the output schema")
         .option("--pretty", "Human-readable output")
         .argument("[goal]", "Goal to automate")
         .action(async (goal, opts) => {
@@ -72,8 +113,13 @@ export function registerRun(agentCmd) {
             err({ error: 'Goal cannot be empty' });
             process.exit(1);
         }
+        const outputSchema = await loadOutputSchema(opts);
         const apiKey = getApiKey();
-        const req = { goal, url: normalizedUrl };
+        const req = {
+            goal,
+            url: normalizedUrl,
+            ...(outputSchema !== undefined ? { output_schema: outputSchema } : {}),
+        };
         if (opts.async) {
             let result;
             try {

package/dist/commands/search.d.ts

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

package/dist/commands/search.js

@@ -0,0 +1,50 @@
+import { getApiKey } from "../lib/auth.js";
+import { searchQuery } from "../lib/client.js";
+import { handleApiError, out, outLine } from "../lib/output.js";
+function printPrettySearch(response) {
+    outLine(`Query: ${response.query}`);
+    outLine(`Total results: ${response.total_results}`);
+    outLine("");
+    if (response.results.length === 0) {
+        outLine("No results.");
+        return;
+    }
+    for (const result of response.results) {
+        outLine(`${result.position}. ${result.title}`);
+        outLine(`   ${result.url}`);
+        outLine(`   ${result.snippet}`);
+        outLine("");
+    }
+}
+export function registerSearch(program) {
+    const searchCmd = program
+        .command("search")
+        .description("Search commands")
+        .enablePositionalOptions();
+    searchCmd
+        .command("query")
+        .description("Query TinyFish Search")
+        .argument("<query>", "Search query")
+        .option("--location <value>", "Search location hint")
+        .option("--language <value>", "Search language hint")
+        .option("--pretty", "Human-readable output")
+        .action(async (query, opts) => {
+        const apiKey = getApiKey();
+        try {
+            const response = await searchQuery({
+                query,
+                ...(opts.location !== undefined ? { location: opts.location } : {}),
+                ...(opts.language !== undefined ? { language: opts.language } : {}),
+            }, apiKey);
+            if (opts.pretty) {
+                printPrettySearch(response);
+            }
+            else {
+                out(response);
+            }
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    });
+}

package/dist/index.js

@@ -3,8 +3,11 @@ import { createRequire } from "module";
 import { Command } from "commander";
 import { registerAuth } from "./commands/auth.js";
 import { registerBatch } from "./commands/batch.js";
+import { registerFetch } from "./commands/fetch.js";
+import { registerBrowser } from "./commands/browser.js";
 import { registerRun } from "./commands/run.js";
 import { registerRuns } from "./commands/runs.js";
+import { registerSearch } from "./commands/search.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
 program
@@ -21,6 +24,7 @@ program
     }
 });
 registerAuth(program);
+registerBrowser(program);
 const agentCmd = program
     .command("agent")
     .description("Agent automation commands")
@@ -28,6 +32,8 @@ const agentCmd = program
 const runCmd = registerRun(agentCmd);
 registerRuns(runCmd);
 registerBatch(agentCmd);
+registerSearch(program);
+registerFetch(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");

package/dist/lib/client.d.ts

@@ -1,10 +1,13 @@
-import { type AgentRunAsyncResponse, type AgentRunParams, type AgentRunResponse, type AgentRunWithStreamingResponse, type Run, type RunListParams, type RunListResponse } from "@tiny-fish/sdk";
-import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse } from "./types.js";
-export declare function runSync(req: AgentRunParams, apiKey: string): Promise<AgentRunResponse>;
-export declare function runAsync(req: AgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
-export declare function runStream(req: AgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
+import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStreamingResponse, type FetchGetContentsParams, type FetchResponse, type BrowserSession, type BrowserSessionCreateParams, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse } from "@tiny-fish/sdk";
+import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams } from "./types.js";
+export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
+export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
+export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
 export declare function listRuns(opts: RunListParams, apiKey: string): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
+export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;
+export declare function fetchContentGet(params: FetchGetContentsParams, apiKey: string): Promise<FetchResponse>;
+export declare function browserSessionCreate(params: BrowserSessionCreateParams, apiKey: string): Promise<BrowserSession>;
 export declare function cancelRun(runId: string, apiKey: string): Promise<CancelRunResponse>;
 export declare function submitBatch(req: BatchRunRequest, apiKey: string): Promise<BatchRunResponse>;
 export declare function getBatchRuns(runIds: string[], apiKey: string): Promise<BatchGetResponse>;

package/dist/lib/client.js

@@ -1,4 +1,4 @@
-import { APIStatusError, TinyFish, runSchema, } from "@tiny-fish/sdk";
+import { APIStatusError, fetchResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, } from "@tiny-fish/sdk";
 import { BASE_URL } from "./constants.js";
 import { ApiError } from "./output.js";
 import { z } from "zod";
@@ -115,6 +115,33 @@ export async function getRun(runId, apiKey) {
         rethrowSdkError(error);
     }
 }
+export async function searchQuery(params, apiKey) {
+    try {
+        const response = await createSdkClient(apiKey).search.query(params);
+        return searchQueryResponseSchema.parse(response);
+    }
+    catch (error) {
+        rethrowSdkError(error);
+    }
+}
+export async function fetchContentGet(params, apiKey) {
+    try {
+        const response = await createSdkClient(apiKey).fetch.getContents(params);
+        return fetchResponseSchema.parse(response);
+    }
+    catch (error) {
+        rethrowSdkError(error);
+    }
+}
+export async function browserSessionCreate(params, apiKey) {
+    try {
+        const response = await createSdkClient(apiKey).browser.sessions.create(params);
+        return browserSessionSchema.parse(response);
+    }
+    catch (error) {
+        rethrowSdkError(error);
+    }
+}
 export async function cancelRun(runId, apiKey) {
     try {
         const response = await createSdkClient(apiKey).post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, { json: {} });

package/dist/lib/types.d.ts

@@ -1,4 +1,8 @@
-import type { Run, RunStatus } from "@tiny-fish/sdk";
+import type { AgentRunParams, Run, RunStatus } from "@tiny-fish/sdk";
+export type OutputSchema = Record<string, unknown>;
+export interface CliAgentRunParams extends AgentRunParams {
+    output_schema?: OutputSchema;
+}
 export interface CancelRunResponse {
     run_id: string;
     status: RunStatus | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.1.4",
+  "version": "0.1.5-next.47",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -16,7 +16,16 @@
     "test": "vitest --run",
     "test:file": "vitest --run",
     "test:watch": "vitest",
-    "test:integration": "vitest --run --config vitest.integration.config.ts",
+    "test:integration:auth": "vitest --run --config vitest.integration.config.ts tests/auth.integration.test.ts",
+    "test:integration:api:fetch": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"fetch content get|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:browser": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"browser session create|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:search": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"search query|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:sync": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"agent run --sync|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:stream": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"agent run streaming exits cleanly after COMPLETE|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:async": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"agent run --async returns a run id that can be fetched and listed|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:cancel": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"agent run cancel cancels an in-flight run|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration:api:batch": "vitest --run --passWithNoTests --config vitest.integration.config.ts tests/api.integration.test.ts --testNamePattern \"batch commands work end-to-end against the real API|skips real API coverage when TINYFISH_API_KEY is not set\"",
+    "test:integration": "npm run test:integration:auth && npm run test:integration:api:fetch && npm run test:integration:api:browser && npm run test:integration:api:search && npm run test:integration:api:sync && npm run test:integration:api:stream && npm run test:integration:api:async && npm run test:integration:api:cancel && npm run test:integration:api:batch",
     "lint": "eslint src tests",
     "format": "prettier --write src tests",
     "type-check": "tsc --noEmit --project tsconfig.all.json",
@@ -39,6 +48,7 @@
     "vitest": "^3.0.0"
   },
   "overrides": {
+    "vite": "7.3.2",
     "brace-expansion": "5.0.5"
   },
   "engines": {