@flatkey-ai/cli 0.1.3 → 0.1.5

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Report a Flatkey CLI bug.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Paste the command. Redact API keys.
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: Paste relevant stdout/stderr. Redact secrets.
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Run `flatkey --version`.
+      placeholder: "0.1.4"
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I removed API keys and secrets from this report.
+          required: true
+        - label: I tried the command again with `--dry-run` when applicable.
+          required: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature request
+description: Request a Flatkey CLI feature.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What workflow should be easier?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What command or behavior do you want?
+      render: bash
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - image
+        - video
+        - audio
+        - text
+        - models
+        - credits/status
+        - packaging
+        - docs
+        - other

package/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+- 
+
+## Test
+
+```bash
+npm test
+```
+
+## Notes
+
+- No API keys or generated media committed.

package/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for improving Flatkey CLI.
+
+## Setup
+
+```bash
+git clone https://github.com/flatkey-ai/flatkey-cli.git
+cd flatkey-cli
+npm install
+npm test
+```
+
+## Local CLI
+
+```bash
+node bin/flatkey.js --version
+node bin/flatkey.js help --ai
+node bin/flatkey.js image generate --prompt "test" --dry-run --json
+```
+
+## Tests
+
+Run all tests before opening a PR:
+
+```bash
+npm test
+```
+
+Live tests require `FLATKEY_API_KEY` and can spend credits. Keep routine tests mocked or `--dry-run`.
+
+## Pull Requests
+
+- Keep changes small and focused.
+- Add or update tests for behavior changes.
+- Do not commit API keys, generated media, or local config.
+- Use `--dry-run` examples when possible.

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,33 @@
-# @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.
+
+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.
 
 ## Install
 
@@ -8,46 +35,195 @@ 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>
+```
+
+Get a key from [flatkey.ai](https://flatkey.ai/?utm_source=github&utm_medium=readme&utm_campaign=flatkey_cli_auth).
+
 ## 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 \
+  -o launch.mp4
+```
+
+### 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
+```
+
+## 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/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+## Reporting
+
+Please do not open public issues for security vulnerabilities.
+
+Report security concerns through Flatkey support at [flatkey.ai](https://flatkey.ai/?utm_source=github&utm_medium=security&utm_campaign=flatkey_cli).
+
+## API Keys
+
+- Prefer `FLATKEY_API_KEY` for automation.
+- Never commit API keys.
+- Rotate keys if they appear in logs, screenshots, shell history, or public CI.

package/flatkey-output/audio-01.mp3

@@ -0,0 +1 @@
+audio-file

package/package.json

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

package/src/api.js

@@ -53,18 +53,52 @@ export function planVideoRequest(options) {
 }
 
 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 +162,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 +211,18 @@ 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 cleanObject(value) {
   return Object.fromEntries(
     Object.entries(value).filter(([, entry]) => entry !== undefined),

package/src/cli.js

@@ -18,6 +18,9 @@ export function parseArgv(argv) {
   if (!group) {
     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}`);
   }
@@ -87,7 +90,8 @@ export async function runCommand(command, deps = {}) {
     return command.options.ai ? getAiHelp() : getHumanHelp();
   }
   if (command.group === "version") {
-    return { version: await readPackageVersion() };
+    const version = await readPackageVersion();
+    return command.options.json ? { version } : version;
   }
 
   if (command.group === "models") {
@@ -99,7 +103,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 });
@@ -112,10 +122,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,
@@ -140,7 +154,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) };
   }
@@ -155,7 +173,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);
@@ -175,6 +197,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/help.js

@@ -14,7 +14,10 @@ JSON mode:
 Commands:
 - 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 audio generate --prompt "<text>" --json [--voice-id <voice_id>] [--model eleven_multilingual_v2] [--output speech.mp3]
+- flatkey audio sfx --prompt "<sound>" --json [--duration <seconds>] [--output sfx.mp3]
+- flatkey audio music --prompt "<music prompt>" --json [--music-length-ms <ms>] [--output music.mp3]
+- flatkey audio voices --json
 - flatkey text generate --prompt "<prompt>" --json [--model gpt-5.5] [--output text.txt]
 - flatkey credits --json
 - flatkey status --json
@@ -28,6 +31,7 @@ Environment:
 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.
+- Unknown voice: run flatkey audio voices --json, then retry with a listed voice_id.
 - API failure: inspect stderr JSON or HTTP message, then retry only after fixing request or credits.
 `;
 }
@@ -39,7 +43,10 @@ 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
+  audio generate --prompt <txt>  Generate speech with ElevenLabs voices
+  audio sfx --prompt <txt>       Generate sound effects
+  audio music --prompt <txt>     Generate music
+  audio voices                   List available voices
   text generate --prompt <txt>   Generate text
   credits                        Show remaining credits
   status                         Show usage/status

package/src/models.js

@@ -6,8 +6,11 @@ const BUNDLED_MODELS = [
   { 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" },
+  { id: "eleven_multilingual_v2", type: "audio" },
+  { id: "eleven_turbo_v2_5", type: "audio" },
+  { id: "eleven_flash_v2_5", type: "audio" },
+  { id: "sound-generation", type: "audio" },
+  { id: "music", type: "audio" },
 ];
 
 export function getBundledModels(type) {

package/test/api.test.js

@@ -11,7 +11,10 @@ import {
   getModels,
   getStatus,
   planImageRequest,
+  planAudioMusicRequest,
   planTextRequest,
+  planAudioSfxRequest,
+  planVoicesRequest,
   planVideoRequest,
 } from "../src/api.js";
 
@@ -22,6 +25,9 @@ function fetchRecorder(responseBody = { ok: true }) {
     return {
       ok: true,
       status: 200,
+      async arrayBuffer() {
+        return Buffer.from("binary");
+      },
       async json() {
         return responseBody;
       },
@@ -138,20 +144,64 @@ test("builds audio generation request", async () => {
   await generateAudio({
     apiKey: "key",
     baseUrl: "https://router.test",
-    model: "tts-1",
+    model: "eleven_multilingual_v2",
     prompt: "voiceover",
-    voice: "alloy",
-    format: "mp3",
+    voiceId: "voice-123",
+    stability: "0.5",
+    similarityBoost: "0.75",
+    style: "0",
     fetch,
   });
 
-  assert.equal(calls[0].url, "https://router.test/v1/audio/generations");
+  assert.equal(calls[0].url, "https://router.test/v1/text-to-speech/voice-123");
   assert.deepEqual(JSON.parse(calls[0].init.body), {
-    model: "tts-1",
-    prompt: "voiceover",
-    voice: "alloy",
-    format: "mp3",
+    text: "voiceover",
+    model_id: "eleven_multilingual_v2",
+    voice_settings: {
+      stability: 0.5,
+      similarity_boost: 0.75,
+      style: 0,
+    },
+  });
+});
+
+test("builds audio sfx, music, and voices requests", () => {
+  assert.equal(planAudioSfxRequest({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    prompt: "glass shattering",
+    duration: "3",
+  }).url, "https://router.test/v1/sound-generation");
+  assert.deepEqual(planAudioSfxRequest({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    prompt: "glass shattering",
+    duration: "3",
+  }).body, {
+    text: "glass shattering",
+    duration_seconds: 3,
   });
+
+  assert.equal(planAudioMusicRequest({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    prompt: "calm ambient piano",
+    musicLengthMs: "10000",
+  }).url, "https://router.test/v1/music");
+  assert.deepEqual(planAudioMusicRequest({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+    prompt: "calm ambient piano",
+    musicLengthMs: "10000",
+  }).body, {
+    prompt: "calm ambient piano",
+    music_length_ms: 10000,
+  });
+
+  assert.equal(planVoicesRequest({
+    apiKey: "key",
+    baseUrl: "https://router.test",
+  }).url, "https://router.test/v1/voices");
 });
 
 test("builds credits, status, and models requests", async () => {

package/test/cli.test.js

@@ -63,6 +63,44 @@ test("parses output aliases", () => {
   );
 });
 
+test("parses audio voice generation controls", () => {
+  const command = parseArgv([
+    "audio",
+    "generate",
+    "--prompt",
+    "hello",
+    "--voice-id",
+    "voice-123",
+    "--stability",
+    "0.5",
+    "--similarity-boost",
+    "0.75",
+    "--style",
+    "0",
+    "-o",
+    "speech.mp3",
+  ]);
+
+  assert.deepEqual(command, {
+    group: "audio",
+    action: "generate",
+    options: {
+      prompt: "hello",
+      voice_id: "voice-123",
+      stability: "0.5",
+      similarity_boost: "0.75",
+      style: "0",
+      output: "speech.mp3",
+    },
+  });
+});
+
+test("parses audio sfx, music, and voices actions", () => {
+  assert.equal(parseArgv(["audio", "sfx", "--prompt", "glass", "--duration", "3"]).action, "sfx");
+  assert.equal(parseArgv(["audio", "music", "--prompt", "piano", "--music-length-ms", "10000"]).action, "music");
+  assert.equal(parseArgv(["audio", "voices", "--json"]).action, "voices");
+});
+
 test("parses ai help", () => {
   const command = parseArgv(["help", "--ai"]);
 
@@ -75,6 +113,19 @@ test("parses ai help", () => {
   });
 });
 
+test("parses global version aliases", () => {
+  assert.deepEqual(parseArgv(["--version"]), {
+    group: "version",
+    action: undefined,
+    options: {},
+  });
+  assert.deepEqual(parseArgv(["-v"]), {
+    group: "version",
+    action: undefined,
+    options: {},
+  });
+});
+
 test("rejects unknown commands", () => {
   assert.throws(
     () => parseArgv(["wat"]),
@@ -85,7 +136,8 @@ test("rejects unknown commands", () => {
 test("version command matches package version", async () => {
   const pkg = JSON.parse(await (await import("node:fs/promises")).readFile("package.json", "utf8"));
 
-  assert.deepEqual(await runCommand({ group: "version", options: {} }), {
+  assert.equal(await runCommand({ group: "version", options: {} }), pkg.version);
+  assert.deepEqual(await runCommand({ group: "version", options: { json: true } }), {
     version: pkg.version,
   });
 });

package/test/help.test.js

@@ -11,6 +11,9 @@ 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 audio sfx/);
+  assert.match(help, /flatkey audio music/);
+  assert.match(help, /flatkey audio voices/);
   assert.match(help, /flatkey text generate/);
   assert.match(help, /flatkey credits --json/);
   assert.match(help, /flatkey status --json/);
@@ -25,5 +28,6 @@ test("human help lists core commands", () => {
   assert.match(help, /Usage: flatkey/);
   assert.match(help, /image generate/);
   assert.match(help, /models/);
+  assert.match(help, /audio voices/);
   assert.match(help, /text generate/);
 });

package/test/integration.test.js

@@ -17,26 +17,36 @@ test("runs generation and utility commands in json mode", async (t) => {
     });
     request.on("end", () => {
       requests.push({ url: request.url, method: request.method, body });
-      response.setHeader("content-type", "application/json");
       if (request.url.startsWith("/v1beta/models/")) {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({ data: [{ url: "https://cdn.test/image.png" }] }));
       } else if (request.url === "/v1/video/generations") {
+        response.setHeader("content-type", "application/json");
         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/text-to-speech/EXAVITQu4vr4xnSDxMaL") {
+        response.setHeader("content-type", "audio/mpeg");
+        response.end("audio-file");
       } else if (request.url === "/v1/chat/completions") {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({ choices: [{ message: { content: "headline" } }] }));
       } else if (request.url === "/v1/credits") {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({ remaining: 42, used: 8 }));
       } else if (request.url === "/v1/status") {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({ status: "ok" }));
       } else if (request.url === "/v1/available_models") {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({
           success: true,
           object: "list",
           data: [{ id: "remote-image", object: "model", owned_by: "flatkey" }],
         }));
+      } else if (request.url === "/v1/voices") {
+        response.setHeader("content-type", "application/json");
+        response.end(JSON.stringify({ voices: [{ voice_id: "voice-123", name: "Rachel" }] }));
       } else {
+        response.setHeader("content-type", "application/json");
         response.statusCode = 404;
         response.end(JSON.stringify({ error: { message: "not found" } }));
       }
@@ -54,20 +64,23 @@ test("runs generation and utility commands in json mode", async (t) => {
   const credits = await runCli(["credits", ...common]);
   const status = await runCli(["status", ...common]);
   const models = await runCli(["models", ...common]);
+  const voices = await runCli(["audio", "voices", ...common]);
 
   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(audio.stdout).artifacts.length, 1);
+  assert.match(JSON.parse(audio.stdout).artifacts[0].path, /audio-01\.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, [
     { id: "remote-image", type: "image", source: "remote" },
   ]);
+  assert.deepEqual(JSON.parse(voices.stdout).voices, [{ voice_id: "voice-123", name: "Rachel" }]);
   assert.equal(image.stderr, "");
   assert.ok(requests.some((request) => request.url.startsWith("/v1beta/models/")));
   assert.ok(requests.some((request) => request.url === "/v1/video/generations"));
-  assert.ok(requests.some((request) => request.url === "/v1/audio/generations"));
+  assert.ok(requests.some((request) => request.url === "/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL"));
   assert.ok(requests.some((request) => request.url === "/v1/chat/completions"));
 });
 
@@ -91,18 +104,63 @@ test("dry-run returns planned request without calling network", async () => {
   assert.equal(result.stderr, "");
 });
 
+test("audio dry-run supports tts, sfx, and music routes", async () => {
+  const tts = await runCli([
+    "audio",
+    "generate",
+    "--prompt",
+    "hello",
+    "--voice-id",
+    "voice-123",
+    "--dry-run",
+    "--json",
+  ]);
+  const sfx = await runCli([
+    "audio",
+    "sfx",
+    "--prompt",
+    "glass shattering",
+    "--duration",
+    "3",
+    "--dry-run",
+    "--json",
+  ]);
+  const music = await runCli([
+    "audio",
+    "music",
+    "--prompt",
+    "calm ambient piano",
+    "--music-length-ms",
+    "10000",
+    "--dry-run",
+    "--json",
+  ]);
+
+  assert.equal(JSON.parse(tts.stdout).request.url, "https://router.flatkey.ai/v1/text-to-speech/voice-123");
+  assert.equal(JSON.parse(sfx.stdout).request.url, "https://router.flatkey.ai/v1/sound-generation");
+  assert.equal(JSON.parse(sfx.stdout).request.body.duration_seconds, 3);
+  assert.equal(JSON.parse(music.stdout).request.url, "https://router.flatkey.ai/v1/music");
+  assert.equal(JSON.parse(music.stdout).request.body.music_length_ms, 10000);
+});
+
 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.setHeader("content-type", "application/json");
         response.end(JSON.stringify({
           data: [{ b64_json: Buffer.from("image-file").toString("base64") }],
         }));
+      } else if (request.url === "/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL") {
+        response.setHeader("content-type", "audio/mpeg");
+        response.end("audio-file");
       } else if (request.url === "/v1/chat/completions") {
+        response.setHeader("content-type", "application/json");
         response.end(JSON.stringify({ choices: [{ message: { content: "text-file" } }] }));
       } else {
+        response.setHeader("content-type", "application/json");
         response.statusCode = 404;
         response.end(JSON.stringify({ error: { message: "not found" } }));
       }
@@ -113,6 +171,7 @@ test("generation commands write explicit output files", async (t) => {
   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 audioOutput = join(dir, "speech.mp3");
   const textOutput = join(dir, "headline.txt");
 
   const common = ["--base-url", baseUrl, "--api-key", "test-key", "--json"];
@@ -136,9 +195,20 @@ test("generation commands write explicit output files", async (t) => {
     textOutput,
     ...common,
   ]);
+  const audio = await runCli([
+    "audio",
+    "generate",
+    "--prompt",
+    "hello",
+    "-o",
+    audioOutput,
+    ...common,
+  ]);
 
   assert.deepEqual(JSON.parse(image.stdout).artifacts, [{ path: imageOutput }]);
   assert.equal(await readFile(imageOutput, "utf8"), "image-file");
+  assert.deepEqual(JSON.parse(audio.stdout).artifacts, [{ path: audioOutput }]);
+  assert.equal(await readFile(audioOutput, "utf8"), "audio-file");
   assert.equal(JSON.parse(text.stdout).output, textOutput);
   assert.equal(await readFile(textOutput, "utf8"), "text-file");
 });

package/test/live-flatkey.test.js

@@ -18,6 +18,36 @@ const cases = [
       assert.ok(payload.models.length > 0);
     },
   },
+  {
+    name: "audio voices",
+    args: ["audio", "voices", "--json"],
+    paid: false,
+    expect: (payload) => {
+      assert.ok(Array.isArray(payload.voices));
+      assert.ok(payload.voices.length > 0);
+    },
+  },
+  {
+    name: "audio tts",
+    args: ["audio", "generate", "--prompt", "flatkey voice test", "--json"],
+    paid: true,
+    dryRun: true,
+    expect: (payload) => assert.equal(payload.request.url, "https://router.flatkey.ai/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL"),
+  },
+  {
+    name: "audio sfx",
+    args: ["audio", "sfx", "--prompt", "glass shattering", "--duration", "3", "--json"],
+    paid: true,
+    dryRun: true,
+    expect: (payload) => assert.equal(payload.request.url, "https://router.flatkey.ai/v1/sound-generation"),
+  },
+  {
+    name: "audio music",
+    args: ["audio", "music", "--prompt", "calm ambient piano", "--music-length-ms", "10000", "--json"],
+    paid: true,
+    dryRun: true,
+    expect: (payload) => assert.equal(payload.request.url, "https://router.flatkey.ai/v1/music"),
+  },
   {
     name: "image gpt",
     args: ["image", "generate", "--model", "gpt-image-2", "--prompt", "one tiny red square icon", "--json"],