@clickraft/cli 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,9 +1,15 @@
-## [0.11.2](https://github.com/clickraft/cli/compare/v0.11.1...v0.11.2) (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
 
-* **sdk:** accept input.width/height in GenerateCreateRequestSchema ([6f92a22](https://github.com/clickraft/cli/commit/6f92a22f8152ce48bbb7ce95e1f4c3134fe81b5d)), closes [#3](https://github.com/clickraft/cli/issues/3)
-* **sdk:** widen declaredParams required (optional) + defaultValue (any-typed) to match server ([03eb961](https://github.com/clickraft/cli/commit/03eb961f9c05272c96cbb7de8667ef0222e08691)), closes [#5](https://github.com/clickraft/cli/issues/5) [#6](https://github.com/clickraft/cli/issues/6) [#N](https://github.com/clickraft/cli/issues/N) [5/#6](https://github.com/5/cli/issues/6)
+* **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
 
@@ -11,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

@@ -2061,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,
@@ -2102,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;
@@ -4292,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)",
@@ -4607,6 +4615,7 @@ async function runGenerateCreate(argv, ctx, rc) {
       ...COMMON_RICH_STRING_FLAGS,
       "prompt",
       "model-slug",
+      "start-frame",
       "aspect-ratio",
       "resolution",
       "duration-seconds",
@@ -4629,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"),