@flatkey-ai/cli 0.1.0

package/src/artifacts.js

@@ -0,0 +1,86 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const DEFAULT_EXTENSIONS = {
+  audio: "mp3",
+  image: "png",
+  video: "mp4",
+};
+
+const MIME_EXTENSIONS = {
+  "audio/aac": "aac",
+  "audio/flac": "flac",
+  "audio/mpeg": "mp3",
+  "audio/mp3": "mp3",
+  "audio/wav": "wav",
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "video/mp4": "mp4",
+};
+
+export async function persistArtifacts({ kind, response, outDir = "flatkey-output" }) {
+  const items = extractItems(response);
+  const artifacts = [];
+  await mkdir(outDir, { recursive: true });
+
+  for (const [index, item] of items.entries()) {
+    const artifact = await persistItem({ kind, item, outDir, index });
+    if (artifact) artifacts.push(artifact);
+  }
+
+  return artifacts;
+}
+
+async function persistItem({ kind, item, outDir, index }) {
+  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 });
+    await writeFile(path, parsed.buffer);
+    return { path };
+  }
+  if (dataUrl?.startsWith("http://") || dataUrl?.startsWith("https://")) {
+    return { url: dataUrl };
+  }
+
+  const base64 = getString(item, ["b64_json", "base64", "data"]);
+  if (base64) {
+    const path = artifactPath({ kind, outDir, index, extension: DEFAULT_EXTENSIONS[kind] });
+    await writeFile(path, Buffer.from(base64, "base64"));
+    return { path };
+  }
+
+  return undefined;
+}
+
+function extractItems(response) {
+  if (Array.isArray(response?.data)) return response.data;
+  if (Array.isArray(response?.artifacts)) return response.artifacts;
+  if (Array.isArray(response?.candidates)) {
+    return response.candidates.flatMap((candidate) => candidate.content?.parts ?? []);
+  }
+  return [];
+}
+
+function getString(item, keys) {
+  for (const key of keys) {
+    if (typeof item?.[key] === "string") return item[key];
+    if (typeof item?.inlineData?.[key] === "string") return item.inlineData[key];
+    if (typeof item?.inline_data?.[key] === "string") return item.inline_data[key];
+  }
+  return undefined;
+}
+
+function parseDataUrl(value) {
+  const match = /^data:([^;,]+);base64,(.+)$/s.exec(value);
+  if (!match) throw new Error("Unsupported data URL artifact.");
+  return {
+    extension: MIME_EXTENSIONS[match[1]] ?? "bin",
+    buffer: Buffer.from(match[2], "base64"),
+  };
+}
+
+function artifactPath({ kind, outDir, index, extension }) {
+  const number = String(index + 1).padStart(2, "0");
+  return join(outDir, `${kind}-${number}.${extension}`);
+}

package/src/cli.js

@@ -0,0 +1,178 @@
+const COMMANDS = new Set([
+  "audio",
+  "credits",
+  "help",
+  "image",
+  "models",
+  "onboard",
+  "status",
+  "version",
+  "video",
+]);
+
+const GROUP_ACTIONS = new Set(["audio", "image", "video"]);
+
+export function parseArgv(argv) {
+  const [group, maybeAction, ...rest] = argv;
+  if (!group) {
+    return { group: "help", action: undefined, options: {} };
+  }
+  if (!COMMANDS.has(group)) {
+    throw new Error(`Unknown command: ${group}`);
+  }
+
+  const hasAction = GROUP_ACTIONS.has(group);
+  const action = hasAction ? maybeAction : undefined;
+  const optionTokens = hasAction ? rest : argv.slice(1);
+
+  return {
+    group,
+    action,
+    options: parseOptions(optionTokens),
+  };
+}
+
+function parseOptions(tokens) {
+  const options = {};
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const name = token.slice(2).replaceAll("-", "_");
+    const next = tokens[index + 1];
+    if (!next || next.startsWith("--")) {
+      options[name] = true;
+      continue;
+    }
+    options[name] = next;
+    index += 1;
+  }
+  return options;
+}
+
+export async function main(argv) {
+  const command = parseArgv(argv);
+  if (command.group === "onboard") {
+    const { writeConfig } = await import("./config.js");
+    const configPath = await writeConfig({ apiKey: command.options.api_key });
+    process.stdout.write(`Saved Flatkey config: ${configPath}\n`);
+    return;
+  }
+
+  const result = await runCommand(command);
+  if (result !== undefined) {
+    process.stdout.write(
+      command.options.json ? `${JSON.stringify(result)}\n` : `${formatHuman(result)}\n`,
+    );
+  }
+}
+
+export async function runCommand(command, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+
+  if (command.group === "help") {
+    const { getAiHelp, getHumanHelp } = await import("./help.js");
+    return command.options.ai ? getAiHelp() : getHumanHelp();
+  }
+  if (command.group === "version") {
+    return { version: "0.1.0" };
+  }
+
+  if (command.group === "models") {
+    return handleModels(command, deps);
+  }
+
+  if (command.group === "credits" || command.group === "status") {
+    return handleUtility(command, deps);
+  }
+
+  if (["image", "video", "audio"].includes(command.group)) {
+    if (command.action !== "generate") {
+      throw new Error(`Unknown action for ${command.group}: ${command.action}`);
+    }
+    return handleGenerate(command, { ...deps, stdout, stderr });
+  }
+
+  throw new Error(`Unknown command: ${command.group}`);
+}
+
+async function handleGenerate(command, deps) {
+  const { resolveApiKey } = await import("./config.js");
+  const { generateAudio, generateImage, generateVideo } = 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 options = {
+    ...command.options,
+    apiKey,
+    baseUrl: command.options.base_url,
+    fetch: deps.fetch,
+  };
+  const animation = createAnimation({
+    json: Boolean(command.options.json),
+    stream: deps.stderr,
+  });
+  animation.start(command.group);
+  try {
+    const response = command.group === "image"
+      ? await generateImage(options)
+      : command.group === "video"
+        ? await generateVideo(options)
+        : await generateAudio(options);
+    const artifacts = await persistArtifacts({
+      kind: command.group,
+      response,
+      outDir: command.options.out ?? "flatkey-output",
+    });
+    return { kind: command.group, artifacts, response };
+  } finally {
+    animation.stop();
+  }
+}
+
+async function handleUtility(command, deps) {
+  const { resolveApiKey } = await import("./config.js");
+  const { getCredits, getStatus } = await import("./api.js");
+  const apiKey = await resolveApiKey({
+    apiKey: command.options.api_key,
+    env: deps.env ?? process.env,
+  });
+  const options = {
+    apiKey,
+    baseUrl: command.options.base_url,
+    fetch: deps.fetch,
+  };
+  return command.group === "credits" ? getCredits(options) : getStatus(options);
+}
+
+async function handleModels(command, deps) {
+  const { resolveApiKey } = await import("./config.js");
+  const { getModels } = await import("./api.js");
+  const { getBundledModels, normalizeModels } = await import("./models.js");
+
+  try {
+    const apiKey = await resolveApiKey({
+      apiKey: command.options.api_key,
+      env: deps.env ?? process.env,
+    });
+    const response = await getModels({
+      apiKey,
+      baseUrl: command.options.base_url,
+      fetch: deps.fetch,
+    });
+    const models = normalizeModels(response, command.options.type);
+    return { models: models.length ? models : getBundledModels(command.options.type) };
+  } catch {
+    return { models: getBundledModels(command.options.type) };
+  }
+}
+
+function formatHuman(result) {
+  if (typeof result === "string") return result;
+  return JSON.stringify(result, null, 2);
+}

package/src/config.js

@@ -0,0 +1,54 @@
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function getDefaultConfigDir() {
+  return join(homedir(), ".config", "flatkey");
+}
+
+export function getConfigPath(configDir = getDefaultConfigDir()) {
+  return join(configDir, "config.json");
+}
+
+export async function resolveApiKey({
+  apiKey,
+  env = process.env,
+  configDir = getDefaultConfigDir(),
+} = {}) {
+  if (apiKey) return apiKey;
+  if (env.FLATKEY_API_KEY) return env.FLATKEY_API_KEY;
+
+  const saved = await readSavedConfig(configDir);
+  if (saved?.apiKey) return saved.apiKey;
+
+  throw new Error(
+    "Missing Flatkey API key. Run `flatkey onboard --api-key <key>` or set FLATKEY_API_KEY.",
+  );
+}
+
+export async function writeConfig({ apiKey, configDir = getDefaultConfigDir() }) {
+  if (!apiKey) {
+    throw new Error("Missing --api-key value.");
+  }
+
+  await mkdir(configDir, { recursive: true });
+  const configPath = getConfigPath(configDir);
+  await writeFile(configPath, `${JSON.stringify({ apiKey }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  try {
+    await chmod(configPath, 0o600);
+  } catch (error) {
+    if (process.platform !== "win32") throw error;
+  }
+  return configPath;
+}
+
+async function readSavedConfig(configDir) {
+  try {
+    return JSON.parse(await readFile(getConfigPath(configDir), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}

package/src/help.js

@@ -0,0 +1,51 @@
+export function getAiHelp() {
+  return `Flatkey CLI protocol for agents
+
+Setup:
+- Prefer env: FLATKEY_API_KEY=<key>
+- Or save key: flatkey onboard --api-key <key>
+- Use --json for machine-readable output.
+
+JSON mode:
+- stdout contains only JSON.
+- stderr contains JSON errors on failure.
+- 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 credits --json
+- flatkey status --json
+- flatkey models --json [--type image|video|audio]
+- flatkey help --ai
+
+Environment:
+- FLATKEY_API_KEY: Flatkey API key.
+- Default router: https://router.flatkey.ai
+
+Recovery:
+- Missing key: run flatkey onboard --api-key <key> or set FLATKEY_API_KEY.
+- Unknown model: run flatkey models --json, then retry with a listed model id.
+- API failure: inspect stderr JSON or HTTP message, then retry only after fixing request or credits.
+`;
+}
+
+export function getHumanHelp() {
+  return `Usage: flatkey <command> [options]
+
+Commands:
+  onboard --api-key <key>        Save Flatkey API key
+  image generate --prompt <txt>  Generate image
+  video generate --prompt <txt>  Generate video
+  audio generate --prompt <txt>  Generate audio
+  credits                        Show remaining credits
+  status                         Show usage/status
+  models                         List available models
+  help --ai                      Print agent-focused usage guide
+
+Global options:
+  --json                         Print machine-readable JSON
+  --base-url <url>               Override Flatkey router URL
+`;
+}

package/src/models.js

@@ -0,0 +1,39 @@
+const BUNDLED_MODELS = [
+  { id: "nano-banana-pro-preview", type: "image" },
+  { id: "nano-banana-flash", type: "image" },
+  { id: "gpt-image-2", type: "image" },
+  { id: "veo-3", type: "video" },
+  { id: "veo-3-fast", type: "video" },
+  { id: "tts-1", type: "audio" },
+  { id: "gpt-4o-mini-tts", type: "audio" },
+];
+
+export function getBundledModels(type) {
+  return BUNDLED_MODELS
+    .filter((model) => !type || model.type === type)
+    .map((model) => ({ ...model, source: "bundled" }));
+}
+
+export function normalizeModels(response, type) {
+  const rawModels = Array.isArray(response?.data)
+    ? response.data
+    : Array.isArray(response?.models)
+      ? response.models
+      : [];
+
+  return rawModels
+    .map((model) => ({
+      id: model.id,
+      type: model.type ?? inferType(model),
+      source: "remote",
+    }))
+    .filter((model) => model.id && model.type)
+    .filter((model) => !type || model.type === type);
+}
+
+function inferType(model) {
+  if (model.capabilities?.includes("video")) return "video";
+  if (model.capabilities?.includes("audio")) return "audio";
+  if (model.capabilities?.includes("image")) return "image";
+  return undefined;
+}

package/test/animation.test.js

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createAnimation } from "../src/animation.js";
+
+test("does not animate in json mode", () => {
+  let output = "";
+  const animation = createAnimation({
+    json: true,
+    stream: { isTTY: true, write: (chunk) => { output += chunk; } },
+  });
+
+  animation.start("image");
+  animation.stop();
+
+  assert.equal(output, "");
+});
+
+test("uses single log line when stderr is not a tty", () => {
+  let output = "";
+  const animation = createAnimation({
+    json: false,
+    stream: { isTTY: false, write: (chunk) => { output += chunk; } },
+  });
+
+  animation.start("video");
+  animation.stop();
+
+  assert.equal(output, "flatkey video generation started\n");
+});

package/test/api.test.js

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  FlatkeyError,
+  generateAudio,
+  generateImage,
+  generateVideo,
+  getCredits,
+  getModels,
+  getStatus,
+} from "../src/api.js";
+
+function fetchRecorder(responseBody = { ok: true }) {
+  const calls = [];
+  const fetch = async (url, init) => {
+    calls.push({ url, init });
+    return {
+      ok: true,
+      status: 200,
+      async json() {
+        return responseBody;
+      },
+    };
+  };
+  return { fetch, calls };
+}
+
+test("builds nano image request using gemini-style route", async () => {
+  const { fetch, calls } = fetchRecorder({ candidates: [] });
+
+  await generateImage({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    prompt: "poster",
+    fetch,
+  });
+
+  assert.equal(
+    calls[0].url,
+    "https://router.test/v1beta/models/nano-banana-pro-preview:generateContent?key=key",
+  );
+  assert.equal(calls[0].init.method, "POST");
+  assert.deepEqual(JSON.parse(calls[0].init.body), {
+    contents: [{ parts: [{ text: "poster" }] }],
+  });
+});
+
+test("builds OpenAI image request for gpt image models", async () => {
+  const { fetch, calls } = fetchRecorder({ data: [] });
+
+  await generateImage({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    model: "gpt-image-2",
+    prompt: "cover",
+    size: "1024x1024",
+    n: "2",
+    fetch,
+  });
+
+  assert.equal(calls[0].url, "https://router.test/v1/images/generations");
+  assert.equal(calls[0].init.headers.Authorization, "Bearer key");
+  assert.deepEqual(JSON.parse(calls[0].init.body), {
+    model: "gpt-image-2",
+    prompt: "cover",
+    size: "1024x1024",
+    n: 2,
+  });
+});
+
+test("builds video generation request", async () => {
+  const { fetch, calls } = fetchRecorder({ data: [] });
+
+  await generateVideo({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    model: "veo-3",
+    prompt: "walkthrough",
+    duration: "8",
+    aspect: "16:9",
+    fps: "24",
+    fetch,
+  });
+
+  assert.equal(calls[0].url, "https://router.test/v1/videos/generations");
+  assert.deepEqual(JSON.parse(calls[0].init.body), {
+    model: "veo-3",
+    prompt: "walkthrough",
+    duration: 8,
+    aspect: "16:9",
+    fps: 24,
+  });
+});
+
+test("builds audio generation request", async () => {
+  const { fetch, calls } = fetchRecorder({ data: [] });
+
+  await generateAudio({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    model: "tts-1",
+    prompt: "voiceover",
+    voice: "alloy",
+    format: "mp3",
+    fetch,
+  });
+
+  assert.equal(calls[0].url, "https://router.test/v1/audio/generations");
+  assert.deepEqual(JSON.parse(calls[0].init.body), {
+    model: "tts-1",
+    prompt: "voiceover",
+    voice: "alloy",
+    format: "mp3",
+  });
+});
+
+test("builds credits, status, and models requests", async () => {
+  const { fetch, calls } = fetchRecorder({});
+
+  await getCredits({ apiKey: "key", baseUrl: "https://router.test", fetch });
+  await getStatus({ apiKey: "key", baseUrl: "https://router.test", fetch });
+  await getModels({ apiKey: "key", baseUrl: "https://router.test", fetch });
+
+  assert.equal(calls[0].url, "https://router.test/v1/credits");
+  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");
+});
+
+test("throws FlatkeyError with API message on HTTP failure", async () => {
+  const fetch = async () => ({
+    ok: false,
+    status: 402,
+    async json() {
+      return { error: { message: "credits exhausted" } };
+    },
+  });
+
+  await assert.rejects(
+    () => getCredits({ apiKey: "key", baseUrl: "https://router.test", fetch }),
+    (error) => error instanceof FlatkeyError && /credits exhausted/.test(error.message),
+  );
+});

package/test/artifacts.test.js

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { persistArtifacts } from "../src/artifacts.js";
+
+test("saves OpenAI base64 image artifacts", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+
+  const artifacts = await persistArtifacts({
+    kind: "image",
+    response: { data: [{ b64_json: Buffer.from("png-bytes").toString("base64") }] },
+    outDir,
+  });
+
+  assert.equal(artifacts.length, 1);
+  assert.match(artifacts[0].path, /image-01\.png$/);
+  assert.equal(await readFile(artifacts[0].path, "utf8"), "png-bytes");
+});
+
+test("saves data url video artifacts with mime extension", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+
+  const artifacts = await persistArtifacts({
+    kind: "video",
+    response: {
+      data: [{ url: `data:video/mp4;base64,${Buffer.from("mp4-bytes").toString("base64")}` }],
+    },
+    outDir,
+  });
+
+  assert.match(artifacts[0].path, /video-01\.mp4$/);
+  assert.equal(await readFile(artifacts[0].path, "utf8"), "mp4-bytes");
+});
+
+test("preserves remote url artifacts without downloading", async () => {
+  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
+
+  const artifacts = await persistArtifacts({
+    kind: "audio",
+    response: { data: [{ url: "https://cdn.test/audio.mp3" }] },
+    outDir,
+  });
+
+  assert.deepEqual(artifacts, [{ url: "https://cdn.test/audio.mp3" }]);
+});

package/test/cli.test.js

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseArgv } from "../src/cli.js";
+
+test("parses image generation with prompt and json mode", () => {
+  const command = parseArgv(["image", "generate", "--prompt", "city at dawn", "--json"]);
+
+  assert.deepEqual(command, {
+    group: "image",
+    action: "generate",
+    options: {
+      prompt: "city at dawn",
+      json: true,
+    },
+  });
+});
+
+test("parses credits with json mode", () => {
+  const command = parseArgv(["credits", "--json"]);
+
+  assert.deepEqual(command, {
+    group: "credits",
+    action: undefined,
+    options: {
+      json: true,
+    },
+  });
+});
+
+test("parses ai help", () => {
+  const command = parseArgv(["help", "--ai"]);
+
+  assert.deepEqual(command, {
+    group: "help",
+    action: undefined,
+    options: {
+      ai: true,
+    },
+  });
+});
+
+test("rejects unknown commands", () => {
+  assert.throws(
+    () => parseArgv(["wat"]),
+    /Unknown command: wat/,
+  );
+});