@flatkey-ai/cli 0.1.6 → 0.1.8

package/package.json

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

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 } = {}) {
@@ -124,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) {
@@ -138,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));
 }
@@ -257,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,15 +3,40 @@ 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"]);
+const GLOBAL_OPTIONS = new Set(["api_key", "base_url", "dry_run", "help", "json", "output", "out"]);
+const COMMAND_OPTIONS = {
+  "audio generate": new Set(["model", "prompt", "similarity_boost", "stability", "style", "voice_id"]),
+  "audio music": new Set(["music_length_ms", "prompt"]),
+  "audio sfx": new Set(["duration", "prompt"]),
+  "audio voices": new Set([]),
+  "auth status": new Set([]),
+  credits: new Set([]),
+  help: new Set(["ai", "command"]),
+  image: new Set([]),
+  "image generate": new Set(["model", "n", "prompt", "quality", "size"]),
+  login: new Set(["console_url", "no_open", "open"]),
+  logout: new Set([]),
+  models: new Set(["type"]),
+  onboard: new Set(["api_key"]),
+  status: new Set([]),
+  text: new Set([]),
+  "text generate": new Set(["model", "prompt"]),
+  version: new Set([]),
+  video: new Set([]),
+  "video generate": new Set(["aspect", "duration", "fps", "model", "prompt", "ratio", "resolution"]),
+};
 
 export function parseArgv(argv) {
   const [group, maybeAction, ...rest] = argv;
@@ -28,11 +53,11 @@ export function parseArgv(argv) {
     throw new Error(`Unknown command: ${group}`);
   }
   if (group === "help" && maybeAction && !maybeAction.startsWith("--")) {
-    return {
+    return validateCommandOptions({
       group: "help",
       action: undefined,
       options: { command: maybeAction, ...parseOptions(rest) },
-    };
+    });
   }
 
   const hasAction = GROUP_ACTIONS.has(group);
@@ -47,21 +72,21 @@ export function parseArgv(argv) {
   const hasHelpOption = optionTokens.some((token) => token === "--help" || token === "-h")
     || (optionTokens.length === 1 && optionTokens[0] === "help");
   if (hasHelpOption) {
-    return {
+    return validateCommandOptions({
       group,
       action,
       options: {
         ...parseOptions(optionTokens.filter((token) => token !== "help" && token !== "--help" && token !== "-h")),
         help: true,
       },
-    };
+    });
   }
 
-  return {
+  return validateCommandOptions({
     group,
     action,
     options: parseOptions(optionTokens),
-  };
+  });
 }
 
 function isHelpToken(token) {
@@ -96,6 +121,20 @@ function parseOptions(tokens) {
   return options;
 }
 
+function validateCommandOptions(command) {
+  const key = command.action ? `${command.group} ${command.action}` : command.group;
+  const allowed = COMMAND_OPTIONS[key] ?? new Set();
+  for (const option of Object.keys(command.options)) {
+    if (GLOBAL_OPTIONS.has(option) || allowed.has(option)) continue;
+    const flag = `--${option.replaceAll("_", "-")}`;
+    const helpCommand = command.action
+      ? `flatkey ${command.group} ${command.action} --help`
+      : `flatkey ${command.group} --help`;
+    throw new Error(`Unknown option ${flag} for flatkey ${key}. Run \`${helpCommand}\` to see supported options.`);
+  }
+  return command;
+}
+
 export async function main(argv) {
   const command = parseArgv(argv);
   if (command.options.help) {
@@ -140,6 +179,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);
   }
@@ -160,6 +214,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 {
@@ -233,12 +431,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");
@@ -262,6 +481,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 });
@@ -269,6 +489,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";
 
@@ -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"));

package/src/help.js

@@ -2,7 +2,8 @@ export function getAiHelp() {
   return `Flatkey CLI protocol for agents
 
 Setup:
-- Prefer env: FLATKEY_API_KEY=<key>
+- Prefer browser auth: flatkey login
+- Or env: FLATKEY_API_KEY=<key>
 - Create a key at https://console.flatkey.ai/keys
 - Or save key: flatkey onboard --api-key <key>
 - Use --json for machine-readable output.
@@ -23,6 +24,9 @@ Commands:
 - flatkey credits --json
 - flatkey status --json
 - flatkey models --json [--type image|video|audio|text]
+- flatkey login [--no-open] [--console-url <url>]
+- flatkey logout
+- flatkey auth status --json
 - flatkey help --ai
 
 Environment:
@@ -41,6 +45,9 @@ export function getHumanHelp() {
   return `Usage: flatkey <command> [options]
 
 Commands:
+  login                         Authorize CLI in browser
+  logout                        Remove saved Flatkey API key
+  auth status                    Show saved auth state
   onboard --api-key <key>        Save Flatkey API key from https://console.flatkey.ai/keys
   image generate --prompt <txt>  Generate image
   video generate --prompt <txt>  Generate video
@@ -58,6 +65,7 @@ Global options:
   --json                         Print machine-readable JSON
   --output, -o <file>             Write generated output to a local file
   --base-url <url>               Override Flatkey router URL
+  --console-url <url>            Override Flatkey console URL for login
 
 Video options:
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
@@ -110,6 +118,17 @@ Options:
   --json                         Print machine-readable JSON`,
   credits: `Usage: flatkey credits [options]
 
+Options:
+  --json                         Print machine-readable JSON`,
+  auth: `Usage: flatkey auth <action> [options]
+
+Actions:
+  status                         Show saved auth state
+
+Options:
+  --json                         Print machine-readable JSON`,
+  "auth status": `Usage: flatkey auth status [options]
+
 Options:
   --json                         Print machine-readable JSON`,
   help: `Usage: flatkey help [command] [options]
@@ -138,6 +157,16 @@ Options:
 
 Options:
   --type <type>                  Filter: image, video, audio, or text
+  --json                         Print machine-readable JSON`,
+  login: `Usage: flatkey login [options]
+
+Options:
+  --no-open                      Print approval URL without opening a browser
+  --console-url <url>            Override Flatkey console URL
+  --json                         Print machine-readable JSON`,
+  logout: `Usage: flatkey logout [options]
+
+Options:
   --json                         Print machine-readable JSON`,
   onboard: `Usage: flatkey onboard --api-key <key>