@tiny-fish/cli 0.1.5-next.44 → 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
@@ -107,6 +137,8 @@ By default all commands output newline-delimited JSON to stdout — pipe-friendl
 
 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/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/lib/client.d.ts

@@ -1,8 +1,8 @@
-import { type AgentRunAsyncResponse, type AgentRunParams, 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 } 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>;

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