@flatkey-ai/cli 0.1.0 → 0.1.1

package/README.md

@@ -30,8 +30,10 @@ export FLATKEY_API_KEY=<key>
 
 ```bash
 flatkey image generate --prompt "magazine cover" --json
+flatkey image generate --prompt "magazine cover" --output cover.png --json
 flatkey video generate --prompt "product launch clip" --json
 flatkey audio generate --prompt "30 second voiceover" --json
+flatkey text generate --prompt "write a headline" --model gpt-5.5 --json
 flatkey credits --json
 flatkey status --json
 flatkey models --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -9,9 +9,13 @@ export class FlatkeyError extends Error {
 }
 
 export async function generateImage(options) {
+  return requestJsonFromPlan(options, planImageRequest(options));
+}
+
+export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
   if (model.startsWith("gpt")) {
-    return postJson(options, "/v1/images/generations", cleanObject({
+    return planJsonPost(options, "/v1/images/generations", cleanObject({
       model,
       prompt: options.prompt,
       size: options.size,
@@ -21,17 +25,21 @@ export async function generateImage(options) {
   }
 
   const path = `/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(options.apiKey)}`;
-  return requestJson(options, path, {
+  return planRequest(options, path, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({
+    body: {
       contents: [{ parts: [{ text: options.prompt }] }],
-    }),
+    },
   });
 }
 
 export function generateVideo(options) {
-  return postJson(options, "/v1/videos/generations", cleanObject({
+  return requestJsonFromPlan(options, planVideoRequest(options));
+}
+
+export function planVideoRequest(options) {
+  return planJsonPost(options, "/v1/videos/generations", cleanObject({
     model: options.model ?? "veo-3",
     prompt: options.prompt,
     duration: parseOptionalInteger(options.duration),
@@ -41,7 +49,11 @@ export function generateVideo(options) {
 }
 
 export function generateAudio(options) {
-  return postJson(options, "/v1/audio/generations", cleanObject({
+  return requestJsonFromPlan(options, planAudioRequest(options));
+}
+
+export function planAudioRequest(options) {
+  return planJsonPost(options, "/v1/audio/generations", cleanObject({
     model: options.model ?? "tts-1",
     prompt: options.prompt,
     voice: options.voice,
@@ -49,6 +61,17 @@ export function generateAudio(options) {
   }));
 }
 
+export function generateText(options) {
+  return requestJsonFromPlan(options, planTextRequest(options));
+}
+
+export function planTextRequest(options) {
+  return planJsonPost(options, "/v1/chat/completions", {
+    model: options.model ?? "gpt-5.5",
+    messages: [{ role: "user", content: options.prompt }],
+  });
+}
+
 export function getCredits(options) {
   return requestJson(options, "/v1/credits");
 }
@@ -62,22 +85,32 @@ export function getModels(options) {
 }
 
 async function postJson(options, path, payload) {
-  return requestJson(options, path, {
+  return requestJsonFromPlan(options, planJsonPost(options, path, payload));
+}
+
+function planJsonPost(options, path, payload) {
+  return planRequest(options, path, {
     method: "POST",
     headers: jsonHeaders(options.apiKey),
-    body: JSON.stringify(payload),
+    body: payload,
   });
 }
 
-async function requestJson(options, path, init = {}) {
+function planRequest(options, path, init = {}) {
+  return {
+    url: buildUrl(options.baseUrl, path),
+    method: init.method ?? "GET",
+    headers: init.headers ?? authHeaders(options.apiKey),
+    body: init.body,
+  };
+}
+
+async function requestJsonFromPlan(options, plan) {
   const fetchImpl = options.fetch ?? fetch;
-  const response = await fetchImpl(buildUrl(options.baseUrl, path), {
-    method: "GET",
-    ...init,
-    headers: {
-      ...authHeaders(options.apiKey),
-      ...init.headers,
-    },
+  const response = await fetchImpl(plan.url, {
+    method: plan.method,
+    headers: plan.headers,
+    body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
   });
   const body = await readJson(response);
   if (!response.ok) {
@@ -88,6 +121,17 @@ async function requestJson(options, path, init = {}) {
   return body;
 }
 
+async function requestJson(options, path, init = {}) {
+  return requestJsonFromPlan(options, planRequest(options, path, {
+    method: init.method ?? "GET",
+    headers: {
+      ...authHeaders(options.apiKey),
+      ...init.headers,
+    },
+    body: init.body ? JSON.parse(init.body) : undefined,
+  }));
+}
+
 function buildUrl(baseUrl = DEFAULT_BASE_URL, path) {
   return `${baseUrl.replace(/\/$/, "")}${path}`;
 }

package/src/artifacts.js

@@ -1,5 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, extname, join } from "node:path";
 
 const DEFAULT_EXTENSIONS = {
   audio: "mp3",
@@ -18,34 +18,51 @@ const MIME_EXTENSIONS = {
   "video/mp4": "mp4",
 };
 
-export async function persistArtifacts({ kind, response, outDir = "flatkey-output" }) {
+export async function persistArtifacts({
+  kind,
+  response,
+  outDir = "flatkey-output",
+  output,
+  fetch: fetchImpl = fetch,
+}) {
   const items = extractItems(response);
   const artifacts = [];
-  await mkdir(outDir, { recursive: true });
+  await mkdir(output ? dirname(output) : outDir, { recursive: true });
 
   for (const [index, item] of items.entries()) {
-    const artifact = await persistItem({ kind, item, outDir, index });
+    const artifact = await persistItem({ kind, item, outDir, output, index, fetchImpl });
     if (artifact) artifacts.push(artifact);
   }
 
   return artifacts;
 }
 
-async function persistItem({ kind, item, outDir, index }) {
+async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
   const dataUrl = getString(item, ["url", "data_url", "dataUrl"]);
   if (dataUrl?.startsWith("data:")) {
     const parsed = parseDataUrl(dataUrl);
-    const path = artifactPath({ kind, outDir, index, extension: parsed.extension });
+    const path = artifactPath({ kind, outDir, output, index, extension: parsed.extension });
     await writeFile(path, parsed.buffer);
     return { path };
   }
   if (dataUrl?.startsWith("http://") || dataUrl?.startsWith("https://")) {
+    if (output) {
+      const path = artifactPath({
+        kind,
+        outDir,
+        output,
+        index,
+        extension: DEFAULT_EXTENSIONS[kind] ?? "bin",
+      });
+      await downloadArtifact({ url: dataUrl, path, fetchImpl });
+      return { path };
+    }
     return { url: dataUrl };
   }
 
   const base64 = getString(item, ["b64_json", "base64", "data"]);
   if (base64) {
-    const path = artifactPath({ kind, outDir, index, extension: DEFAULT_EXTENSIONS[kind] });
+    const path = artifactPath({ kind, outDir, output, index, extension: DEFAULT_EXTENSIONS[kind] });
     await writeFile(path, Buffer.from(base64, "base64"));
     return { path };
   }
@@ -53,6 +70,14 @@ async function persistItem({ kind, item, outDir, index }) {
   return undefined;
 }
 
+async function downloadArtifact({ url, path, fetchImpl }) {
+  const response = await fetchImpl(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download artifact ${url}: HTTP ${response.status}`);
+  }
+  await writeFile(path, Buffer.from(await response.arrayBuffer()));
+}
+
 function extractItems(response) {
   if (Array.isArray(response?.data)) return response.data;
   if (Array.isArray(response?.artifacts)) return response.artifacts;
@@ -80,7 +105,14 @@ function parseDataUrl(value) {
   };
 }
 
-function artifactPath({ kind, outDir, index, extension }) {
+function artifactPath({ kind, outDir, output, index, extension }) {
+  if (output) {
+    if (index === 0) return output;
+    const existingExtension = extname(output);
+    const base = existingExtension ? output.slice(0, -existingExtension.length) : output;
+    const suffix = String(index + 1).padStart(2, "0");
+    return `${base}-${suffix}${existingExtension || `.${extension}`}`;
+  }
   const number = String(index + 1).padStart(2, "0");
   return join(outDir, `${kind}-${number}.${extension}`);
 }

package/src/cli.js

@@ -6,11 +6,12 @@ const COMMANDS = new Set([
   "models",
   "onboard",
   "status",
+  "text",
   "version",
   "video",
 ]);
 
-const GROUP_ACTIONS = new Set(["audio", "image", "video"]);
+const GROUP_ACTIONS = new Set(["audio", "image", "text", "video"]);
 
 export function parseArgv(argv) {
   const [group, maybeAction, ...rest] = argv;
@@ -36,6 +37,15 @@ function parseOptions(tokens) {
   const options = {};
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index];
+    if (token === "-o") {
+      const output = tokens[index + 1];
+      if (!output || output.startsWith("-")) {
+        throw new Error("Missing value for -o.");
+      }
+      options.output = output;
+      index += 1;
+      continue;
+    }
     if (!token.startsWith("--")) {
       throw new Error(`Unexpected argument: ${token}`);
     }
@@ -88,7 +98,7 @@ export async function runCommand(command, deps = {}) {
     return handleUtility(command, deps);
   }
 
-  if (["image", "video", "audio"].includes(command.group)) {
+  if (["image", "video", "audio", "text"].includes(command.group)) {
     if (command.action !== "generate") {
       throw new Error(`Unknown action for ${command.group}: ${command.action}`);
     }
@@ -100,19 +110,40 @@ export async function runCommand(command, deps = {}) {
 
 async function handleGenerate(command, deps) {
   const { resolveApiKey } = await import("./config.js");
-  const { generateAudio, generateImage, generateVideo } = await import("./api.js");
+  const {
+    generateAudio,
+    generateImage,
+    generateText,
+    generateVideo,
+    planAudioRequest,
+    planImageRequest,
+    planTextRequest,
+    planVideoRequest,
+  } = await import("./api.js");
   const { persistArtifacts } = await import("./artifacts.js");
   const { createAnimation } = await import("./animation.js");
-  const apiKey = await resolveApiKey({
-    apiKey: command.options.api_key,
-    env: deps.env ?? process.env,
-  });
+  const apiKey = command.options.dry_run
+    ? (command.options.api_key ?? "FLATKEY_API_KEY")
+    : await resolveApiKey({
+        apiKey: command.options.api_key,
+        env: deps.env ?? process.env,
+      });
   const options = {
     ...command.options,
     apiKey,
     baseUrl: command.options.base_url,
     fetch: deps.fetch,
   };
+  if (command.options.dry_run) {
+    const request = command.group === "image"
+      ? planImageRequest(options)
+      : command.group === "video"
+        ? planVideoRequest(options)
+        : command.group === "audio"
+          ? planAudioRequest(options)
+          : planTextRequest(options);
+    return { dryRun: true, kind: command.group, request: redactRequest(request) };
+  }
   const animation = createAnimation({
     json: Boolean(command.options.json),
     stream: deps.stderr,
@@ -123,11 +154,20 @@ async function handleGenerate(command, deps) {
       ? await generateImage(options)
       : command.group === "video"
         ? await generateVideo(options)
-        : await generateAudio(options);
+        : command.group === "audio"
+          ? await generateAudio(options)
+          : await generateText(options);
+    if (command.group === "text") {
+      const text = extractText(response);
+      const output = await writeTextOutput(text, command.options.output);
+      return { kind: command.group, text, output, response };
+    }
     const artifacts = await persistArtifacts({
       kind: command.group,
       response,
       outDir: command.options.out ?? "flatkey-output",
+      output: command.options.output,
+      fetch: deps.fetch,
     });
     return { kind: command.group, artifacts, response };
   } finally {
@@ -135,6 +175,34 @@ async function handleGenerate(command, deps) {
   }
 }
 
+function extractText(response) {
+  return response?.choices?.[0]?.message?.content
+    ?? response?.output_text
+    ?? response?.text
+    ?? "";
+}
+
+async function writeTextOutput(text, output) {
+  if (!output) return undefined;
+  const { mkdir, writeFile } = await import("node:fs/promises");
+  const { dirname } = await import("node:path");
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, text);
+  return output;
+}
+
+function redactRequest(request) {
+  return {
+    ...request,
+    headers: Object.fromEntries(
+      Object.entries(request.headers ?? {}).map(([key, value]) => [
+        key,
+        key.toLowerCase() === "authorization" ? "Bearer <redacted>" : value,
+      ]),
+    ),
+  };
+}
+
 async function handleUtility(command, deps) {
   const { resolveApiKey } = await import("./config.js");
   const { getCredits, getStatus } = await import("./api.js");

package/src/help.js

@@ -12,12 +12,13 @@ JSON mode:
 - ASCII animation and human logs are disabled.
 
 Commands:
-- flatkey image generate --prompt "<prompt>" --json [--model <model>] [--size 1024x1024] [--out flatkey-output]
-- flatkey video generate --prompt "<prompt>" --json [--model veo-3] [--duration 8] [--aspect 16:9]
-- flatkey audio generate --prompt "<prompt>" --json [--model tts-1] [--voice alloy] [--format mp3]
+- flatkey image generate --prompt "<prompt>" --json [--model <model>] [--output image.png]
+- flatkey video generate --prompt "<prompt>" --json [--model seedance2] [--output video.mp4]
+- flatkey audio generate --prompt "<prompt>" --json [--model tts-1] [--output audio.mp3]
+- flatkey text generate --prompt "<prompt>" --json [--model gpt-5.5] [--output text.txt]
 - flatkey credits --json
 - flatkey status --json
-- flatkey models --json [--type image|video|audio]
+- flatkey models --json [--type image|video|audio|text]
 - flatkey help --ai
 
 Environment:
@@ -39,6 +40,7 @@ Commands:
   image generate --prompt <txt>  Generate image
   video generate --prompt <txt>  Generate video
   audio generate --prompt <txt>  Generate audio
+  text generate --prompt <txt>   Generate text
   credits                        Show remaining credits
   status                         Show usage/status
   models                         List available models
@@ -46,6 +48,7 @@ Commands:
 
 Global options:
   --json                         Print machine-readable JSON
+  --output, -o <file>             Write generated output to a local file
   --base-url <url>               Override Flatkey router URL
 `;
 }

package/src/models.js

@@ -4,6 +4,8 @@ const BUNDLED_MODELS = [
   { id: "gpt-image-2", type: "image" },
   { id: "veo-3", type: "video" },
   { id: "veo-3-fast", type: "video" },
+  { id: "seedance2", type: "video" },
+  { id: "gpt-5.5", type: "text" },
   { id: "tts-1", type: "audio" },
   { id: "gpt-4o-mini-tts", type: "audio" },
 ];
@@ -35,5 +37,10 @@ function inferType(model) {
   if (model.capabilities?.includes("video")) return "video";
   if (model.capabilities?.includes("audio")) return "audio";
   if (model.capabilities?.includes("image")) return "image";
+  if (model.capabilities?.includes("text")) return "text";
+  if (/image|nano-banana/i.test(model.id)) return "image";
+  if (/seedance|veo|sora|video/i.test(model.id)) return "video";
+  if (/tts|audio|voice|speech/i.test(model.id)) return "audio";
+  if (model.object === "model") return "text";
   return undefined;
 }

package/test/api.test.js

@@ -5,10 +5,14 @@ import {
   FlatkeyError,
   generateAudio,
   generateImage,
+  generateText,
   generateVideo,
   getCredits,
   getModels,
   getStatus,
+  planImageRequest,
+  planTextRequest,
+  planVideoRequest,
 } from "../src/api.js";
 
 function fetchRecorder(responseBody = { ok: true }) {
@@ -93,6 +97,39 @@ test("builds video generation request", async () => {
   });
 });
 
+test("builds seedance2 video generation request", async () => {
+  const { fetch, calls } = fetchRecorder({ data: [] });
+
+  await generateVideo({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    model: "seedance2",
+    prompt: "newsroom b-roll",
+    fetch,
+  });
+
+  assert.equal(calls[0].url, "https://router.test/v1/videos/generations");
+  assert.equal(JSON.parse(calls[0].init.body).model, "seedance2");
+});
+
+test("builds text generation request for gpt-5.5", async () => {
+  const { fetch, calls } = fetchRecorder({ choices: [{ message: { content: "copy" } }] });
+
+  await generateText({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    model: "gpt-5.5",
+    prompt: "write headline",
+    fetch,
+  });
+
+  assert.equal(calls[0].url, "https://router.test/v1/chat/completions");
+  assert.deepEqual(JSON.parse(calls[0].init.body), {
+    model: "gpt-5.5",
+    messages: [{ role: "user", content: "write headline" }],
+  });
+});
+
 test("builds audio generation request", async () => {
   const { fetch, calls } = fetchRecorder({ data: [] });
 
@@ -126,6 +163,43 @@ test("builds credits, status, and models requests", async () => {
   assert.equal(calls[1].url, "https://router.test/v1/status");
   assert.equal(calls[2].url, "https://router.test/v1/models");
   assert.equal(calls[0].init.headers.Authorization, "Bearer key");
+  assert.equal(calls[2].init.headers.Authorization, "Bearer key");
+});
+
+test("plans model list request from new-api relay route", async () => {
+  const { fetch, calls } = fetchRecorder({ object: "list", data: [{ id: "gpt-5.5" }] });
+
+  await getModels({ apiKey: "env-key", baseUrl: "https://router.flatkey.ai", fetch });
+
+  assert.equal(calls[0].url, "https://router.flatkey.ai/v1/models");
+  assert.equal(calls[0].init.method, "GET");
+  assert.equal(calls[0].init.headers.Authorization, "Bearer env-key");
+});
+
+test("plans dry-run requests for target media models", () => {
+  assert.equal(planImageRequest({
+    apiKey: "key",
+    model: "gpt-image-2",
+    prompt: "poster",
+  }).url, "https://router.flatkey.ai/v1/images/generations");
+
+  assert.match(planImageRequest({
+    apiKey: "key",
+    model: "nano-banana-pro-preview",
+    prompt: "poster",
+  }).url, /\/v1beta\/models\/nano-banana-pro-preview:generateContent\?key=key$/);
+
+  assert.equal(planVideoRequest({
+    apiKey: "key",
+    model: "seedance2",
+    prompt: "clip",
+  }).body.model, "seedance2");
+
+  assert.equal(planTextRequest({
+    apiKey: "key",
+    model: "gpt-5.5",
+    prompt: "headline",
+  }).body.model, "gpt-5.5");
 });
 
 test("throws FlatkeyError with API message on HTTP failure", async () => {

package/test/artifacts.test.js

@@ -46,3 +46,63 @@ test("preserves remote url artifacts without downloading", async () => {
 
   assert.deepEqual(artifacts, [{ url: "https://cdn.test/audio.mp3" }]);
 });
+
+test("saves first artifact to explicit output path", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+  const output = join(outDir, "custom.png");
+
+  const artifacts = await persistArtifacts({
+    kind: "image",
+    response: { data: [{ b64_json: Buffer.from("custom-bytes").toString("base64") }] },
+    output,
+  });
+
+  assert.deepEqual(artifacts, [{ path: output }]);
+  assert.equal(await readFile(output, "utf8"), "custom-bytes");
+});
+
+test("adds numeric suffix for multiple artifacts with explicit output path", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+  const output = join(outDir, "custom.png");
+
+  const artifacts = await persistArtifacts({
+    kind: "image",
+    response: {
+      data: [
+        { b64_json: Buffer.from("one").toString("base64") },
+        { b64_json: Buffer.from("two").toString("base64") },
+      ],
+    },
+    output,
+  });
+
+  assert.match(artifacts[0].path, /custom\.png$/);
+  assert.match(artifacts[1].path, /custom-02\.png$/);
+  assert.equal(await readFile(artifacts[1].path, "utf8"), "two");
+});
+
+test("downloads remote url artifact when explicit output path is set", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+  const output = join(outDir, "clip.mp4");
+  const calls = [];
+
+  const artifacts = await persistArtifacts({
+    kind: "video",
+    response: { data: [{ url: "https://cdn.test/clip.mp4" }] },
+    output,
+    fetch: async (url) => {
+      calls.push(url);
+      return {
+        ok: true,
+        status: 200,
+        async arrayBuffer() {
+          return Buffer.from("video-bytes");
+        },
+      };
+    },
+  });
+
+  assert.deepEqual(calls, ["https://cdn.test/clip.mp4"]);
+  assert.deepEqual(artifacts, [{ path: output }]);
+  assert.equal(await readFile(output, "utf8"), "video-bytes");
+});

package/test/cli.test.js

@@ -28,6 +28,41 @@ test("parses credits with json mode", () => {
   });
 });
 
+test("parses text generation with dry-run", () => {
+  const command = parseArgv([
+    "text",
+    "generate",
+    "--prompt",
+    "write lead",
+    "--model",
+    "gpt-5.5",
+    "--dry-run",
+    "--json",
+  ]);
+
+  assert.deepEqual(command, {
+    group: "text",
+    action: "generate",
+    options: {
+      prompt: "write lead",
+      model: "gpt-5.5",
+      dry_run: true,
+      json: true,
+    },
+  });
+});
+
+test("parses output aliases", () => {
+  assert.equal(
+    parseArgv(["image", "generate", "--prompt", "x", "--output", "out.png"]).options.output,
+    "out.png",
+  );
+  assert.equal(
+    parseArgv(["video", "generate", "--prompt", "x", "-o", "clip.mp4"]).options.output,
+    "clip.mp4",
+  );
+});
+
 test("parses ai help", () => {
   const command = parseArgv(["help", "--ai"]);
 

package/test/help.test.js

@@ -11,6 +11,7 @@ test("ai help teaches agents setup and command usage", () => {
   assert.match(help, /flatkey image generate/);
   assert.match(help, /flatkey video generate/);
   assert.match(help, /flatkey audio generate/);
+  assert.match(help, /flatkey text generate/);
   assert.match(help, /flatkey credits --json/);
   assert.match(help, /flatkey status --json/);
   assert.match(help, /flatkey models --json/);
@@ -24,4 +25,5 @@ test("human help lists core commands", () => {
   assert.match(help, /Usage: flatkey/);
   assert.match(help, /image generate/);
   assert.match(help, /models/);
+  assert.match(help, /text generate/);
 });

package/test/integration.test.js

@@ -1,6 +1,9 @@
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { test } from "node:test";
 
 const BIN = new URL("../bin/flatkey.js", import.meta.url).pathname;
@@ -21,6 +24,8 @@ test("runs generation and utility commands in json mode", async (t) => {
         response.end(JSON.stringify({ data: [{ url: "https://cdn.test/video.mp4" }] }));
       } else if (request.url === "/v1/audio/generations") {
         response.end(JSON.stringify({ data: [{ url: "https://cdn.test/audio.mp3" }] }));
+      } else if (request.url === "/v1/chat/completions") {
+        response.end(JSON.stringify({ choices: [{ message: { content: "headline" } }] }));
       } else if (request.url === "/v1/credits") {
         response.end(JSON.stringify({ remaining: 42, used: 8 }));
       } else if (request.url === "/v1/status") {
@@ -41,6 +46,7 @@ test("runs generation and utility commands in json mode", async (t) => {
   const image = await runCli(["image", "generate", "--prompt", "poster", ...common]);
   const video = await runCli(["video", "generate", "--prompt", "clip", ...common]);
   const audio = await runCli(["audio", "generate", "--prompt", "voice", ...common]);
+  const text = await runCli(["text", "generate", "--prompt", "headline", ...common]);
   const credits = await runCli(["credits", ...common]);
   const status = await runCli(["status", ...common]);
   const models = await runCli(["models", ...common]);
@@ -48,6 +54,7 @@ test("runs generation and utility commands in json mode", async (t) => {
   assert.deepEqual(JSON.parse(image.stdout).artifacts, [{ url: "https://cdn.test/image.png" }]);
   assert.deepEqual(JSON.parse(video.stdout).artifacts, [{ url: "https://cdn.test/video.mp4" }]);
   assert.deepEqual(JSON.parse(audio.stdout).artifacts, [{ url: "https://cdn.test/audio.mp3" }]);
+  assert.equal(JSON.parse(text.stdout).text, "headline");
   assert.equal(JSON.parse(credits.stdout).remaining, 42);
   assert.equal(JSON.parse(status.stdout).status, "ok");
   assert.deepEqual(JSON.parse(models.stdout).models, [
@@ -57,6 +64,79 @@ test("runs generation and utility commands in json mode", async (t) => {
   assert.ok(requests.some((request) => request.url.startsWith("/v1beta/models/")));
   assert.ok(requests.some((request) => request.url === "/v1/videos/generations"));
   assert.ok(requests.some((request) => request.url === "/v1/audio/generations"));
+  assert.ok(requests.some((request) => request.url === "/v1/chat/completions"));
+});
+
+test("dry-run returns planned request without calling network", async () => {
+  const result = await runCli([
+    "image",
+    "generate",
+    "--prompt",
+    "poster",
+    "--model",
+    "gpt-image-2",
+    "--dry-run",
+    "--json",
+  ]);
+
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.dryRun, true);
+  assert.equal(payload.kind, "image");
+  assert.equal(payload.request.url, "https://router.flatkey.ai/v1/images/generations");
+  assert.equal(payload.request.body.model, "gpt-image-2");
+  assert.equal(result.stderr, "");
+});
+
+test("generation commands write explicit output files", async (t) => {
+  const server = createServer((request, response) => {
+    request.on("data", () => {});
+    request.on("end", () => {
+      response.setHeader("content-type", "application/json");
+      if (request.url === "/v1/images/generations") {
+        response.end(JSON.stringify({
+          data: [{ b64_json: Buffer.from("image-file").toString("base64") }],
+        }));
+      } else if (request.url === "/v1/chat/completions") {
+        response.end(JSON.stringify({ choices: [{ message: { content: "text-file" } }] }));
+      } else {
+        response.statusCode = 404;
+        response.end(JSON.stringify({ error: { message: "not found" } }));
+      }
+    });
+  });
+  t.after(() => server.close());
+  await listen(server);
+  const baseUrl = `http://127.0.0.1:${server.address().port}`;
+  const dir = await mkdtemp(join(tmpdir(), "flatkey-output-"));
+  const imageOutput = join(dir, "poster.png");
+  const textOutput = join(dir, "headline.txt");
+
+  const common = ["--base-url", baseUrl, "--api-key", "test-key", "--json"];
+  const image = await runCli([
+    "image",
+    "generate",
+    "--model",
+    "gpt-image-2",
+    "--prompt",
+    "poster",
+    "--output",
+    imageOutput,
+    ...common,
+  ]);
+  const text = await runCli([
+    "text",
+    "generate",
+    "--prompt",
+    "headline",
+    "-o",
+    textOutput,
+    ...common,
+  ]);
+
+  assert.deepEqual(JSON.parse(image.stdout).artifacts, [{ path: imageOutput }]);
+  assert.equal(await readFile(imageOutput, "utf8"), "image-file");
+  assert.equal(JSON.parse(text.stdout).output, textOutput);
+  assert.equal(await readFile(textOutput, "utf8"), "text-file");
 });
 
 test("prints json errors to stderr in json mode", async () => {

package/test/live-flatkey.test.js

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { test } from "node:test";
+
+const BIN = new URL("../bin/flatkey.js", import.meta.url).pathname;
+const LIVE = process.env.FLATKEY_LIVE_TESTS === "1";
+
+const cases = [
+  {
+    name: "models list",
+    args: ["models", "--json"],
+    paid: false,
+    expect: (payload) => {
+      assert.ok(Array.isArray(payload.models));
+      assert.ok(payload.models.length > 0);
+    },
+  },
+  {
+    name: "image gpt",
+    args: ["image", "generate", "--model", "gpt-image-2", "--prompt", "one tiny red square icon", "--json"],
+    paid: true,
+    dryRun: false,
+    expect: (payload) => assert.equal(payload.kind, "image"),
+  },
+  {
+    name: "image nano",
+    args: ["image", "generate", "--model", "nano-banana-pro-preview", "--prompt", "one tiny blue square icon", "--json"],
+    paid: true,
+    dryRun: false,
+    expect: (payload) => assert.equal(payload.kind, "image"),
+  },
+  {
+    name: "video seedance2",
+    args: ["video", "generate", "--model", "seedance2", "--prompt", "one second newsroom establishing shot", "--duration", "1", "--json"],
+    paid: true,
+    dryRun: false,
+    expect: (payload) => assert.equal(payload.kind, "video"),
+  },
+  {
+    name: "text gpt-5.5",
+    args: ["text", "generate", "--model", "gpt-5.5", "--prompt", "Write a five word headline.", "--json"],
+    paid: true,
+    dryRun: false,
+    expect: (payload) => {
+      assert.equal(payload.kind, "text");
+      assert.equal(typeof payload.text, "string");
+    },
+  },
+];
+
+for (const item of cases) {
+  test(`live flatkey ${item.name}${item.dryRun ? " dry-run" : ""}`, { skip: !LIVE }, async () => {
+    assert.ok(process.env.FLATKEY_API_KEY, "FLATKEY_API_KEY is required");
+    const outDir = await mkdtemp(join(tmpdir(), "flatkey-live-"));
+    const args = [...item.args, "--out", outDir];
+    if (item.dryRun) args.push("--dry-run");
+    const result = await runCli(args);
+    const payload = JSON.parse(result.stdout);
+    item.expect(payload);
+  });
+}
+
+function runCli(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [BIN, ...args], {
+      env: {
+        ...process.env,
+        FLATKEY_API_KEY: process.env.FLATKEY_API_KEY,
+      },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`CLI exited ${code}\nstdout:${stdout}\nstderr:${stderr}`));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}

package/test/models.test.js

@@ -7,7 +7,10 @@ test("returns bundled fallback models with source marker", () => {
   const models = getBundledModels();
 
   assert.ok(models.some((model) => model.id === "nano-banana-pro-preview"));
+  assert.ok(models.some((model) => model.id === "seedance2"));
+  assert.ok(models.some((model) => model.id === "gpt-5.5"));
   assert.ok(models.some((model) => model.type === "video"));
+  assert.ok(models.some((model) => model.type === "text"));
   assert.ok(models.some((model) => model.type === "audio"));
   assert.equal(models[0].source, "bundled");
 });
@@ -32,3 +35,22 @@ test("normalizes remote model arrays", () => {
     { id: "vid-x", type: "video", source: "remote" },
   ]);
 });
+
+test("normalizes OpenAI model list response from /v1/models", () => {
+  const models = normalizeModels({
+    object: "list",
+    data: [
+      { id: "gpt-5.5", object: "model" },
+      { id: "seedance2", object: "model" },
+      { id: "gpt-image-2", object: "model" },
+      { id: "nano-banana-pro-preview", object: "model" },
+    ],
+  });
+
+  assert.deepEqual(models, [
+    { id: "gpt-5.5", type: "text", source: "remote" },
+    { id: "seedance2", type: "video", source: "remote" },
+    { id: "gpt-image-2", type: "image", source: "remote" },
+    { id: "nano-banana-pro-preview", type: "image", source: "remote" },
+  ]);
+});