@clickraft/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,9 @@
-## [0.3.0](https://github.com/clickraft/cli/compare/v0.2.0...v0.3.0) (2026-05-24)
+## [0.4.0](https://github.com/clickraft/cli/compare/v0.3.0...v0.4.0) (2026-05-24)
 
 ### Features
 
-* **commands:** add template list, get, and find commands ([b2f5c5c](https://github.com/clickraft/cli/commit/b2f5c5c2e501f8ea5c6586476d121b97ce97f4ba))
+* **errors:** add brand model error codes and surface error details ([98ee9f4](https://github.com/clickraft/cli/commit/98ee9f415a85cf31e38152092655accbe9acef1c))
+* **generate:** make --brand-model repeatable with pose support ([872209c](https://github.com/clickraft/cli/commit/872209cfab22f7cd31e2a7655fa072c437a78351))
 
 # Changelog
 

package/README.md

@@ -24,6 +24,25 @@ clickraft template get <template-id>
 clickraft template find "coffee brand"
 ```
 
+### Brand Model references
+
+Use `--brand-model` to attach trained brand models to a generation. The flag is repeatable (max 3) and accepts an optional pose:
+
+```bash
+# Single brand model, primary image
+clickraft generate create --model-slug nano-banana-2 \
+  --prompt "product on marble" \
+  --brand-model a2438521-abcd-4000-8000-000000000001
+
+# Two brand models with pose selection
+clickraft generate create --model-slug nano-banana-2 \
+  --prompt "lifestyle shot" \
+  --brand-model a2438521-abcd-4000-8000-000000000001:front \
+  --brand-model b3549632-bcde-4000-8000-000000000002:3/4-right
+```
+
+> **Note:** `--brand-model` only works with reference-supporting models (nano-banana-2 recommended).
+
 Full documentation: [docs.clickraft.ai/cli](https://docs.clickraft.ai/cli) _(coming soon)_
 
 ## Connecting to staging

package/dist/cli.js

@@ -285,6 +285,55 @@ var EXIT_CODE_MAP = {
     retryable: false,
     hint: "No such profile. Use `clickraft auth profiles` to list available profiles."
   },
+  // --- 8 brand model resolution codes -----------------------------------------
+  BRAND_MODEL_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "No brand model with that ID. Run `clickraft brand-model list`."
+  },
+  BRAND_MODEL_NOT_A_MODEL: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "The specified asset is not a brand model."
+  },
+  BRAND_MODEL_NOT_ACTIVE: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Brand model is not active. Check its status in the dashboard."
+  },
+  BRAND_MODEL_NO_REFERENCES: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Brand model has no reference images. Upload references first."
+  },
+  BRAND_MODEL_POSE_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Requested pose not found. Valid: front, 3/4-right, right, left, 3/4-left, back, approved."
+  },
+  BRAND_MODEL_DUPLICATE_ID: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Same brand model ID appears more than once."
+  },
+  MODEL_DOES_NOT_SUPPORT_REFERENCES: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "This model does not support brand model references."
+  },
+  REFERENCE_LIMIT_EXCEEDED: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Too many reference images. Check model limits."
+  },
   // --- 4 CLI-synthetic codes --------------------------------------------------
   NETWORK_ERROR: {
     exitCode: 6,
@@ -697,7 +746,8 @@ function apiErrorFromServerBody(args) {
     requestId: error.correlationId ?? args.requestId,
     retryable,
     retryAfterMs,
-    redactedBody: args.redactedBody
+    redactedBody: args.redactedBody,
+    details: error.details
   });
 }
 function parseRetryAfterHeader(headerValue) {
@@ -826,7 +876,8 @@ function errorToEnvelopePayload(err) {
       message: err.message,
       retryable: err.meta.retryable,
       retryAfterMs: err.meta.retryAfterMs,
-      requestId: err.meta.requestId
+      requestId: err.meta.requestId,
+      details: err.meta.details
     });
   }
   if (err instanceof AuthError || err instanceof CredentialsError) {
@@ -855,6 +906,7 @@ function buildPayload(args) {
   if (typeof args.retryAfterMs === "number") payload.retry_after_ms = args.retryAfterMs;
   if (args.requestId) payload.request_id = args.requestId;
   if (mapping?.hint) payload.hint = mapping.hint;
+  if (args.details != null) payload.details = args.details;
   return payload;
 }
 
@@ -1736,7 +1788,15 @@ 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.brandModel !== void 0) input.providerParams = { brandModelId: args.brandModel };
+  if (args.brandModels !== void 0 && args.brandModels.length > 0) {
+    input.providerParams = {
+      brandModels: args.brandModels.map((spec) => {
+        const entry = { id: spec.id };
+        if (spec.imageType) entry.imageType = spec.imageType;
+        return entry;
+      })
+    };
+  }
   const body = {
     modelSlug: args.modelSlug,
     input
@@ -1773,6 +1833,152 @@ function projectCreateToResult(response, modelSlug) {
   };
 }
 
+// src/cli/args.ts
+var ArgError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArgError";
+  }
+};
+function parseArgs(argv, spec) {
+  const result = {
+    positional: [],
+    string: {},
+    boolean: {},
+    array: {}
+  };
+  const stringFlags = new Set(spec.string ?? []);
+  const booleanFlags = new Set(spec.boolean ?? []);
+  const arrayFlags = new Set(spec.array ?? []);
+  const aliases = spec.aliases ?? {};
+  let i = 0;
+  let stopFlags = false;
+  while (i < argv.length) {
+    const raw = argv[i];
+    if (raw === void 0) {
+      i += 1;
+      continue;
+    }
+    if (stopFlags) {
+      result.positional.push(raw);
+      i += 1;
+      continue;
+    }
+    if (raw === "--") {
+      stopFlags = true;
+      i += 1;
+      continue;
+    }
+    if (!raw.startsWith("--")) {
+      result.positional.push(raw);
+      i += 1;
+      continue;
+    }
+    const eqIdx = raw.indexOf("=");
+    const flagToken = eqIdx >= 0 ? raw.slice(2, eqIdx) : raw.slice(2);
+    const inlineValue = eqIdx >= 0 ? raw.slice(eqIdx + 1) : void 0;
+    const canonical = resolveCanonical(flagToken, { booleanFlags, aliases });
+    if (booleanFlags.has(canonical)) {
+      if (inlineValue !== void 0) {
+        result.boolean[canonical] = parseBool(inlineValue);
+      } else if (flagToken.startsWith("no-") && booleanFlags.has(flagToken.slice(3))) {
+        result.boolean[flagToken.slice(3)] = false;
+      } else {
+        result.boolean[canonical] = true;
+      }
+      i += 1;
+      continue;
+    }
+    if (stringFlags.has(canonical) || arrayFlags.has(canonical)) {
+      let value;
+      if (inlineValue !== void 0) {
+        value = inlineValue;
+      } else {
+        const next = argv[i + 1];
+        if (next === void 0 || next.startsWith("--")) {
+          throw new ArgError(`Flag --${canonical} requires a value.`);
+        }
+        value = next;
+        i += 1;
+      }
+      if (arrayFlags.has(canonical)) {
+        const existing = result.array[canonical] ?? [];
+        existing.push(value);
+        result.array[canonical] = existing;
+      } else {
+        result.string[canonical] = value;
+      }
+      i += 1;
+      continue;
+    }
+    throw new ArgError(`Unknown flag --${flagToken}`);
+  }
+  return result;
+}
+function resolveCanonical(flagToken, ctx) {
+  if (ctx.aliases[flagToken]) return ctx.aliases[flagToken];
+  if (flagToken.startsWith("no-") && ctx.booleanFlags.has(flagToken.slice(3))) {
+    return flagToken.slice(3);
+  }
+  return flagToken;
+}
+function parseBool(value) {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  throw new ArgError(`Expected boolean value (true/false), got "${value}".`);
+}
+
+// src/commands/generate/parse-brand-model-spec.ts
+var VALID_POSES = [
+  "front",
+  "3/4-right",
+  "right",
+  "left",
+  "3/4-left",
+  "back",
+  "approved"
+];
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function parseBrandModelSpec(raw) {
+  if (!raw) throw new ArgError("--brand-model value cannot be empty.");
+  const colonIdx = raw.indexOf(":");
+  const uuid = colonIdx >= 0 ? raw.slice(0, colonIdx) : raw;
+  const poseRaw = colonIdx >= 0 ? raw.slice(colonIdx + 1) : void 0;
+  if (!UUID_RE.test(uuid)) {
+    throw new ArgError(
+      `Invalid brand model ID: '${uuid}'. Expected a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).`
+    );
+  }
+  if (poseRaw !== void 0) {
+    if (!poseRaw) {
+      throw new ArgError(
+        `Empty pose for brand model ${uuid}. Valid poses: ${VALID_POSES.join(", ")}.`
+      );
+    }
+    if (!VALID_POSES.includes(poseRaw)) {
+      throw new ArgError(
+        `Unknown pose '${poseRaw}' for brand model ${uuid}. Valid poses: ${VALID_POSES.join(", ")}.`
+      );
+    }
+    return { id: uuid.toLowerCase(), imageType: poseRaw };
+  }
+  return { id: uuid.toLowerCase() };
+}
+function validateBrandModelSpecs(specs) {
+  if (specs.length > 3) {
+    throw new ArgError(`Too many --brand-model flags (${specs.length}). Maximum is 3.`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    if (seen.has(spec.id)) {
+      throw new ArgError(
+        `Duplicate brand model ID: ${spec.id}. Each --brand-model must reference a different model.`
+      );
+    }
+    seen.add(spec.id);
+  }
+}
+
 // src/auth/device-flow.ts
 import { setTimeout as delay } from "timers/promises";
 import { request } from "undici";
@@ -2443,23 +2649,33 @@ async function listTokens(options) {
 var FALLBACK_HINT = "See `clickraft --help` or contact support.";
 function formatHumanError(err) {
   const view = errorToView(err);
-  return [
+  const lines = [
     `Error: ${view.message}`,
     `Code: ${view.code}`,
     `Try: ${view.hint}`,
     `Request ID: ${view.requestId ?? "n/a"}`
-  ].join("\n");
+  ];
+  if (view.details) lines.push(`Details: ${view.details}`);
+  return lines.join("\n");
 }
 function formatJsonError(err, ctx) {
   return JSON.stringify(wrapError(err, ctx));
 }
+function formatDetails(details) {
+  if (details == null) return void 0;
+  if (typeof details !== "object") return String(details);
+  const entries = Object.entries(details);
+  if (entries.length === 0) return void 0;
+  return entries.map(([k, v]) => `${k}=${v}`).join(", ");
+}
 function errorToView(err) {
   if (err instanceof ApiError) {
     return {
       code: toEnvelopeCode(err.code),
       message: err.message,
       hint: EXIT_CODE_MAP[err.code]?.hint ?? FALLBACK_HINT,
-      requestId: err.meta.requestId
+      requestId: err.meta.requestId,
+      details: formatDetails(err.meta.details)
     };
   }
   if (err instanceof AuthError || err instanceof CredentialsError) {
@@ -2477,101 +2693,6 @@ function errorToView(err) {
   };
 }
 
-// src/cli/args.ts
-var ArgError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ArgError";
-  }
-};
-function parseArgs(argv, spec) {
-  const result = {
-    positional: [],
-    string: {},
-    boolean: {},
-    array: {}
-  };
-  const stringFlags = new Set(spec.string ?? []);
-  const booleanFlags = new Set(spec.boolean ?? []);
-  const arrayFlags = new Set(spec.array ?? []);
-  const aliases = spec.aliases ?? {};
-  let i = 0;
-  let stopFlags = false;
-  while (i < argv.length) {
-    const raw = argv[i];
-    if (raw === void 0) {
-      i += 1;
-      continue;
-    }
-    if (stopFlags) {
-      result.positional.push(raw);
-      i += 1;
-      continue;
-    }
-    if (raw === "--") {
-      stopFlags = true;
-      i += 1;
-      continue;
-    }
-    if (!raw.startsWith("--")) {
-      result.positional.push(raw);
-      i += 1;
-      continue;
-    }
-    const eqIdx = raw.indexOf("=");
-    const flagToken = eqIdx >= 0 ? raw.slice(2, eqIdx) : raw.slice(2);
-    const inlineValue = eqIdx >= 0 ? raw.slice(eqIdx + 1) : void 0;
-    const canonical = resolveCanonical(flagToken, { booleanFlags, aliases });
-    if (booleanFlags.has(canonical)) {
-      if (inlineValue !== void 0) {
-        result.boolean[canonical] = parseBool(inlineValue);
-      } else if (flagToken.startsWith("no-") && booleanFlags.has(flagToken.slice(3))) {
-        result.boolean[flagToken.slice(3)] = false;
-      } else {
-        result.boolean[canonical] = true;
-      }
-      i += 1;
-      continue;
-    }
-    if (stringFlags.has(canonical) || arrayFlags.has(canonical)) {
-      let value;
-      if (inlineValue !== void 0) {
-        value = inlineValue;
-      } else {
-        const next = argv[i + 1];
-        if (next === void 0 || next.startsWith("--")) {
-          throw new ArgError(`Flag --${canonical} requires a value.`);
-        }
-        value = next;
-        i += 1;
-      }
-      if (arrayFlags.has(canonical)) {
-        const existing = result.array[canonical] ?? [];
-        existing.push(value);
-        result.array[canonical] = existing;
-      } else {
-        result.string[canonical] = value;
-      }
-      i += 1;
-      continue;
-    }
-    throw new ArgError(`Unknown flag --${flagToken}`);
-  }
-  return result;
-}
-function resolveCanonical(flagToken, ctx) {
-  if (ctx.aliases[flagToken]) return ctx.aliases[flagToken];
-  if (flagToken.startsWith("no-") && ctx.booleanFlags.has(flagToken.slice(3))) {
-    return flagToken.slice(3);
-  }
-  return flagToken;
-}
-function parseBool(value) {
-  if (value === "true" || value === "1") return true;
-  if (value === "false" || value === "0") return false;
-  throw new ArgError(`Expected boolean value (true/false), got "${value}".`);
-}
-
 // src/cli/parse-args.ts
 var SHORT_ALIASES = {
   h: "help",
@@ -3256,7 +3377,9 @@ function renderCommandHelp(command) {
         "Options:",
         "  --prompt <text>           Text prompt (or pass as the positional argument)",
         "  --model-slug <slug>       Required model identifier",
-        "  --brand-model <id>        Optional Brand Model reference",
+        "  --brand-model <spec>      Brand Model reference (repeatable, max 3)",
+        "                             Format: <uuid> or <uuid>:<pose>",
+        "                             Poses: front, 3/4-right, right, left, 3/4-left, back, approved",
         "  --reference-image <v>     URL or local path (repeatable, max 8)",
         "  --aspect-ratio <a:b>      e.g. 16:9",
         "  --resolution <WxH>        e.g. 1024x768",
@@ -3451,7 +3574,6 @@ async function runGenerateCreate(argv, ctx, rc) {
       ...COMMON_RICH_STRING_FLAGS,
       "prompt",
       "model-slug",
-      "brand-model",
       "aspect-ratio",
       "resolution",
       "duration-seconds",
@@ -3460,10 +3582,13 @@ async function runGenerateCreate(argv, ctx, rc) {
       "timeout"
     ],
     boolean: [...COMMON_RICH_BOOL_FLAGS, "wait", "async"],
-    array: ["reference-image"]
+    array: ["reference-image", "brand-model"]
   });
   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 result = await generateCreate({
     prompt: parsed.string.prompt ?? parsed.positional[0],
     modelSlug,
@@ -3471,7 +3596,7 @@ async function runGenerateCreate(argv, ctx, rc) {
     aspectRatio: parsed.string["aspect-ratio"],
     resolution: parsed.string.resolution,
     durationSeconds: optionalInt(parsed.string["duration-seconds"], "duration-seconds"),
-    brandModel: parsed.string["brand-model"],
+    brandModels,
     workflowId: parsed.string["workflow-id"],
     nodeId: parsed.string["node-id"],
     wait: computeWaitFlag(parsed),