@clickraft/cli 0.3.0 → 0.5.0

package/dist/index.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";
@@ -2235,6 +2441,77 @@ function formatRevokeFailure(err, token) {
   return `warning: server-side revoke failed (${reason}). Local profile removed; token ${redactTokenLikeValue(token)} remains server-valid until expiry.`;
 }
 
+// src/schemas/models.ts
+import { z as z8 } from "zod";
+var ModelSummarySchema = z8.object({
+  id: z8.string().uuid(),
+  slug: z8.string(),
+  displayName: z8.string(),
+  description: z8.string().nullable(),
+  shortDescription: z8.string().nullable(),
+  providerSlug: z8.string(),
+  providerName: z8.string(),
+  modelType: z8.string(),
+  category: z8.string(),
+  costTier: z8.string(),
+  creditCost: z8.number(),
+  pricingStrategy: z8.string(),
+  estimatedSeconds: z8.object({
+    typical: z8.number(),
+    range: z8.array(z8.number())
+  }).passthrough().nullable(),
+  status: z8.string(),
+  modalities: z8.object({
+    input: z8.array(z8.string()),
+    output: z8.array(z8.string())
+  }).passthrough().nullable(),
+  bestFor: z8.array(z8.string()),
+  badges: z8.array(z8.string()),
+  isFeatured: z8.boolean(),
+  isDefault: z8.boolean(),
+  docsUrl: z8.string().nullable(),
+  llmContext: z8.string().nullable(),
+  constraints: z8.record(z8.unknown()).nullable(),
+  modelFamily: z8.string().nullable(),
+  isFamilyPrimary: z8.boolean().nullable()
+}).strict();
+var ModelsListResponseSchema = z8.object({
+  models: z8.array(ModelSummarySchema)
+}).strict();
+
+// src/commands/models/internal.ts
+async function buildModelClient(opts) {
+  const cfg = await loadConfig({
+    flagProfile: opts.profile,
+    flagApiBaseUrl: opts.apiBaseUrl,
+    flagToken: opts.token
+  });
+  return new ApiClient({
+    apiBaseUrl: cfg.apiBaseUrl,
+    accessToken: cfg.accessToken,
+    signal: opts.signal,
+    cloudflareAccess: cfg.cloudflareAccess
+  });
+}
+
+// src/commands/models/list.ts
+async function listModels(opts) {
+  const client = opts.client ?? await buildModelClient(opts);
+  const data = await client.request({
+    method: "GET",
+    path: "/models",
+    query: {
+      category: opts.category,
+      tier: opts.tier,
+      type: opts.type,
+      featured: opts.featured !== void 0 ? String(opts.featured) : void 0
+    },
+    responseSchema: ModelsListResponseSchema,
+    signal: opts.signal
+  });
+  return data;
+}
+
 // src/telemetry/detect.ts
 var AGENT_SIGNALS = [
   { envVar: "CLAUDE_CODE_SESSION_ID", agent: "claude-code" },
@@ -2325,33 +2602,33 @@ async function buildTemplateClient(opts) {
 }
 
 // src/schemas/templates.ts
-import { z as z8 } from "zod";
-var DeclaredParamSchema = z8.object({
-  name: z8.string(),
-  type: z8.string(),
-  required: z8.boolean(),
-  defaultValue: z8.string().nullable().optional(),
-  enumValues: z8.array(z8.string()).nullable().optional(),
-  description: z8.string().nullable().optional()
+import { z as z9 } from "zod";
+var DeclaredParamSchema = z9.object({
+  name: z9.string(),
+  type: z9.string(),
+  required: z9.boolean(),
+  defaultValue: z9.string().nullable().optional(),
+  enumValues: z9.array(z9.string()).nullable().optional(),
+  description: z9.string().nullable().optional()
 }).strict();
-var TemplateSummarySchema = z8.object({
-  id: z8.string().uuid(),
-  source: z8.enum(["own", "system"]),
-  name: z8.string(),
-  description: z8.string().nullable(),
-  category: z8.string().nullable(),
-  thumbnailUrl: z8.string().nullable(),
-  tags: z8.array(z8.string()),
-  createdAt: z8.string()
+var TemplateSummarySchema = z9.object({
+  id: z9.string().uuid(),
+  source: z9.enum(["own", "system"]),
+  name: z9.string(),
+  description: z9.string().nullable(),
+  category: z9.string().nullable(),
+  thumbnailUrl: z9.string().nullable(),
+  tags: z9.array(z9.string()),
+  createdAt: z9.string()
 }).strict();
 var TemplateDetailSchema = TemplateSummarySchema.extend({
-  declaredParams: z8.array(DeclaredParamSchema),
-  timesUsed: z8.number()
+  declaredParams: z9.array(DeclaredParamSchema),
+  timesUsed: z9.number()
 }).strict();
-var TemplatesListResponseSchema = z8.object({
-  templates: z8.array(TemplateSummarySchema),
-  cursor: z8.string().nullable(),
-  hasMore: z8.boolean()
+var TemplatesListResponseSchema = z9.object({
+  templates: z9.array(TemplateSummarySchema),
+  cursor: z9.string().nullable(),
+  hasMore: z9.boolean()
 }).strict();
 
 // src/commands/template/list.ts
@@ -2401,20 +2678,20 @@ async function getTemplate(opts) {
 }
 
 // src/commands/tokens/list.ts
-import { z as z9 } from "zod";
-var TokenRowSchema = z9.object({
-  id: z9.string().uuid(),
-  organizationId: z9.string().uuid(),
-  userId: z9.string().uuid(),
-  clientId: z9.string().nullable(),
-  tokenPrefix: z9.string(),
-  name: z9.string().nullable(),
-  scopes: z9.array(z9.string()),
-  lastUsedAt: z9.string().nullable(),
-  expiresAt: z9.string(),
-  createdAt: z9.string()
+import { z as z10 } from "zod";
+var TokenRowSchema = z10.object({
+  id: z10.string().uuid(),
+  organizationId: z10.string().uuid(),
+  userId: z10.string().uuid(),
+  clientId: z10.string().nullable(),
+  tokenPrefix: z10.string(),
+  name: z10.string().nullable(),
+  scopes: z10.array(z10.string()),
+  lastUsedAt: z10.string().nullable(),
+  expiresAt: z10.string(),
+  createdAt: z10.string()
 }).strict();
-var TokensListResponseSchema = z9.array(TokenRowSchema);
+var TokensListResponseSchema = z10.array(TokenRowSchema);
 async function listTokens(options) {
   const config = await loadConfig({
     flagProfile: options.profile,
@@ -2443,23 +2720,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 +2764,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",
@@ -2867,6 +3059,72 @@ function renderTemplateDetail(detail, out) {
   }
   out.write(lines.join("\n") + "\n");
 }
+var TIER_ORDER = { premium: 0, pro: 1, standard: 2 };
+function renderModelsList(result, out, options) {
+  const { models } = result;
+  if (models.length === 0) {
+    out.write("No models match your filters.\n");
+    return;
+  }
+  const sorted = [...models].sort((a, b) => {
+    const catCmp = a.category.localeCompare(b.category);
+    if (catCmp !== 0) return catCmp;
+    const tierA = TIER_ORDER[a.costTier] ?? 99;
+    const tierB = TIER_ORDER[b.costTier] ?? 99;
+    if (tierA !== tierB) return tierA - tierB;
+    return a.slug.localeCompare(b.slug);
+  });
+  const filterParts = [];
+  if (options?.filters) {
+    for (const [k, v] of Object.entries(options.filters)) {
+      if (v) filterParts.push(`${k}=${v}`);
+    }
+  }
+  const filterSuffix = filterParts.length > 0 ? ` (filters: ${filterParts.join(", ")})` : "";
+  out.write(`${sorted.length} models${filterSuffix}
+
+`);
+  const headers = ["SLUG", "NAME", "CATEGORY", "TIER", "CREDITS", "DEFAULT"];
+  const data = sorted.map((m) => [
+    m.slug,
+    m.displayName,
+    m.category,
+    m.costTier,
+    String(m.creditCost),
+    m.isDefault ? "\u2713" : ""
+  ]);
+  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();
+  out.write(padRow(headers) + "\n");
+  for (const cells of data) out.write(padRow(cells) + "\n");
+  out.write(
+    `
+Showing all ${sorted.length} models. Use --json for full details including constraints.
+`
+  );
+  if (options?.verbose) {
+    out.write("\n");
+    for (const m of sorted) {
+      const pad = 16;
+      out.write(`${m.slug} (${m.displayName})
+`);
+      out.write(`${"  Provider:".padEnd(pad)}${m.providerName}
+`);
+      out.write(`${"  Category:".padEnd(pad)}${m.category} / ${m.modelType}
+`);
+      out.write(`${"  Tier:".padEnd(pad)}${m.costTier} (${m.creditCost} credits)
+`);
+      if (m.llmContext) {
+        const ctx = m.llmContext.length > 100 ? m.llmContext.slice(0, 100) + "..." : m.llmContext;
+        out.write(`${"  Context:".padEnd(pad)}${ctx}
+`);
+      }
+      out.write("\n");
+    }
+  }
+}
 function formatExpiresAt(iso) {
   const ms = Date.parse(iso);
   if (Number.isNaN(ms)) return iso;
@@ -3093,6 +3351,7 @@ function renderRootHelp(version) {
     "  tokens list             List the caller's API tokens",
     "  balance                 Show credit balance and rate limits",
     "  brand-model list        List available brand models",
+    "  models list             List available AI models",
     "  telemetry inspect       Show current telemetry state and payload shape",
     "  template list            List available templates",
     "  template get             Fetch a template by ID",
@@ -3172,6 +3431,38 @@ function renderCommandHelp(command) {
         "  --json             Emit JSON envelope instead of human output",
         ""
       ].join("\n");
+    case "models":
+      return [
+        "Usage: clickraft models <subcommand> [options]",
+        "",
+        "Subcommands:",
+        "  list  List available AI models",
+        ""
+      ].join("\n");
+    case "models list":
+      return [
+        "Usage: clickraft models list [options]",
+        "",
+        "List AI models available for generation. By default shows a summary table;",
+        "use --json for full details including constraints and llmContext.",
+        "",
+        "Options:",
+        "  --category <name>     Filter by category (image, video, audio, chat, edit)",
+        "  --tier <name>         Filter by cost tier (standard, pro, premium)",
+        "  --type <name>         Filter by model type (e.g. text-to-image)",
+        "  --featured            Show only featured models",
+        "  --verbose             Show expanded per-model details after the table",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        "",
+        "Examples:",
+        "  clickraft models list",
+        "  clickraft models list --category image --tier pro",
+        "  clickraft models list --featured --json",
+        ""
+      ].join("\n");
     case "telemetry inspect":
       return [
         "Usage: clickraft telemetry inspect [options]",
@@ -3256,7 +3547,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",
@@ -3365,6 +3658,12 @@ function matchNewCommand(argv) {
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "template" };
     return { kind: "unknown-sub", verb: "template", sub };
   }
+  if (verb === "models") {
+    const sub = argv[1];
+    if (sub === "list") return { kind: "cmd", path: "models.list", verbTokenCount: 2 };
+    if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "models" };
+    return { kind: "unknown-sub", verb: "models", sub };
+  }
   return null;
 }
 async function runNewCommand(newCmd, options, stdout, stderr) {
@@ -3421,6 +3720,8 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runTemplateGet(argvAfterVerb, ctx, rc);
       case "template.find":
         return await runTemplateFind(argvAfterVerb, ctx, rc);
+      case "models.list":
+        return await runModelsList(argvAfterVerb, ctx, rc);
     }
   } catch (err) {
     if (isAbortedError(err, options.signal)) {
@@ -3451,7 +3752,6 @@ async function runGenerateCreate(argv, ctx, rc) {
       ...COMMON_RICH_STRING_FLAGS,
       "prompt",
       "model-slug",
-      "brand-model",
       "aspect-ratio",
       "resolution",
       "duration-seconds",
@@ -3460,10 +3760,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 +3774,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),
@@ -3696,6 +3999,42 @@ function emitTemplateDetail(detail, ctx, rc) {
   }
   renderTemplateDetail(detail, rc.stdout);
 }
+async function runModelsList(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "category", "tier", "type"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS, "featured", "verbose"]
+  });
+  const result = await listModels({
+    category: parsed.string.category,
+    tier: parsed.string.tier,
+    type: parsed.string.type,
+    featured: parsed.boolean.featured,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  emitModelsList(result, ctx, rc, parsed);
+  return 0;
+}
+function emitModelsList(result, ctx, rc, parsed) {
+  if (rc.signal?.aborted) {
+    throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  }
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderModelsList(result, rc.stdout, {
+    verbose: parsed.boolean.verbose === true,
+    filters: {
+      category: parsed.string.category ?? "",
+      tier: parsed.string.tier ?? "",
+      type: parsed.string.type ?? "",
+      featured: parsed.boolean.featured !== void 0 ? String(parsed.boolean.featured) : ""
+    }
+  });
+}
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);