@clickraft/cli 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,16 +1,13 @@
-## [0.13.0](https://github.com/clickraft/cli/compare/v0.12.0...v0.13.0) (2026-08-08)
+## [0.15.0](https://github.com/clickraft/cli/compare/v0.14.0...v0.15.0) (2026-09-25)
 
 ### Features
 
-* **cli:** add product create ([fe46251](https://github.com/clickraft/cli/commit/fe4625100ae9af7571e0b97156d58eba59e9aea1))
-* **cli:** request products:write at login and degrade when the server refuses it ([a8b6db2](https://github.com/clickraft/cli/commit/a8b6db24d2789df834bffdf6290cb1bebd41116c))
-* **errors:** recognize the five product-create error codes ([9e0aef4](https://github.com/clickraft/cli/commit/9e0aef4a3eb0cf188b1016f70b7c326b14b7cd8b))
-* **mcp:** add the product_create tool ([f725172](https://github.com/clickraft/cli/commit/f725172c9df13af80c244c93506036c178008284))
-* **sdk:** add the product create request contract ([75ae3c7](https://github.com/clickraft/cli/commit/75ae3c78b011b5278a21da75d247e7452e2c630c))
-
-### Bug Fixes
-
-* **cli:** point the insufficient-scope hint at login --force-reauth ([398abd3](https://github.com/clickraft/cli/commit/398abd3ba7928706faf7f505038c4b52361b4a68))
+* **cli:** add generate list and generate estimate ([938df07](https://github.com/clickraft/cli/commit/938df073db7d234c6516f0bfe45dab9c5ea8db41))
+* **cli:** save a completed result with --output ([8265d7a](https://github.com/clickraft/cli/commit/8265d7ac4fa7057264123b6856a425a193a79c9b))
+* **mcp:** add generate_history and generate_estimate ([3288baa](https://github.com/clickraft/cli/commit/3288baadc4ddfccbd04114a2a3434515b78c2b64))
+* **mcp:** show generations inline with MCP Apps widgets ([ca318a5](https://github.com/clickraft/cli/commit/ca318a53cd5ca29ffbb77bbef57773793487a619))
+* **sdk:** accept a caller idempotency key in createGeneration ([a532ac3](https://github.com/clickraft/cli/commit/a532ac338277a699f9504abb43cda95cf97365b8))
+* **sdk:** add the generation history and estimate contracts ([da4d161](https://github.com/clickraft/cli/commit/da4d16196d3ef4e2d017143c9ab800ea09f10ba5))
 
 # Changelog
 

package/README.md

@@ -45,6 +45,35 @@ clickraft generate create --model-slug nano-banana-2 \
 
 > **Note:** `--brand-model` only works with reference-supporting models (nano-banana-2 recommended).
 
+### Quality
+
+Use `--quality` to pick a model's quality tier. Lower tiers cost fewer credits. Valid values depend on the model (GPT Image 2.5 offers `low`, `medium`, `high`, `xhigh` and `max`). Omit it to use the model default. An unsupported value is rejected before any charge, and the error lists the values the model accepts:
+
+```bash
+clickraft generate create --model-slug gpt-image-2.5-flare \
+  --prompt "product on marble" \
+  --quality low
+```
+
+### Saving the result
+
+Use `--output` on `generate create`, `generate wait` or `generate get` to save a completed result to disk. Pass a directory (or a path ending in `/`) to get `<jobId>.<ext>` inside it, or a file path to write exactly there. JSON mode reports the absolute path as `data.savedPath`; a job that has not completed is not saved, and the CLI says so on stderr:
+
+```bash
+clickraft generate create --model-slug nano-banana-2 \
+  --prompt "product on marble" \
+  --output ./out/
+```
+
+### History and cost
+
+`generate list` shows your recent generations, newest first (`--limit`, `--status`, `--content-type`, `--cursor` for the next page). `generate estimate` takes the same flags as `generate create` and prints what it would cost and whether your account can run it now — nothing is created or charged:
+
+```bash
+clickraft generate list --limit 10
+clickraft generate estimate --model-slug nano-banana-pro --prompt "product on marble" --quality high
+```
+
 ### Products
 
 Create a product from images you have already uploaded, then generate against it:

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // ../sdk/dist/index.js
@@ -151,10 +151,10 @@ function parseProductCreateRequest(input) {
       { retryable: false, details: parsed.error.issues }
     );
   }
-  const request2 = parsed.data;
+  const request3 = parsed.data;
   const seen = /* @__PURE__ */ new Set();
   const duplicates = /* @__PURE__ */ new Set();
-  for (const img of request2.images) {
+  for (const img of request3.images) {
     if (seen.has(img.assetId)) duplicates.add(img.assetId);
     seen.add(img.assetId);
   }
@@ -165,7 +165,7 @@ function parseProductCreateRequest(input) {
       { retryable: false }
     );
   }
-  const bytes = Buffer.byteLength(JSON.stringify(request2), "utf8");
+  const bytes = Buffer.byteLength(JSON.stringify(request3), "utf8");
   if (bytes > MAX_PRODUCT_CREATE_BODY_BYTES) {
     throw new ApiError(
       "INPUT_INVALID_FORMAT",
@@ -173,7 +173,7 @@ function parseProductCreateRequest(input) {
       { retryable: false }
     );
   }
-  return request2;
+  return request3;
 }
 var TokenRowSchema = z4.object({
   id: z4.string().uuid(),
@@ -235,6 +235,10 @@ var GenerateCreateRequestSchema = z6.object({
       "resolution must match WxH (e.g. 1280x720), p-token (e.g. 720p), or K-token (e.g. 1K)"
     ).optional(),
     durationSeconds: z6.number().int().min(1).max(60).optional(),
+    // The model's quality tier (e.g. 'low' | 'medium' | 'high'). The valid set is
+    // per model, so it is checked server-side: an unoffered value returns 400
+    // INPUT_INVALID_FORMAT with the supported options in `details.allowed`.
+    quality: z6.string().min(1).max(40).optional(),
     width: z6.number().int().min(64).max(8192).optional(),
     height: z6.number().int().min(64).max(8192).optional(),
     providerParams: z6.record(z6.string(), z6.unknown()).optional()
@@ -280,6 +284,34 @@ var GenerationResultSchema = z6.object({
   startedAt: z6.string().nullable(),
   completedAt: z6.string().nullable()
 }).strict();
+var GenerationListItemSchema = z6.object({
+  jobId: z6.string().uuid(),
+  status: GenerationStatusSchema,
+  modelSlug: z6.string().nullable(),
+  contentType: z6.enum(["image", "video", "audio"]),
+  prompt: z6.string().nullable(),
+  resultUrl: z6.string().nullable(),
+  thumbnailUrl: z6.string().nullable(),
+  errorCode: z6.string().nullable(),
+  errorMessage: z6.string().nullable(),
+  creditsCharged: z6.number().int().nonnegative(),
+  creditsRefunded: z6.boolean(),
+  createdAt: z6.string(),
+  completedAt: z6.string().nullable()
+}).strict();
+var GenerationListResponseSchema = z6.object({
+  jobs: z6.array(GenerationListItemSchema),
+  cursor: z6.string().nullable(),
+  hasMore: z6.boolean()
+}).strict();
+var GenerateEstimateResponseSchema = z6.object({
+  modelSlug: z6.string(),
+  creditCost: z6.number().int().nonnegative(),
+  estimatedSeconds: z6.number().int().nonnegative().nullable(),
+  balance: z6.number().nullable(),
+  affordable: z6.boolean(),
+  blockedReason: z6.enum(["insufficient_credits", "feature_disabled", "subscription_required", "past_due"]).nullable()
+}).strict();
 var MAX_UPLOAD_SIZE_BYTES = 15 * 1024 * 1024;
 var UploadRequestSchema = z7.object({
   filename: z7.string().min(1).max(255),
@@ -532,10 +564,10 @@ async function sleep(delayMs, signal) {
   if (signal?.aborted) {
     throw signalToAbortError(signal);
   }
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve();
+      resolve2();
     }, delayMs);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1083,7 +1115,8 @@ async function createGeneration(params) {
     path: "/jobs",
     body: params.body,
     responseSchema: params.createSchema,
-    signal: params.signal
+    signal: params.signal,
+    idempotencyKey: params.idempotencyKey
   });
   if (!params.wait) {
     return params.projectCreated(created, params.modelSlug);
@@ -2184,8 +2217,7 @@ async function generateWait(opts) {
 
 // src/commands/generate/create.ts
 var PREFLIGHT_PLACEHOLDER_URL = "https://placeholder.invalid/pending-upload";
-async function generateCreate(opts) {
-  const client = opts.client ?? await buildGenerateClient(opts);
+async function prepareCreateBody(opts, client) {
   const preflightRefs = (opts.referenceImages ?? []).map(
     (v) => isUrlLike(v) ? v : PREFLIGHT_PLACEHOLDER_URL
   );
@@ -2201,7 +2233,11 @@ async function generateCreate(opts) {
     client,
     signal: opts.signal
   }))[0];
-  const body = buildRequestBody({ ...opts, referenceImages, startFrame });
+  return buildRequestBody({ ...opts, referenceImages, startFrame });
+}
+async function generateCreate(opts) {
+  const client = opts.client ?? await buildGenerateClient(opts);
+  const body = await prepareCreateBody(opts, client);
   return createGeneration({
     client,
     body,
@@ -2245,6 +2281,7 @@ function buildRequestBody(args) {
   if (args.aspectRatio !== void 0) input.aspectRatio = args.aspectRatio;
   if (args.resolution !== void 0) input.resolution = args.resolution;
   if (args.durationSeconds !== void 0) input.durationSeconds = args.durationSeconds;
+  if (args.quality !== void 0) input.quality = args.quality;
   if (args.brandModels !== void 0 && args.brandModels.length > 0) {
     input.providerParams = {
       brandModels: args.brandModels.map((spec) => {
@@ -2297,6 +2334,87 @@ function projectCreateToResult(response, modelSlug) {
   };
 }
 
+// src/commands/generate/download.ts
+import { createWriteStream } from "fs";
+import { mkdir as mkdir2, rename as rename2, rm as rm2, stat as stat3 } from "fs/promises";
+import { basename as basename2, dirname as dirname2, extname, join as join2, resolve, sep } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+import { request } from "undici";
+var DOWNLOAD_TIMEOUT_MS = 12e4;
+async function isDirectory(path) {
+  try {
+    return (await stat3(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function extensionOf(url) {
+  const ext = extname(new URL(url).pathname);
+  return /^\.[a-z0-9]{1,5}$/i.test(ext) ? ext.toLowerCase() : "";
+}
+async function resolveOutputPath(output, result) {
+  if (!result.resultUrl) {
+    throw new ApiError("INPUT_INVALID_FORMAT", "The job has no result to save.", {
+      retryable: false
+    });
+  }
+  const asDir = output.endsWith("/") || output.endsWith(sep) || await isDirectory(output);
+  return asDir ? resolve(output, `${result.jobId}${extensionOf(result.resultUrl)}`) : resolve(output);
+}
+async function downloadResult(result, output, options = {}) {
+  if (result.status !== "completed" || !result.resultUrl) {
+    throw new ApiError(
+      "INPUT_INVALID_FORMAT",
+      `Job ${result.jobId} is ${result.status}; only a completed job can be saved.`,
+      { retryable: false }
+    );
+  }
+  const url = result.resultUrl;
+  if (!url.startsWith("https://") && !url.startsWith("http://")) {
+    throw new ApiError("INPUT_INVALID_FORMAT", `Refusing to download a non-HTTP URL: ${url}`, {
+      retryable: false
+    });
+  }
+  const target = await resolveOutputPath(output, result);
+  await mkdir2(dirname2(target), { recursive: true });
+  const partial = join2(dirname2(target), `.${basename2(target)}.part`);
+  const signals = [AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)];
+  if (options.signal) signals.push(options.signal);
+  const res = await request(url, {
+    method: "GET",
+    signal: AbortSignal.any(signals),
+    dispatcher: options.dispatcher
+  });
+  if (res.statusCode !== 200) {
+    await res.body.dump();
+    throw new ApiError("NETWORK_ERROR", `Could not download the result (HTTP ${res.statusCode}).`, {
+      retryable: res.statusCode >= 500
+    });
+  }
+  try {
+    await pipeline(Readable.from(res.body), createWriteStream(partial));
+    await rename2(partial, target);
+  } catch (err) {
+    await rm2(partial, { force: true });
+    throw err;
+  }
+  return target;
+}
+
+// src/commands/generate/estimate.ts
+async function generateEstimate(opts) {
+  const client = opts.client ?? await buildGenerateClient(opts);
+  const body = await prepareCreateBody(opts, client);
+  return client.request({
+    method: "POST",
+    path: "/jobs/estimate",
+    body,
+    responseSchema: GenerateEstimateResponseSchema,
+    signal: opts.signal
+  });
+}
+
 // src/commands/generate/get.ts
 async function generateGet(opts) {
   const client = opts.client ?? await buildGenerateClient(opts);
@@ -2309,6 +2427,23 @@ async function generateGet(opts) {
   });
 }
 
+// src/commands/generate/list.ts
+async function generateList(opts) {
+  const client = opts.client ?? await buildGenerateClient(opts);
+  return client.request({
+    method: "GET",
+    path: "/jobs",
+    query: {
+      limit: opts.limit,
+      status: opts.status,
+      contentType: opts.contentType,
+      cursor: opts.cursor
+    },
+    responseSchema: GenerationListResponseSchema,
+    signal: opts.signal
+  });
+}
+
 // src/cli/args.ts
 var ArgError = class extends Error {
   constructor(message) {
@@ -2495,7 +2630,7 @@ function validateProductSpecs(specs) {
 
 // src/auth/device-flow.ts
 import { setTimeout as delay } from "timers/promises";
-import { request } from "undici";
+import { request as request2 } from "undici";
 var GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 var FORM_CONTENT_TYPE = "application/x-www-form-urlencoded";
 async function runDeviceFlow(opts) {
@@ -2610,7 +2745,7 @@ async function attemptDeviceAuthorization(opts, scope) {
   }
   let resp;
   try {
-    resp = await request(`${opts.apiBaseUrl}/oauth/device-authorization`, {
+    resp = await request2(`${opts.apiBaseUrl}/oauth/device-authorization`, {
       method: "POST",
       headers,
       body,
@@ -2692,7 +2827,7 @@ async function pollToken(args) {
   }
   let resp;
   try {
-    resp = await request(`${args.apiBaseUrl}/oauth/token`, {
+    resp = await request2(`${args.apiBaseUrl}/oauth/token`, {
       method: "POST",
       headers,
       body,
@@ -4333,6 +4468,8 @@ function renderRootHelp(version) {
     "  generate create         Submit a generation job and wait for completion",
     "  generate wait           Wait for an existing job to reach a terminal state",
     "  generate get            Fetch the current state of a job",
+    "  generate list           List your recent generations, newest first",
+    "  generate estimate       Price a generation without running it",
     "  jobs wait               Alias of `generate wait`",
     "  workflow create         Create a new empty workflow",
     "  workflow list           List workflows in your organization",
@@ -4604,6 +4741,8 @@ function renderCommandHelp(command) {
         "  create  Submit a generation job (waits for completion by default)",
         "  wait    Long-poll an existing job until terminal",
         "  get     Fetch the current state of a job (no polling)",
+        "  list      List your recent generations, newest first",
+        "  estimate  Price a generation without running it (same flags as create)",
         ""
       ].join("\n");
     case "generate create":
@@ -4627,10 +4766,13 @@ function renderCommandHelp(command) {
         "  --aspect-ratio <a:b>      e.g. 16:9",
         "  --resolution <size>       e.g. 1024x768, 720p, 1K",
         "  --duration-seconds <n>    For video/audio models (1-60)",
+        "  --quality <tier>          e.g. low, medium, high (valid values depend on the model)",
         "  --workflow-id <uuid>      Attach to an existing workflow",
         "  --node-id <id>            Attach to a specific node",
         "  --no-wait, --async        Return immediately with the jobId",
         "  --timeout <seconds>       Override the 120s default wait",
+        "  --output <path>           Save the completed result to a file, or into a",
+        "                             directory as <jobId>.<ext>",
         "  --profile <name>          Credentials profile name",
         "  --api-base-url <url>      Override the API base URL",
         "  --token <token>           Override the access token",
@@ -4647,6 +4789,42 @@ function renderCommandHelp(command) {
         "",
         "Options:",
         "  --timeout <seconds>   Overall wait deadline (default: 120)",
+        "  --output <path>       Save the completed result (file, or directory \u2192 <jobId>.<ext>)",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "generate list":
+      return [
+        "Usage: clickraft generate list [options]",
+        "",
+        "Lists your recent generations in the organization, newest first.",
+        "",
+        "Options:",
+        "  --limit <n>             Results per page (1-50, default: 20)",
+        "  --status <status>       queued, processing, uploading, completed, failed, cancelled",
+        "  --content-type <type>   image, video, or audio",
+        "  --cursor <token>        Pagination cursor from a previous response",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "generate estimate":
+      return [
+        "Usage: clickraft generate estimate [prompt] --model-slug <slug> [options]",
+        "",
+        "Prices exactly what `generate create` with the same flags would charge, and",
+        "says whether the account can run it now. Nothing is created or charged.",
+        "Accepts the same generation flags as `generate create` (--prompt,",
+        "--model-slug, --reference-image, --start-frame, --aspect-ratio, --resolution,",
+        "--duration-seconds, --quality, --brand-model, --product, --workflow-id,",
+        "--node-id). Local reference paths are uploaded first, as with create.",
+        "",
+        "Options:",
         "  --profile <name>",
         "  --api-base-url <url>",
         "  --token <token>",
@@ -4660,6 +4838,7 @@ function renderCommandHelp(command) {
         "Fetches the current state of a generation job without polling.",
         "",
         "Options:",
+        "  --output <path>       Save the completed result (file, or directory \u2192 <jobId>.<ext>)",
         "  --profile <name>",
         "  --api-base-url <url>",
         "  --token <token>",
@@ -4791,6 +4970,8 @@ function matchNewCommand(argv) {
     if (sub === "create") return { kind: "cmd", path: "generate.create", verbTokenCount: 2 };
     if (sub === "wait") return { kind: "cmd", path: "generate.wait", verbTokenCount: 2 };
     if (sub === "get") return { kind: "cmd", path: "generate.get", verbTokenCount: 2 };
+    if (sub === "list") return { kind: "cmd", path: "generate.list", verbTokenCount: 2 };
+    if (sub === "estimate") return { kind: "cmd", path: "generate.estimate", verbTokenCount: 2 };
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "generate" };
     return { kind: "unknown-sub", verb: "generate", sub };
   }
@@ -4883,6 +5064,10 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runGenerateWait(argvAfterVerb, ctx, rc);
       case "generate.get":
         return await runGenerateGet(argvAfterVerb, ctx, rc);
+      case "generate.list":
+        return await runGenerateList(argvAfterVerb, ctx, rc);
+      case "generate.estimate":
+        return await runGenerateEstimate(argvAfterVerb, ctx, rc);
       case "jobs.wait":
         return await runJobsWait(argvAfterVerb, ctx, rc);
       case "upload":
@@ -4945,9 +5130,11 @@ async function runGenerateCreate(argv, ctx, rc) {
       "aspect-ratio",
       "resolution",
       "duration-seconds",
+      "quality",
       "workflow-id",
       "node-id",
-      "timeout"
+      "timeout",
+      "output"
     ],
     boolean: [...COMMON_RICH_BOOL_FLAGS, "wait", "async"],
     array: ["reference-image", "brand-model", "product"]
@@ -4968,6 +5155,7 @@ async function runGenerateCreate(argv, ctx, rc) {
     aspectRatio: parsed.string["aspect-ratio"],
     resolution: parsed.string.resolution,
     durationSeconds: optionalInt(parsed.string["duration-seconds"], "duration-seconds"),
+    quality: parsed.string.quality,
     brandModels,
     products,
     workflowId: parsed.string["workflow-id"],
@@ -4979,12 +5167,12 @@ async function runGenerateCreate(argv, ctx, rc) {
     token: parsed.string.token,
     signal: rc.signal
   });
-  emitJob(result, ctx, rc);
+  await emitJob(result, ctx, rc, parsed.string.output);
   return exitCodeForResult(result);
 }
 async function runGenerateWait(argv, ctx, rc) {
   const parsed = parseArgs(argv, {
-    string: [...COMMON_RICH_STRING_FLAGS, "timeout"],
+    string: [...COMMON_RICH_STRING_FLAGS, "timeout", "output"],
     boolean: [...COMMON_RICH_BOOL_FLAGS]
   });
   const jobId = parsed.positional[0];
@@ -4997,12 +5185,12 @@ async function runGenerateWait(argv, ctx, rc) {
     token: parsed.string.token,
     signal: rc.signal
   });
-  emitJob(result, ctx, rc);
+  await emitJob(result, ctx, rc, parsed.string.output);
   return exitCodeForResult(result);
 }
 async function runGenerateGet(argv, ctx, rc) {
   const parsed = parseArgs(argv, {
-    string: [...COMMON_RICH_STRING_FLAGS],
+    string: [...COMMON_RICH_STRING_FLAGS, "output"],
     boolean: [...COMMON_RICH_BOOL_FLAGS]
   });
   const jobId = parsed.positional[0];
@@ -5014,12 +5202,84 @@ async function runGenerateGet(argv, ctx, rc) {
     token: parsed.string.token,
     signal: rc.signal
   });
-  emitJob(result, ctx, rc);
+  await emitJob(result, ctx, rc, parsed.string.output);
   return exitCodeForResult(result);
 }
+async function runGenerateList(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "limit", "status", "content-type", "cursor"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS]
+  });
+  const page = await generateList({
+    limit: optionalInt(parsed.string.limit, "limit"),
+    status: parsed.string.status,
+    contentType: parsed.string["content-type"],
+    cursor: parsed.string.cursor,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(page, ctx)) + "\n");
+    return 0;
+  }
+  rc.stdout.write(renderGenerationList(page) + "\n");
+  return 0;
+}
+async function runGenerateEstimate(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [
+      ...COMMON_RICH_STRING_FLAGS,
+      "prompt",
+      "model-slug",
+      "start-frame",
+      "aspect-ratio",
+      "resolution",
+      "duration-seconds",
+      "quality",
+      "workflow-id",
+      "node-id"
+    ],
+    boolean: [...COMMON_RICH_BOOL_FLAGS],
+    array: ["reference-image", "brand-model", "product"]
+  });
+  const modelSlug = parsed.string["model-slug"];
+  if (!modelSlug) throw new ArgError("--model-slug is required.");
+  const rawBrandModels = parsed.array["brand-model"] ?? [];
+  const brandModels = rawBrandModels.length > 0 ? rawBrandModels.map(parseBrandModelSpec) : void 0;
+  if (brandModels) validateBrandModelSpecs(brandModels);
+  const rawProducts = parsed.array["product"] ?? [];
+  const products = rawProducts.length > 0 ? rawProducts.map(parseProductSpec) : void 0;
+  if (products) validateProductSpecs(products);
+  const estimate = await generateEstimate({
+    prompt: parsed.string.prompt ?? parsed.positional[0],
+    modelSlug,
+    referenceImages: parsed.array["reference-image"],
+    startFrame: parsed.string["start-frame"],
+    aspectRatio: parsed.string["aspect-ratio"],
+    resolution: parsed.string.resolution,
+    durationSeconds: optionalInt(parsed.string["duration-seconds"], "duration-seconds"),
+    quality: parsed.string.quality,
+    brandModels,
+    products,
+    workflowId: parsed.string["workflow-id"],
+    nodeId: parsed.string["node-id"],
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(estimate, ctx)) + "\n");
+    return 0;
+  }
+  rc.stdout.write(renderEstimate(estimate) + "\n");
+  return 0;
+}
 async function runJobsWait(argv, ctx, rc) {
   const parsed = parseArgs(argv, {
-    string: [...COMMON_RICH_STRING_FLAGS, "timeout"],
+    string: [...COMMON_RICH_STRING_FLAGS, "timeout", "output"],
     boolean: [...COMMON_RICH_BOOL_FLAGS]
   });
   const jobId = parsed.positional[0];
@@ -5032,7 +5292,7 @@ async function runJobsWait(argv, ctx, rc) {
     token: parsed.string.token,
     signal: rc.signal
   });
-  emitJob(result, ctx, rc);
+  await emitJob(result, ctx, rc, parsed.string.output);
   return exitCodeForResult(result);
 }
 async function runUploadCmd(argv, ctx, rc) {
@@ -5053,15 +5313,27 @@ async function runUploadCmd(argv, ctx, rc) {
   emitUpload(result, ctx, rc);
   return 0;
 }
-function emitJob(result, ctx, rc) {
+async function emitJob(result, ctx, rc, output) {
   if (rc.signal?.aborted) {
     throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
   }
+  let savedPath;
+  if (output !== void 0) {
+    if (result.status === "completed" && result.resultUrl) {
+      savedPath = await downloadResult(result, output, { signal: rc.signal });
+    } else {
+      rc.stderr.write(`Not saved: job ${result.jobId} is ${result.status}.
+`);
+    }
+  }
   if (rc.jsonMode) {
-    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    const data = savedPath ? { ...result, savedPath } : result;
+    rc.stdout.write(JSON.stringify(wrapSuccess(data, ctx)) + "\n");
     return;
   }
   rc.stdout.write(renderGenerationResult(result) + "\n");
+  if (savedPath) rc.stdout.write(`Saved: ${savedPath}
+`);
 }
 function emitUpload(result, ctx, rc) {
   if (rc.signal?.aborted) {
@@ -5084,6 +5356,38 @@ function renderGenerationResult(r) {
   }
   return lines.join("\n");
 }
+function renderGenerationList(page) {
+  if (page.jobs.length === 0) return "No generations.";
+  const headers = ["JOB ID", "STATUS", "MODEL", "CREATED", "CREDITS", "PROMPT"];
+  const PROMPT_WIDTH = 48;
+  const data = page.jobs.map((job) => {
+    const prompt = (job.prompt ?? "\u2014").replace(/\s+/g, " ");
+    return [
+      job.jobId,
+      job.status,
+      job.modelSlug ?? "\u2014",
+      job.createdAt.slice(0, 16),
+      String(job.creditsCharged),
+      prompt.length > PROMPT_WIDTH ? `${prompt.slice(0, PROMPT_WIDTH - 1)}\u2026` : prompt
+    ];
+  });
+  const widths = headers.map(
+    (header, i) => Math.max(header.length, ...data.map((cells) => cells[i].length))
+  );
+  const padRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  const lines = [padRow(headers), ...data.map(padRow)];
+  if (page.hasMore && page.cursor) lines.push("", `More: --cursor ${page.cursor}`);
+  return lines.join("\n");
+}
+function renderEstimate(e) {
+  const lines = [`Model: ${e.modelSlug}`, `Estimated cost: ${e.creditCost} credits`];
+  if (e.estimatedSeconds !== null) lines.push(`Typical duration: ~${e.estimatedSeconds}s`);
+  if (e.balance !== null) lines.push(`Balance: ${e.balance} credits`);
+  lines.push(
+    e.affordable ? "Can run now: yes" : `Can run now: no (${e.blockedReason?.replace(/_/g, " ") ?? "blocked"})`
+  );
+  return lines.join("\n");
+}
 function renderUploadResult(r) {
   return [
     `Uploaded: ${r.publicUrl}`,
@@ -5614,8 +5918,8 @@ async function readJsonFile(filePath) {
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = dirname2(__filename2);
-var pkg = JSON.parse(readFileSync(join2(__dirname2, "..", "package.json"), "utf8"));
+var __dirname2 = dirname3(__filename2);
+var pkg = JSON.parse(readFileSync(join3(__dirname2, "..", "package.json"), "utf8"));
 async function run(args, signal) {
   return dispatch({
     argv: args,