@flatkey-ai/cli 0.1.5 → 0.1.7

package/README.md

@@ -7,6 +7,8 @@
 
 Creative generation from the terminal for media teams and AI agents. Generate images, videos, audio, and text through one Flatkey credit balance.
 
+Languages: [English](README.md) | [简体中文](docs/readme/README.zh-CN.md) | [日本語](docs/readme/README.ja-JP.md)
+
 Website: [flatkey.ai](https://flatkey.ai/?utm_source=github&utm_medium=readme&utm_campaign=flatkey_cli)
 
 ```bash
@@ -29,6 +31,21 @@ flatkey credits --json
 - Cross-platform npm package for macOS, Linux, and Windows.
 - Cool terminal progress animation for human runs; disabled in `--json` mode.
 
+## Product Comparison
+
+Flatkey is built for media teams that want programmatic generation without paying a premium for a closed creative suite or waiting in long queues. Higgsfield is strong for creator-facing workflows, and Dreamina/Jimeng has good ByteDance video models, but both can become expensive or slow once the workflow moves from manual creation to repeated AI-agent testing. In our testing, Dreamina/Jimeng video generation can wait up to 5 hours during peak time, which makes one-by-one prompt iteration impractical.
+
+| Need | Flatkey | Higgsfield | Dreamina / Jimeng |
+| --- | --- | --- | --- |
+| Cost for repeat testing | Flatkey token pricing is at least ~20% lower than comparable retail routes, and some modalities such as image can be ~40% lower. | Credit packages can be expensive once premium video/image models are used heavily. | Subscription credits can be cheaper in some local workflows, but API-style automation usually has plan and region constraints. |
+| Programmatic access | First-class CLI and API-router workflow. Designed for agents, scripts, and batch testing. | Strong product UI for creators; CLI-style automation is not the primary product promise. | CLI/API access is gated behind higher-tier setup in many workflows, not the default creator entry path. |
+| Queue / iteration speed | Built for fast CLI retries, `--dry-run`, local outputs, and unified model routing. | Good for polished creator workflows, but heavy credit usage makes broad testing costly. | Peak-time queues can block video iteration; we have observed waits up to 5 hours for a single video generation test. |
+| Modalities | Image, video, TTS, SFX, music, text, credits, status, and model discovery behind one Flatkey key. | Strong image/video creator stack and media tooling. | Strong ByteDance image/video models, especially Seedance/Dreamina-style workflows. |
+| Agent ergonomics | `--json`, `--output/-o`, `--dry-run`, `models`, `audio voices`, and predictable stdout/stderr. | More oriented around human creative workflows. | More oriented around app/product workflow than simple agent protocol. |
+| Best fit | Media teams building repeatable generation pipelines and AI-agent workflows. | Creators who want a polished visual production suite. | Teams already deep in CapCut/Dreamina/Jimeng ecosystem and willing to accept plan/queue tradeoffs. |
+
+In short: use Flatkey when the job is repeated media generation, cost-sensitive testing, and AI-agent automation. Use creator suites when you want their native editing UI more than a programmable router.
+
 ## Install
 
 ```bash
@@ -62,7 +79,7 @@ Or save it locally:
 flatkey onboard --api-key <key>
 ```
 
-Get a key from [flatkey.ai](https://flatkey.ai/?utm_source=github&utm_medium=readme&utm_campaign=flatkey_cli_auth).
+Create a key at [console.flatkey.ai/keys](https://console.flatkey.ai/keys), then pass it with `--api-key`.
 
 ## Commands
 
@@ -81,9 +98,14 @@ flatkey image generate \
 flatkey video generate \
   --prompt "8 second cinematic product reveal, glossy black background" \
   --model seedance2 \
+  --ratio 16:9 \
+  --resolution 720p \
   -o launch.mp4
 ```
 
+Video ratios: `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `1:1`.
+Video resolutions: `480p`, `720p`, `1080p`.
+
 ### Generate Audio
 
 Text to speech:
@@ -222,6 +244,10 @@ npm test
 node bin/flatkey.js --version
 ```
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=flatkey-ai/flatkey-cli&type=Date)](https://www.star-history.com/#flatkey-ai/flatkey-cli&Date)
+
 ## Links
 
 - Website: [flatkey.ai](https://flatkey.ai/?utm_source=github&utm_medium=readme&utm_campaign=flatkey_cli_links)

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
   "type": "module",
   "bin": {
     "flatkey": "bin/flatkey.js"
   },
+  "files": [
+    "bin",
+    "src"
+  ],
   "scripts": {
     "test": "node --test"
   },

package/src/api.js

@@ -1,5 +1,6 @@
 export const DEFAULT_BASE_URL = "https://router.flatkey.ai";
 export const DEFAULT_MODELS_BASE_URL = "https://console.flatkey.ai";
+export const DEFAULT_CONSOLE_URL = "https://console.flatkey.ai";
 
 export class FlatkeyError extends Error {
   constructor(message, { status } = {}) {
@@ -43,11 +44,24 @@ export function generateVideo(options) {
 }
 
 export function planVideoRequest(options) {
+  const ratio = validateOptionalValue(
+    optionValue(options, "ratio", "aspect"),
+    ["16:9", "9:16", "4:3", "3:4", "21:9", "1:1"],
+    "ratio",
+  );
+  const resolution = validateOptionalValue(
+    options.resolution,
+    ["480p", "720p", "1080p"],
+    "resolution",
+  );
   return planJsonPost(options, "/v1/video/generations", cleanObject({
     model: options.model ?? "veo-3",
     prompt: options.prompt,
     duration: parseOptionalInteger(options.duration),
-    aspect: options.aspect,
+    aspect: ratio,
+    ratio,
+    resolution,
+    quality: resolution,
     fps: parseOptionalInteger(options.fps),
   }));
 }
@@ -111,11 +125,17 @@ export function planTextRequest(options) {
 }
 
 export function getCredits(options) {
-  return requestJson(options, "/v1/credits");
+  return requestJson({
+    ...options,
+    baseUrl: options.baseUrl ?? DEFAULT_CONSOLE_URL,
+  }, "/v1/credits");
 }
 
 export function getStatus(options) {
-  return requestJson(options, "/v1/status");
+  return requestJson({
+    ...options,
+    baseUrl: options.baseUrl ?? DEFAULT_CONSOLE_URL,
+  }, "/v1/status");
 }
 
 export function getModels(options) {
@@ -125,6 +145,32 @@ export function getModels(options) {
   }, "/v1/available_models");
 }
 
+export async function createDeviceAuthorization(options) {
+  return requestJson({
+    ...options,
+    baseUrl: options.consoleUrl ?? DEFAULT_CONSOLE_URL,
+  }, "/api/cli/device_authorizations", {
+    method: "POST",
+    body: JSON.stringify({
+      client_name: options.clientName ?? "flatkey-cli",
+      client_version: options.clientVersion,
+      device_id: options.deviceId,
+    }),
+  });
+}
+
+export async function pollDeviceAuthorization(options) {
+  return requestJson({
+    ...options,
+    baseUrl: options.consoleUrl ?? DEFAULT_CONSOLE_URL,
+  }, "/api/cli/device_authorizations/token", {
+    method: "POST",
+    body: JSON.stringify({
+      device_code: options.deviceCode,
+    }),
+  });
+}
+
 async function postJson(options, path, payload) {
   return requestJsonFromPlan(options, planJsonPost(options, path, payload));
 }
@@ -223,6 +269,12 @@ function optionValue(options, ...keys) {
   return undefined;
 }
 
+function validateOptionalValue(value, allowed, name) {
+  if (value === undefined) return undefined;
+  if (allowed.includes(value)) return value;
+  throw new Error(`Invalid ${name}: ${value}. Allowed values: ${allowed.join(", ")}`);
+}
+
 function cleanObject(value) {
   return Object.fromEntries(
     Object.entries(value).filter(([, entry]) => entry !== undefined),
@@ -238,7 +290,16 @@ async function readJson(response) {
 }
 
 function extractErrorMessage(body, status) {
-  if (typeof body?.error?.message === "string") return body.error.message;
-  if (typeof body?.message === "string") return body.message;
+  const message = typeof body?.error?.message === "string"
+    ? body.error.message
+    : typeof body?.message === "string"
+      ? body.message
+      : undefined;
+  if (message === "Token not provided") return missingApiKeyMessage();
+  if (message) return message;
   return `Flatkey API request failed with HTTP ${status}`;
 }
+
+function missingApiKeyMessage() {
+  return "Missing Flatkey API key. Create one at https://console.flatkey.ai/keys, then run `flatkey onboard --api-key <key>` or set FLATKEY_API_KEY.";
+}

package/src/artifacts.js

@@ -1,4 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, extname, join } from "node:path";
 
 const DEFAULT_EXTENSIONS = {
@@ -25,6 +26,7 @@ export async function persistArtifacts({
   output,
   fetch: fetchImpl = fetch,
 }) {
+  output = expandHomePath(output);
   const items = extractItems(response);
   const artifacts = [];
   await mkdir(output ? dirname(output) : outDir, { recursive: true });
@@ -37,6 +39,13 @@ export async function persistArtifacts({
   return artifacts;
 }
 
+function expandHomePath(path) {
+  if (typeof path !== "string") return path;
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
 async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
   const dataUrl = getString(item, ["url", "data_url", "dataUrl"]);
   if (dataUrl?.startsWith("data:")) {

package/src/cli.js

@@ -3,31 +3,62 @@ const COMMANDS = new Set([
   "credits",
   "help",
   "image",
+  "login",
   "models",
   "onboard",
+  "logout",
+  "auth",
   "status",
   "text",
   "version",
   "video",
 ]);
 
-const GROUP_ACTIONS = new Set(["audio", "image", "text", "video"]);
+const GROUP_ACTIONS = new Set(["audio", "auth", "image", "text", "video"]);
 
 export function parseArgv(argv) {
   const [group, maybeAction, ...rest] = argv;
   if (!group) {
     return { group: "help", action: undefined, options: {} };
   }
+  if (group === "--help" || group === "-h") {
+    return { group: "help", action: undefined, options: {} };
+  }
   if (group === "--version" || group === "-v") {
     return { group: "version", action: undefined, options: {} };
   }
   if (!COMMANDS.has(group)) {
     throw new Error(`Unknown command: ${group}`);
   }
+  if (group === "help" && maybeAction && !maybeAction.startsWith("--")) {
+    return {
+      group: "help",
+      action: undefined,
+      options: { command: maybeAction, ...parseOptions(rest) },
+    };
+  }
 
   const hasAction = GROUP_ACTIONS.has(group);
+  if (hasAction && isHelpToken(maybeAction)) {
+    return { group, action: undefined, options: { help: true } };
+  }
+  if (!hasAction && isHelpToken(maybeAction)) {
+    return { group, action: undefined, options: { help: true } };
+  }
   const action = hasAction ? maybeAction : undefined;
   const optionTokens = hasAction ? rest : argv.slice(1);
+  const hasHelpOption = optionTokens.some((token) => token === "--help" || token === "-h")
+    || (optionTokens.length === 1 && optionTokens[0] === "help");
+  if (hasHelpOption) {
+    return {
+      group,
+      action,
+      options: {
+        ...parseOptions(optionTokens.filter((token) => token !== "help" && token !== "--help" && token !== "-h")),
+        help: true,
+      },
+    };
+  }
 
   return {
     group,
@@ -36,6 +67,10 @@ export function parseArgv(argv) {
   };
 }
 
+function isHelpToken(token) {
+  return token === "help" || token === "--help" || token === "-h";
+}
+
 function parseOptions(tokens) {
   const options = {};
   for (let index = 0; index < tokens.length; index += 1) {
@@ -66,6 +101,11 @@ function parseOptions(tokens) {
 
 export async function main(argv) {
   const command = parseArgv(argv);
+  if (command.options.help) {
+    const result = await runCommand(command);
+    process.stdout.write(`${formatHuman(result)}\n`);
+    return;
+  }
   if (command.group === "onboard") {
     const { writeConfig } = await import("./config.js");
     const configPath = await writeConfig({ apiKey: command.options.api_key });
@@ -86,9 +126,14 @@ export async function runCommand(command, deps = {}) {
   const stderr = deps.stderr ?? process.stderr;
 
   if (command.group === "help") {
-    const { getAiHelp, getHumanHelp } = await import("./help.js");
+    const { getAiHelp, getCommandHelp, getHumanHelp } = await import("./help.js");
+    if (command.options.command) return getCommandHelp(command.options.command);
     return command.options.ai ? getAiHelp() : getHumanHelp();
   }
+  if (command.options.help) {
+    const { getCommandHelp } = await import("./help.js");
+    return getCommandHelp(command.group, command.action);
+  }
   if (command.group === "version") {
     const version = await readPackageVersion();
     return command.options.json ? { version } : version;
@@ -98,6 +143,21 @@ export async function runCommand(command, deps = {}) {
     return handleModels(command, deps);
   }
 
+  if (command.group === "login") {
+    return handleLogin(command, { ...deps, stdout, stderr });
+  }
+
+  if (command.group === "logout") {
+    return handleLogout(command, deps);
+  }
+
+  if (command.group === "auth") {
+    if (command.action !== "status") {
+      throw new Error(`Unknown action for auth: ${command.action}`);
+    }
+    return handleAuthStatus(command, deps);
+  }
+
   if (command.group === "credits" || command.group === "status") {
     return handleUtility(command, deps);
   }
@@ -118,6 +178,150 @@ export async function runCommand(command, deps = {}) {
   throw new Error(`Unknown command: ${command.group}`);
 }
 
+async function handleLogin(command, deps) {
+  const { ensureDeviceId, writeAuthConfig } = await import("./config.js");
+  const { createDeviceAuthorization, pollDeviceAuthorization } = await import("./api.js");
+  const deviceId = await ensureDeviceId({ configDir: deps.configDir });
+  const version = await readPackageVersion();
+  const consoleUrl = command.options.console_url;
+  const authorization = await createDeviceAuthorization({
+    consoleUrl,
+    deviceId,
+    clientName: "flatkey-cli",
+    clientVersion: version,
+    fetch: deps.fetch,
+  });
+  const data = authorization?.data ?? authorization;
+  if (!data?.device_code || !data?.verification_uri_complete) {
+    throw new Error("Flatkey login failed: missing device authorization response.");
+  }
+
+  if (!command.options.json) {
+    deps.stdout?.write?.(`Open this URL to approve Flatkey CLI:\n${data.verification_uri_complete}\n\n`);
+  }
+  if (command.options.open !== false && command.options.no_open !== true) {
+    await openBrowser(data.verification_uri_complete, deps);
+  }
+
+  const initialIntervalMs = Math.max(Number(data.interval ?? 5), 5) * 1000;
+  const deadline = Date.now() + Math.max(Number(data.expires_in ?? 600), 1) * 1000;
+  const startedAt = Date.now();
+  while (Date.now() < deadline) {
+    await delay(nextLoginPollDelay(startedAt, initialIntervalMs), deps);
+    const poll = await pollDeviceAuthorization({
+      consoleUrl,
+      deviceCode: data.device_code,
+      fetch: deps.fetch,
+    });
+    const pollData = poll?.data ?? poll;
+    if (pollData?.status === "approved") {
+      if (!pollData.api_key) {
+        throw new Error("Flatkey login approved but no API key was returned.");
+      }
+      const configPath = await writeAuthConfig({
+        apiKey: pollData.api_key,
+        auth: {
+          deviceId,
+          userId: pollData.user_id,
+          tokenId: pollData.token_id,
+          loginAt: Math.floor(Date.now() / 1000),
+        },
+        configDir: deps.configDir,
+      });
+      return command.options.json
+        ? { success: true, configPath, tokenId: pollData.token_id, userId: pollData.user_id }
+        : `Flatkey CLI authorized. Saved config: ${configPath}`;
+    }
+    if (pollData?.status === "denied") {
+      throw new Error("Flatkey login denied.");
+    }
+    if (pollData?.status === "expired") {
+      throw new Error("Flatkey login expired. Run `flatkey login` again.");
+    }
+  }
+  throw new Error("Flatkey login timed out. Run `flatkey login` again.");
+}
+
+function nextLoginPollDelay(startedAt, initialIntervalMs) {
+  const elapsed = Date.now() - startedAt;
+  const base = elapsed < 30_000
+    ? initialIntervalMs
+    : elapsed < 120_000
+      ? Math.max(initialIntervalMs, 10_000)
+      : Math.max(initialIntervalMs, 15_000);
+  return base + Math.floor(Math.random() * 800);
+}
+
+async function delay(ms, deps = {}) {
+  const sleep = deps.sleep ?? ((duration) => new Promise((resolve) => setTimeout(resolve, duration)));
+  return sleep(ms);
+}
+
+async function openBrowser(url, deps = {}) {
+  if (deps.openBrowser) return deps.openBrowser(url);
+  const { spawn } = await import("node:child_process");
+  const platform = deps.platform ?? process.platform;
+  const command = platform === "darwin"
+    ? "open"
+    : platform === "win32"
+      ? "cmd"
+      : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.unref();
+  } catch {
+    // Printed URL is enough when open is unavailable.
+  }
+}
+
+function maskKey(key) {
+  if (!key) return "";
+  if (key.length <= 8) return `${key.slice(0, 2)}****${key.slice(-2)}`;
+  return `${key.slice(0, 6)}...${key.slice(-4)}`;
+}
+
+function formatAuthStatus(status) {
+  if (!status.authenticated) return "Not authenticated";
+  return `Authenticated via ${status.source}: ${status.key}`;
+}
+
+async function handleLogout(command, deps = {}) {
+  const { clearSavedApiKey } = await import("./config.js");
+  const configPath = await clearSavedApiKey({ configDir: deps.configDir });
+  return command.options.json
+    ? { success: true, configPath }
+    : `Removed saved Flatkey API key from ${configPath}`;
+}
+
+async function handleAuthStatus(command, deps) {
+  const { readConfig, resolveApiKey } = await import("./config.js");
+  const saved = await readConfig(deps.configDir);
+  let apiKey;
+  try {
+    apiKey = await resolveApiKey({
+      apiKey: command.options.api_key,
+      env: deps.env ?? process.env,
+      configDir: deps.configDir,
+    });
+  } catch {
+    apiKey = "";
+  }
+  const status = {
+    authenticated: Boolean(apiKey),
+    source: command.options.api_key
+      ? "option"
+      : (deps.env ?? process.env).FLATKEY_API_KEY
+        ? "env"
+        : saved?.apiKey
+          ? "config"
+          : "none",
+    key: maskKey(apiKey),
+    auth: saved?.auth ?? null,
+  };
+  return command.options.json ? status : formatAuthStatus(status);
+}
+
 async function handleGenerate(command, deps) {
   const { resolveApiKey } = await import("./config.js");
   const {
@@ -191,12 +395,33 @@ async function handleGenerate(command, deps) {
       output: command.options.output,
       fetch: deps.fetch,
     });
-    return { kind: command.group, artifacts, response };
+    return { kind: command.group, artifacts, response: scrubArtifactResponse(response) };
   } finally {
     animation.stop();
   }
 }
 
+function scrubArtifactResponse(value) {
+  if (Array.isArray(value)) return value.map(scrubArtifactResponse);
+  if (!value || typeof value !== "object") {
+    if (typeof value === "string" && value.startsWith("data:")) return "<artifact omitted>";
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => {
+      if (["b64_json", "base64", "data"].includes(key) && typeof entry === "string") {
+        return [key, "<artifact omitted>"];
+      }
+      if (["url", "data_url", "dataUrl"].includes(key)
+        && typeof entry === "string"
+        && entry.startsWith("data:")) {
+        return [key, "<artifact omitted>"];
+      }
+      return [key, scrubArtifactResponse(entry)];
+    }),
+  );
+}
+
 async function handleVoices(command, deps) {
   const { resolveApiKey } = await import("./config.js");
   const { getVoices } = await import("./api.js");
@@ -220,6 +445,7 @@ function extractText(response) {
 
 async function writeTextOutput(text, output) {
   if (!output) return undefined;
+  output = await expandHomePath(output);
   const { mkdir, writeFile } = await import("node:fs/promises");
   const { dirname } = await import("node:path");
   await mkdir(dirname(output), { recursive: true });
@@ -227,6 +453,15 @@ async function writeTextOutput(text, output) {
   return output;
 }
 
+async function expandHomePath(path) {
+  if (typeof path !== "string") return path;
+  if (path !== "~" && !path.startsWith("~/")) return path;
+  const { homedir } = await import("node:os");
+  const { join } = await import("node:path");
+  if (path === "~") return homedir();
+  return join(homedir(), path.slice(2));
+}
+
 function redactRequest(request) {
   return {
     ...request,

package/src/config.js

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -22,13 +23,13 @@ export async function resolveApiKey({
   if (saved?.apiKey) return saved.apiKey;
 
   throw new Error(
-    "Missing Flatkey API key. Run `flatkey onboard --api-key <key>` or set FLATKEY_API_KEY.",
+    "Missing Flatkey API key. Create one at https://console.flatkey.ai/keys, then 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.");
+  if (typeof apiKey !== "string" || apiKey.trim() === "") {
+    throw new Error("Missing --api-key value. Create a key at https://console.flatkey.ai/keys, then run `flatkey onboard --api-key <key>`.");
   }
 
   await mkdir(configDir, { recursive: true });
@@ -44,6 +45,62 @@ export async function writeConfig({ apiKey, configDir = getDefaultConfigDir() })
   return configPath;
 }
 
+export async function writeAuthConfig({
+  apiKey,
+  auth,
+  configDir = getDefaultConfigDir(),
+}) {
+  if (typeof apiKey !== "string" || apiKey.trim() === "") {
+    throw new Error("Missing API key from Flatkey login response.");
+  }
+  const saved = await readSavedConfig(configDir) ?? {};
+  const next = {
+    ...saved,
+    apiKey,
+    auth: {
+      ...(saved.auth ?? {}),
+      ...auth,
+      type: "device",
+    },
+  };
+  await mkdir(configDir, { recursive: true });
+  const configPath = getConfigPath(configDir);
+  await writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  try {
+    await chmod(configPath, 0o600);
+  } catch (error) {
+    if (process.platform !== "win32") throw error;
+  }
+  return configPath;
+}
+
+export async function ensureDeviceId({ configDir = getDefaultConfigDir() } = {}) {
+  const saved = await readSavedConfig(configDir);
+  if (typeof saved?.auth?.deviceId === "string" && saved.auth.deviceId) {
+    return saved.auth.deviceId;
+  }
+  return randomUUID();
+}
+
+export async function clearSavedApiKey({ configDir = getDefaultConfigDir() } = {}) {
+  const saved = await readSavedConfig(configDir);
+  if (!saved) return getConfigPath(configDir);
+  const next = { ...saved };
+  delete next.apiKey;
+  await mkdir(configDir, { recursive: true });
+  const configPath = getConfigPath(configDir);
+  await writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  return configPath;
+}
+
+export async function readConfig(configDir = getDefaultConfigDir()) {
+  return readSavedConfig(configDir);
+}
+
 async function readSavedConfig(configDir) {
   try {
     return JSON.parse(await readFile(getConfigPath(configDir), "utf8"));