@flatkey-ai/cli 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flatkey AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,50 @@
-# @flatkey-ai/cli
+# Flatkey CLI
 
-Unified Flatkey CLI for media workers. Generate images, videos, and audio through Flatkey credits.
+[![npm version](https://img.shields.io/npm/v/@flatkey-ai/cli.svg)](https://www.npmjs.com/package/@flatkey-ai/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@flatkey-ai/cli.svg)](https://www.npmjs.com/package/@flatkey-ai/cli)
+[![Publish npm](https://github.com/flatkey-ai/flatkey-cli/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/flatkey-ai/flatkey-cli/actions/workflows/npm-publish.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+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
+npm install -g @flatkey-ai/cli
+export FLATKEY_API_KEY=<your-flatkey-api-key>
+
+flatkey image generate --prompt "editorial cover, neon city at dawn" -o cover.png
+flatkey video generate --prompt "cinematic product launch clip" --model seedance2 -o launch.mp4
+flatkey audio generate --prompt "你好，这是 Flatkey 的配音测试" -o speech.mp3
+flatkey models --json
+flatkey credits --json
+```
+
+## Why Flatkey CLI
+
+- One CLI for image, video, audio, and text generation.
+- One `FLATKEY_API_KEY`, one credit balance.
+- Agent-friendly JSON mode with clean stdout.
+- Local output support with `--output` / `-o`.
+- 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
 
@@ -8,46 +52,204 @@ Unified Flatkey CLI for media workers. Generate images, videos, and audio throug
 npm install -g @flatkey-ai/cli
 ```
 
-Or run without installing:
+Run without installing:
 
 ```bash
 npx @flatkey-ai/cli help --ai
 ```
 
-## Auth
+Check local version:
 
 ```bash
-flatkey onboard --api-key <key>
+flatkey --version
+flatkey -v
 ```
 
-Or use:
+## Auth
+
+Use an environment variable:
 
 ```bash
 export FLATKEY_API_KEY=<key>
 ```
 
+Or save it locally:
+
+```bash
+flatkey onboard --api-key <key>
+```
+
+Create a key at [console.flatkey.ai/keys](https://console.flatkey.ai/keys), then pass it with `--api-key`.
+
 ## Commands
 
+### Generate Image
+
+```bash
+flatkey image generate \
+  --prompt "magazine cover, reflective typography, studio lighting" \
+  --model gpt-image-2 \
+  -o cover.png
+```
+
+### Generate Video
+
+```bash
+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:
+
+```bash
+flatkey audio generate \
+  --prompt "你好，这是 Flatkey 网关的语音测试。" \
+  --voice-id EXAVITQu4vr4xnSDxMaL \
+  --model eleven_multilingual_v2 \
+  --stability 0.5 \
+  --similarity-boost 0.75 \
+  --style 0 \
+  -o speech.mp3
+```
+
+List voices:
+
+```bash
+flatkey audio voices --json
+```
+
+Sound effects:
+
+```bash
+flatkey audio sfx \
+  --prompt "glass shattering on the floor" \
+  --duration 3 \
+  -o sfx.mp3
+```
+
+Music:
+
+```bash
+flatkey audio music \
+  --prompt "calm ambient piano, sad mood" \
+  --music-length-ms 10000 \
+  -o music.mp3
+```
+
+### Generate Text
+
+```bash
+flatkey text generate \
+  --prompt "write 5 sharp headlines for a creator tool launch" \
+  --model gpt-5.5 \
+  -o headlines.txt
+```
+
+### Credits, Status, Models
+
 ```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
+flatkey models --type image --json
+flatkey help --ai
+```
+
+## Models
+
+Live model list:
+
+```bash
+flatkey models --json
+```
+
+Useful current defaults:
+
+| Type | Models |
+| --- | --- |
+| Image | `gpt-image-2`, `nano-banana-pro-preview`, Gemini image models |
+| Video | `seedance2`, `veo-3`, `veo-3-fast` |
+| Audio | `eleven_multilingual_v2`, ElevenLabs voices, sound effects, music |
+| Text | `gpt-5.5`, Claude, Gemini, GLM, Grok models |
+
+`models` reads from the Flatkey console model registry. Generation calls use the Flatkey router.
+
+## Agent Protocol
+
+Use this when wiring Flatkey into Codex, Claude Code, Cursor, or other agents:
+
+```bash
 flatkey help --ai
 ```
 
-Default router: `https://router.flatkey.ai`.
+Agent rules:
+
+- Prefer `FLATKEY_API_KEY`.
+- Always pass `--json` for machine-readable output.
+- Use `--output` / `-o` when the generated file path matters.
+- Call `flatkey models --json` before choosing a model.
+- Call `flatkey audio voices --json` before choosing a TTS `voice_id`.
+- Use `--dry-run` to inspect request shape without spending credits.
+
+Example dry run:
+
+```bash
+flatkey video generate \
+  --prompt "fashion campaign hero shot" \
+  --model seedance2 \
+  --dry-run \
+  --json
+```
+
+## Routing
+
+- Generation router: `https://router.flatkey.ai`
+- Model registry: `https://console.flatkey.ai/v1/available_models`
+- Voice registry: `https://router.flatkey.ai/v1/voices`
+
+Override router only when developing or testing:
+
+```bash
+flatkey image generate --prompt "test" --base-url http://127.0.0.1:3000 --json
+```
 
 ## Release Channels
 
-Primary release is npm package `@flatkey-ai/cli`.
+Primary release:
+
+- npm package: [`@flatkey-ai/cli`](https://www.npmjs.com/package/@flatkey-ai/cli)
 
 Planned wrappers:
 
 - Homebrew formula.
 - Debian `.deb` package for apt-based install.
 - Windows MSI package.
+
+## Development
+
+```bash
+git clone https://github.com/flatkey-ai/flatkey-cli.git
+cd flatkey-cli
+npm install
+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)
+- npm: [`@flatkey-ai/cli`](https://www.npmjs.com/package/@flatkey-ai/cli)
+- Issues: [github.com/flatkey-ai/flatkey-cli/issues](https://github.com/flatkey-ai/flatkey-cli/issues)

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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

@@ -43,28 +43,75 @@ 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),
   }));
 }
 
 export function generateAudio(options) {
-  return requestJsonFromPlan(options, planAudioRequest(options));
+  return requestBinaryArtifactFromPlan(options, planAudioRequest(options));
 }
 
 export function planAudioRequest(options) {
-  return planJsonPost(options, "/v1/audio/generations", cleanObject({
-    model: options.model ?? "tts-1",
+  const voiceId = optionValue(options, "voiceId", "voice_id") ?? "EXAVITQu4vr4xnSDxMaL";
+  return planJsonPost(options, `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, cleanObject({
+    text: options.text ?? options.prompt,
+    model_id: options.model ?? options.model_id ?? "eleven_multilingual_v2",
+    voice_settings: cleanObject({
+      stability: parseOptionalFloat(options.stability),
+      similarity_boost: parseOptionalFloat(optionValue(options, "similarityBoost", "similarity_boost")),
+      style: parseOptionalFloat(options.style),
+    }),
+  }));
+}
+
+export function generateAudioSfx(options) {
+  return requestBinaryArtifactFromPlan(options, planAudioSfxRequest(options));
+}
+
+export function planAudioSfxRequest(options) {
+  return planJsonPost(options, "/v1/sound-generation", cleanObject({
+    text: options.text ?? options.prompt,
+    duration_seconds: parseOptionalFloat(optionValue(options, "durationSeconds", "duration_seconds", "duration")),
+  }));
+}
+
+export function generateAudioMusic(options) {
+  return requestBinaryArtifactFromPlan(options, planAudioMusicRequest(options));
+}
+
+export function planAudioMusicRequest(options) {
+  return planJsonPost(options, "/v1/music", cleanObject({
     prompt: options.prompt,
-    voice: options.voice,
-    format: options.format,
+    music_length_ms: parseOptionalInteger(optionValue(options, "musicLengthMs", "music_length_ms")),
   }));
 }
 
+export function getVoices(options) {
+  return requestJson(options, "/v1/voices");
+}
+
+export function planVoicesRequest(options) {
+  return planRequest(options, "/v1/voices");
+}
+
 export function generateText(options) {
   return requestJsonFromPlan(options, planTextRequest(options));
 }
@@ -128,6 +175,24 @@ async function requestJsonFromPlan(options, plan) {
   return body;
 }
 
+async function requestBinaryArtifactFromPlan(options, plan) {
+  const fetchImpl = options.fetch ?? fetch;
+  const response = await fetchImpl(plan.url, {
+    method: plan.method,
+    headers: plan.headers,
+    body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
+  });
+  if (!response.ok) {
+    const body = await readJson(response);
+    throw new FlatkeyError(extractErrorMessage(body, response.status), {
+      status: response.status,
+    });
+  }
+  return {
+    data: [{ data: Buffer.from(await response.arrayBuffer()).toString("base64") }],
+  };
+}
+
 async function requestJson(options, path, init = {}) {
   return requestJsonFromPlan(options, planRequest(options, path, {
     method: init.method ?? "GET",
@@ -159,6 +224,24 @@ function parseOptionalInteger(value) {
   return Number.parseInt(value, 10);
 }
 
+function parseOptionalFloat(value) {
+  if (value === undefined) return undefined;
+  return Number.parseFloat(value);
+}
+
+function optionValue(options, ...keys) {
+  for (const key of keys) {
+    if (options[key] !== undefined) return options[key];
+  }
+  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),

package/src/cli.js

@@ -18,16 +18,44 @@ export function parseArgv(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 +64,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 +98,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 +123,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;
@@ -103,7 +145,13 @@ export async function runCommand(command, deps = {}) {
   }
 
   if (["image", "video", "audio", "text"].includes(command.group)) {
-    if (command.action !== "generate") {
+    if (command.group === "audio" && command.action === "voices") {
+      return handleVoices(command, deps);
+    }
+    const validAction = command.group === "audio"
+      ? ["generate", "sfx", "music"].includes(command.action)
+      : command.action === "generate";
+    if (!validAction) {
       throw new Error(`Unknown action for ${command.group}: ${command.action}`);
     }
     return handleGenerate(command, { ...deps, stdout, stderr });
@@ -116,10 +164,14 @@ async function handleGenerate(command, deps) {
   const { resolveApiKey } = await import("./config.js");
   const {
     generateAudio,
+    generateAudioMusic,
+    generateAudioSfx,
     generateImage,
     generateText,
     generateVideo,
+    planAudioMusicRequest,
     planAudioRequest,
+    planAudioSfxRequest,
     planImageRequest,
     planTextRequest,
     planVideoRequest,
@@ -144,7 +196,11 @@ async function handleGenerate(command, deps) {
       : command.group === "video"
         ? planVideoRequest(options)
         : command.group === "audio"
-          ? planAudioRequest(options)
+          ? command.action === "sfx"
+            ? planAudioSfxRequest(options)
+            : command.action === "music"
+              ? planAudioMusicRequest(options)
+              : planAudioRequest(options)
           : planTextRequest(options);
     return { dryRun: true, kind: command.group, request: redactRequest(request) };
   }
@@ -159,7 +215,11 @@ async function handleGenerate(command, deps) {
       : command.group === "video"
         ? await generateVideo(options)
         : command.group === "audio"
-          ? await generateAudio(options)
+          ? command.action === "sfx"
+            ? await generateAudioSfx(options)
+            : command.action === "music"
+              ? await generateAudioMusic(options)
+              : await generateAudio(options)
           : await generateText(options);
     if (command.group === "text") {
       const text = extractText(response);
@@ -179,6 +239,20 @@ async function handleGenerate(command, deps) {
   }
 }
 
+async function handleVoices(command, deps) {
+  const { resolveApiKey } = await import("./config.js");
+  const { getVoices } = await import("./api.js");
+  const apiKey = await resolveApiKey({
+    apiKey: command.options.api_key,
+    env: deps.env ?? process.env,
+  });
+  return getVoices({
+    apiKey,
+    baseUrl: command.options.base_url,
+    fetch: deps.fetch,
+  });
+}
+
 function extractText(response) {
   return response?.choices?.[0]?.message?.content
     ?? response?.output_text

package/src/config.js

@@ -22,13 +22,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 });