@clickraft/cli 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,8 +1,15 @@
-## [0.11.1](https://github.com/clickraft/cli/compare/v0.11.0...v0.11.1) (2026-06-21)
+## [0.12.0](https://github.com/clickraft/cli/compare/v0.11.2...v0.12.0) (2026-07-02)
 
-### Bug Fixes
+### ⚠ BREAKING CHANGES
 
-* **cli:** widen models schema to accept server lifecycle fields and any-typed constraints ([47eedfa](https://github.com/clickraft/cli/commit/47eedfa0e126034fa5f46e29610cc626d3de8c32)), closes [#10](https://github.com/clickraft/cli/issues/10) [#R2-constraints](https://github.com/clickraft/cli/issues/R2-constraints) [8/#10](https://github.com/8/cli/issues/10)
+* **generate:** a lone --reference-image no longer sets the
+image-to-video start frame. To set the start frame, use the new
+--start-frame flag. --reference-image remains for reference images
+(repeatable, max 8).
+
+### Features
+
+* **generate:** route --reference-image to references and add --start-frame for i2v start frame ([b37ffee](https://github.com/clickraft/cli/commit/b37ffee452f97cbac99b9e1166d69124c101fc7b))
 
 # Changelog
 
@@ -10,6 +17,30 @@ All notable changes to the Clickraft CLI are documented here.
 
 ## Unreleased
 
+### Added
+
+- **`generate create --start-frame <url|path>`** — sets the image-to-video start
+  frame. It is emitted as the scalar `referenceImageUrl`, which the server maps
+  to `start_image`. Accepts an http(s) URL or a local path (auto-uploaded, like
+  `--reference-image`).
+
+### Changed
+
+- **BREAKING: `generate create --reference-image` now always routes to the
+  references category**, regardless of how many are supplied. Previously a
+  *single* `--reference-image` was collapsed into the scalar `referenceImageUrl`
+  (which the server treats as the image-to-video start frame), so it was rejected
+  by image models such as `gpt-image-2` that only accept references — while two
+  or more images worked. A single reference image is now sent as
+  `referenceImages: [{ url }]` and is accepted correctly.
+
+  **Migration (image-to-video users):** a lone `--reference-image <url>` no
+  longer sets the start frame. To set the start frame, use the new
+  `--start-frame <url>` flag. `--reference-image` remains for reference images
+  (repeatable, max 8). The same routing change applies to the `generate_create`
+  MCP tool: `referenceImages` is always references; the new `startFrame` input
+  sets the start frame.
+
 ### Fixed
 
 - **Workflow docs taught fictional node types and port names.** All examples in

package/dist/cli.js

@@ -95,8 +95,8 @@ var TokensListResponseSchema = z4.array(TokenRowSchema);
 var DeclaredParamSchema = z5.object({
   name: z5.string(),
   type: z5.string(),
-  required: z5.boolean(),
-  defaultValue: z5.string().nullable().optional(),
+  required: z5.boolean().optional(),
+  defaultValue: z5.unknown().optional(),
   enumValues: z5.array(z5.string()).nullable().optional(),
   description: z5.string().nullable().optional()
 }).strict();
@@ -139,6 +139,8 @@ 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(),
+    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()
   }).strict(),
   options: z6.object({
@@ -2059,13 +2061,19 @@ async function generateCreate(opts) {
   const preflightRefs = (opts.referenceImages ?? []).map(
     (v) => isUrlLike(v) ? v : PREFLIGHT_PLACEHOLDER_URL
   );
-  buildRequestBody({ ...opts, referenceImages: preflightRefs });
+  const preflightStartFrame = opts.startFrame === void 0 ? void 0 : isUrlLike(opts.startFrame) ? opts.startFrame : PREFLIGHT_PLACEHOLDER_URL;
+  buildRequestBody({ ...opts, referenceImages: preflightRefs, startFrame: preflightStartFrame });
   const referenceImages = await resolveReferenceImages({
     items: opts.referenceImages ?? [],
     client,
     signal: opts.signal
   });
-  const body = buildRequestBody({ ...opts, referenceImages });
+  const startFrame = opts.startFrame === void 0 ? void 0 : (await resolveReferenceImages({
+    items: [opts.startFrame],
+    client,
+    signal: opts.signal
+  }))[0];
+  const body = buildRequestBody({ ...opts, referenceImages, startFrame });
   return createGeneration({
     client,
     body,
@@ -2100,11 +2108,12 @@ async function resolveReferenceImages(args) {
 function buildRequestBody(args) {
   const input = {};
   if (args.prompt !== void 0) input.prompt = args.prompt;
-  if (args.referenceImages.length === 1) {
-    input.referenceImageUrl = args.referenceImages[0];
-  } else if (args.referenceImages.length > 1) {
+  if (args.referenceImages.length > 0) {
     input.referenceImages = args.referenceImages.map((url) => ({ url }));
   }
+  if (args.startFrame !== void 0) {
+    input.referenceImageUrl = args.startFrame;
+  }
   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;
@@ -4290,7 +4299,8 @@ function renderCommandHelp(command) {
         "  --product <spec>          Product reference (repeatable)",
         "                             Format: <uuid> or <uuid>:<imageId>",
         "                             Server enforces reference cap per model",
-        "  --reference-image <v>     URL or local path (repeatable, max 8)",
+        "  --reference-image <v>     Reference image: URL or local path (repeatable, max 8)",
+        "  --start-frame <v>         Image-to-video start frame: URL or local path",
         "  --aspect-ratio <a:b>      e.g. 16:9",
         "  --resolution <size>       e.g. 1024x768, 720p, 1K",
         "  --duration-seconds <n>    For video/audio models (1-60)",
@@ -4605,6 +4615,7 @@ async function runGenerateCreate(argv, ctx, rc) {
       ...COMMON_RICH_STRING_FLAGS,
       "prompt",
       "model-slug",
+      "start-frame",
       "aspect-ratio",
       "resolution",
       "duration-seconds",
@@ -4627,6 +4638,7 @@ async function runGenerateCreate(argv, ctx, rc) {
     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"),