@flatkey-ai/cli 0.1.4 → 0.1.6

package/src/help.js

@@ -3,6 +3,7 @@ export function getAiHelp() {
 
 Setup:
 - Prefer 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.
 
@@ -13,8 +14,11 @@ 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 video generate --prompt "<prompt>" --json [--model seedance2] [--ratio 16:9] [--resolution 720p] [--output video.mp4]
+- 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
@@ -26,8 +30,9 @@ Environment:
 - Default router: https://router.flatkey.ai
 
 Recovery:
-- Missing key: run flatkey onboard --api-key <key> or set FLATKEY_API_KEY.
+- Missing key: create one at https://console.flatkey.ai/keys, then 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.
 `;
 }
@@ -36,10 +41,13 @@ export function getHumanHelp() {
   return `Usage: flatkey <command> [options]
 
 Commands:
-  onboard --api-key <key>        Save Flatkey API key
+  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
-  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
@@ -50,5 +58,145 @@ Global options:
   --json                         Print machine-readable JSON
   --output, -o <file>             Write generated output to a local file
   --base-url <url>               Override Flatkey router URL
+
+Video options:
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
+  --resolution <value>            480p, 720p, or 1080p
 `;
 }
+
+const COMMAND_HELP = {
+  audio: `Usage: flatkey audio <action> [options]
+
+Actions:
+  generate --prompt <txt>        Generate speech
+  sfx --prompt <txt>             Generate sound effects
+  music --prompt <txt>           Generate music
+  voices                         List available voices
+
+Options:
+  --json                         Print machine-readable JSON
+  --output, -o <file>             Write generated output to a local file
+  --model <model>                Override model id
+  --voice-id <voice_id>           Voice id for speech generation
+  --duration <seconds>            Duration for sound effects
+  --music-length-ms <ms>          Music length in milliseconds
+  --help                         Show audio help`,
+  "audio generate": `Usage: flatkey audio generate --prompt <txt> [options]
+
+Options:
+  --voice-id <voice_id>           Voice id
+  --model <model>                Model id, default eleven_multilingual_v2
+  --stability <0..1>              Voice stability
+  --similarity-boost <0..1>       Voice similarity boost
+  --style <0..1>                 Voice style
+  --output, -o <file>             Write speech file
+  --json                         Print machine-readable JSON`,
+  "audio music": `Usage: flatkey audio music --prompt <txt> [options]
+
+Options:
+  --music-length-ms <ms>          Music length in milliseconds
+  --output, -o <file>             Write music file
+  --json                         Print machine-readable JSON`,
+  "audio sfx": `Usage: flatkey audio sfx --prompt <txt> [options]
+
+Options:
+  --duration <seconds>            Sound effect duration
+  --output, -o <file>             Write sound effect file
+  --json                         Print machine-readable JSON`,
+  "audio voices": `Usage: flatkey audio voices [options]
+
+Options:
+  --json                         Print machine-readable JSON`,
+  credits: `Usage: flatkey credits [options]
+
+Options:
+  --json                         Print machine-readable JSON`,
+  help: `Usage: flatkey help [command] [options]
+
+Options:
+  --ai                           Print agent-focused usage guide`,
+  image: `Usage: flatkey image generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id
+  --size <size>                  Image size for OpenAI-style image models
+  --quality <quality>             Image quality for supported models
+  --n <count>                    Number of images for supported models
+  --output, -o <file>             Write image file
+  --json                         Print machine-readable JSON`,
+  "image generate": `Usage: flatkey image generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id
+  --size <size>                  Image size for OpenAI-style image models
+  --quality <quality>             Image quality for supported models
+  --n <count>                    Number of images for supported models
+  --output, -o <file>             Write image file
+  --json                         Print machine-readable JSON`,
+  models: `Usage: flatkey models [options]
+
+Options:
+  --type <type>                  Filter: image, video, audio, or text
+  --json                         Print machine-readable JSON`,
+  onboard: `Usage: flatkey onboard --api-key <key>
+
+Create a Flatkey API key first:
+  https://console.flatkey.ai/keys
+
+Options:
+  --api-key <key>                Flatkey API key to save`,
+  status: `Usage: flatkey status [options]
+
+Options:
+  --json                         Print machine-readable JSON`,
+  text: `Usage: flatkey text generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id, default gpt-5.5
+  --output, -o <file>             Write text file
+  --json                         Print machine-readable JSON`,
+  "text generate": `Usage: flatkey text generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id, default gpt-5.5
+  --output, -o <file>             Write text file
+  --json                         Print machine-readable JSON`,
+  version: `Usage: flatkey version [options]
+
+Aliases:
+  flatkey --version
+  flatkey -v
+
+Options:
+  --json                         Print machine-readable JSON`,
+  video: `Usage: flatkey video generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id, default veo-3
+  --duration <seconds>            Video duration
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
+  --resolution <value>            480p, 720p, or 1080p
+  --fps <fps>                    Frames per second
+  --output, -o <file>             Write video file
+  --json                         Print machine-readable JSON`,
+  "video generate": `Usage: flatkey video generate --prompt <txt> [options]
+
+Options:
+  --model <model>                Model id, default veo-3
+  --duration <seconds>            Video duration
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
+  --resolution <value>            480p, 720p, or 1080p
+  --fps <fps>                    Frames per second
+  --output, -o <file>             Write video file
+  --json                         Print machine-readable JSON`,
+};
+
+export function getCommandHelp(group, action) {
+  const key = action ? `${group} ${action}` : group;
+  const help = COMMAND_HELP[key];
+  if (!help) {
+    throw new Error(`Unknown help topic: ${key}`);
+  }
+  return help;
+}

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/.github/workflows/npm-publish.yml

@@ -1,36 +0,0 @@
-name: Publish npm
-
-on:
-  workflow_dispatch:
-  push:
-    tags:
-      - "v*"
-
-permissions:
-  contents: read
-
-jobs:
-  publish:
-    name: Publish @flatkey-ai/cli
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Test
-        run: npm test
-
-      - name: Publish
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/docs/superpowers/plans/2026-07-17-flatkey-cli.md

@@ -1,90 +0,0 @@
-# Flatkey CLI Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build `@flatkey-ai/cli`, a Node.js CLI for Flatkey image, video, audio, credits, status, models, onboarding, and AI-first help.
-
-**Architecture:** Use small ESM modules with dependency-injected `fetch`, filesystem paths, and streams so behavior can be tested without real Flatkey calls. The CLI parser converts argv into command objects, command handlers call provider functions, and output helpers keep human logs off stdout in JSON mode.
-
-**Tech Stack:** Node.js ESM, npm package bin, built-in `node:test`, `assert/strict`, `fs/promises`, `child_process`, and global `fetch`.
-
----
-
-## File Structure
-
-- `package.json`: npm metadata, bin mapping, scripts, engines.
-- `bin/flatkey.js`: executable entrypoint.
-- `src/cli.js`: argv parsing, command dispatch, exit handling.
-- `src/config.js`: API key/config resolution and onboarding writes.
-- `src/api.js`: Flatkey HTTP requests and route selection.
-- `src/artifacts.js`: save base64/data URL/url artifacts.
-- `src/help.js`: human and AI help text.
-- `src/models.js`: bundled fallback model list and remote normalization.
-- `src/animation.js`: ASCII animation lifecycle.
-- `test/*.test.js`: focused tests for each module and CLI subprocess behavior.
-
-## Task 1: Package and Parser
-
-- [ ] Write failing tests in `test/cli.test.js` for `parseArgv`, including `flatkey image generate --prompt x --json`, `flatkey credits --json`, unknown command, and `flatkey help --ai`.
-- [ ] Run `npm test -- test/cli.test.js`; expect module-not-found or function-not-found failure.
-- [ ] Create `package.json`, `bin/flatkey.js`, and `src/cli.js` with minimal parser and dispatch stubs.
-- [ ] Run `npm test -- test/cli.test.js`; expect parser tests pass.
-- [ ] Commit: `feat: add cli parser`
-
-## Task 2: Config and Onboarding
-
-- [ ] Write failing tests in `test/config.test.js` for API key precedence: option, `FLATKEY_API_KEY`, saved config, and missing key error.
-- [ ] Write failing test for `writeConfig` creating config JSON with `apiKey`.
-- [ ] Run `npm test -- test/config.test.js`; expect missing module failure.
-- [ ] Create `src/config.js` and wire `onboard` command to write config.
-- [ ] Run `npm test -- test/config.test.js test/cli.test.js`; expect pass.
-- [ ] Commit: `feat: add flatkey config`
-
-## Task 3: API Requests
-
-- [ ] Write failing tests in `test/api.test.js` for Nano image route, OpenAI image route, video route, audio route, credits route, status route, and models route using injected fetch.
-- [ ] Run `npm test -- test/api.test.js`; expect missing module failure.
-- [ ] Create `src/api.js` with `FlatkeyError`, `generateImage`, `generateVideo`, `generateAudio`, `getCredits`, `getStatus`, and `getModels`.
-- [ ] Run `npm test -- test/api.test.js`; expect pass.
-- [ ] Commit: `feat: add flatkey api client`
-
-## Task 4: Artifacts and Model Fallback
-
-- [ ] Write failing tests in `test/artifacts.test.js` for saving base64, data URL, and preserving URL outputs.
-- [ ] Write failing tests in `test/models.test.js` for bundled fallback shape and type filtering.
-- [ ] Run targeted tests; expect missing module failures.
-- [ ] Create `src/artifacts.js` and `src/models.js`.
-- [ ] Run targeted tests; expect pass.
-- [ ] Commit: `feat: add artifact and model helpers`
-
-## Task 5: Help and Animation
-
-- [ ] Write failing tests in `test/help.test.js` checking `help --ai` includes setup, JSON contract, image/video/audio examples, credits, status, and models.
-- [ ] Write failing tests in `test/animation.test.js` checking no animation when JSON mode or non-TTY.
-- [ ] Run targeted tests; expect missing module failures.
-- [ ] Create `src/help.js` and `src/animation.js`.
-- [ ] Run targeted tests; expect pass.
-- [ ] Commit: `feat: add help and animation`
-
-## Task 6: Command Integration
-
-- [ ] Write failing subprocess tests in `test/integration.test.js` with a local HTTP server for `image generate --json`, `video generate --json`, `audio generate --json`, `credits --json`, `status --json`, and `models --json`.
-- [ ] Run `npm test -- test/integration.test.js`; expect command behavior missing.
-- [ ] Wire command handlers in `src/cli.js` to config, API, artifacts, models, help, and animation.
-- [ ] Run `npm test`; expect pass.
-- [ ] Commit: `feat: wire flatkey cli commands`
-
-## Task 7: Release Metadata
-
-- [ ] Write failing tests or static checks for package name `@flatkey-ai/cli`, bin `flatkey`, and executable bin file.
-- [ ] Add `README.md` with install, auth, commands, and release channel notes.
-- [ ] Add `release/homebrew/flatkey.rb`, `release/deb/README.md`, and `release/msi/README.md` as packaging stubs that wrap npm package release.
-- [ ] Run `npm test`.
-- [ ] Commit: `docs: add release notes`
-
-## Final Verification
-
-- [ ] Run `npm test`.
-- [ ] Run `node bin/flatkey.js help --ai`.
-- [ ] Run `node bin/flatkey.js models --json` without network key and confirm bundled fallback.
-- [ ] Run `git status --short`.

package/docs/superpowers/specs/2026-07-17-flatkey-cli-design.md

@@ -1,209 +0,0 @@
-# Flatkey CLI Design
-
-## Goal
-
-Build `@flatkey-ai/cli`, a cross-platform npm CLI for media workers and AI agents to use Flatkey as the most cost-effective practical AI API entrypoint for image, video, and audio generation. The CLI should make cost, credits, model choice, upload inputs, generation jobs, and saved artifacts visible from the terminal.
-
-## Scope
-
-The CLI provides:
-
-- Image generation.
-- Video generation.
-- Audio generation.
-- Cost estimation before generation.
-- Generation job creation, listing, inspection, and waiting.
-- Uploads for local image, video, and audio inputs.
-- Credit balance and usage status.
-- Recent credit transactions.
-- AI-first help output.
-- Available model listing.
-- Model parameter inspection.
-- Local onboarding for a Flatkey API key.
-- A short ASCII animation during human-facing generation commands.
-
-The first implementation is a Node.js npm package. It runs on Windows, Linux, and macOS through Node. Homebrew, apt/deb, and MSI packaging are release channels around the npm package, not separate native implementations.
-
-## Package and Binary
-
-Package name: `@flatkey-ai/cli`.
-
-Primary binary: `flatkey`.
-
-The package uses ESM JavaScript and keeps runtime dependencies minimal. It should run with the current active Node LTS line and newer.
-
-## Command Surface
-
-Top-level commands:
-
-- `flatkey onboard [--api-key <key>]`
-- `flatkey image generate --prompt "<prompt>" [options]`
-- `flatkey video generate --prompt "<prompt>" [options]`
-- `flatkey audio generate --prompt "<prompt>" [options]`
-- `flatkey generate create <model> --prompt "<prompt>" [options]`
-- `flatkey generate cost <model> --prompt "<prompt>" [options]`
-- `flatkey generate get <job-id> [--json]`
-- `flatkey generate list [--type image|video|audio] [--json]`
-- `flatkey generate wait <job-id> [--json]`
-- `flatkey upload create <file> [--json]`
-- `flatkey upload list [--type image|video|audio] [--json]`
-- `flatkey credits [--json]`
-- `flatkey status [--json]`
-- `flatkey transactions [--size <count>] [--json]`
-- `flatkey models [--type image|video|audio] [--json]`
-- `flatkey models get <model> [--json]`
-- `flatkey help [--ai] [--json]`
-- `flatkey version`
-
-Shared generation options:
-
-- `--model <model>`
-- `--base-url <url>`
-- `--api-key <key>`
-- `--out <dir>`
-- `--json`
-
-Image-specific options:
-
-- `--size <width>x<height>`
-- `--aspect <ratio>`
-- `--n <count>`
-- `--quality <quality>`
-
-Video-specific options:
-
-- `--duration <seconds>`
-- `--aspect <ratio>`
-- `--fps <number>`
-
-Audio-specific options:
-
-- `--voice <voice>`
-- `--format <mp3|wav|aac|flac>`
-
-## Authentication and Config
-
-Credential resolution order:
-
-1. `--api-key`
-2. `FLATKEY_API_KEY`
-3. Saved config at `~/.config/flatkey/config.json`
-
-`flatkey onboard` writes the config file with mode `0600` where supported. Windows should ignore chmod failures.
-
-## Flatkey API Integration
-
-Default base URL: `https://router.flatkey.ai`.
-
-Image generation follows the proven `awesome-images` behavior:
-
-- OpenAI-compatible image endpoint: `POST /v1/images/generations`
-- Gemini-style Nano endpoint: `POST /v1beta/models/{model}:generateContent?key={apiKey}`
-
-The CLI should default image generation to the Nano route when `--model` is omitted or starts with `nano`, and use `/v1/images/generations` for `gpt` or `gpt-image-*`.
-
-Video, audio, cost, jobs, uploads, credits, status, transactions, and models are implemented through small provider functions with configurable endpoint paths. The initial default paths are:
-
-- `POST /v1/videos/generations`
-- `POST /v1/audio/generations`
-- `POST /v1/generations`
-- `POST /v1/generations/cost`
-- `GET /v1/generations`
-- `GET /v1/generations/{jobId}`
-- `POST /v1/uploads`
-- `GET /v1/uploads`
-- `GET /v1/credits`
-- `GET /v1/credits/transactions`
-- `GET /v1/status`
-- `GET /v1/models`
-- `GET /v1/models/{model}`
-
-If Flatkey router returns a different shape, adapters normalize results before printing or saving artifacts.
-
-## Output and Artifacts
-
-Default output directory: `flatkey-output`.
-
-Generation commands save returned files when the API returns base64 or data URLs, and print remote URLs when the API returns URLs. JSON mode prints a machine-readable payload and suppresses animation/logging.
-
-Artifact naming:
-
-- `image-01.png`
-- `video-01.mp4`
-- `audio-01.mp3`
-
-Extensions come from returned MIME types when available.
-
-## AI-First Help
-
-`flatkey help --ai` prints a compact protocol-style guide:
-
-- Required setup.
-- Commands.
-- Arguments.
-- Environment variables.
-- JSON mode contract.
-- Example calls for image, video, audio, cost, upload, job wait, credits, transactions, status, and models.
-- Error recovery instructions for missing key, unknown model, and API failure.
-
-Human `--help` remains readable but secondary.
-
-## Models
-
-`flatkey models` fetches remote model metadata when API key and network are available. If remote fetch fails, it falls back to bundled defaults:
-
-- Image: `nano-banana-pro-preview`, `nano-banana-flash`, `gpt-image-2`
-- Video: `veo-3`, `veo-3-fast`
-- Audio: `tts-1`, `gpt-4o-mini-tts`
-
-The fallback must mark `source: "bundled"` in JSON output.
-
-## ASCII Animation
-
-Human generation mode shows a short stderr animation before and during network calls. Requirements:
-
-- Uses plain ASCII only.
-- No animation in `--json`.
-- Does not corrupt stdout artifact paths.
-- Works in Windows terminals.
-- Automatically falls back to simple log lines when stderr is not a TTY.
-
-## Error Handling
-
-Errors should be short and actionable:
-
-- Missing key: explain `flatkey onboard` and `FLATKEY_API_KEY`.
-- Unknown command: point to `flatkey help --ai`.
-- HTTP failure: show API message when present, otherwise status code.
-- Save failure: show output path and filesystem error.
-
-JSON mode errors still exit non-zero and write error JSON to stderr.
-
-## Testing
-
-Use Node's built-in `node:test` and `assert/strict`.
-
-Test coverage:
-
-- Argument parsing.
-- Config read/write and env precedence.
-- Request building for image OpenAI and Nano routes.
-- Request building for video/audio/credits/status/models.
-- Artifact persistence from base64, data URL, and URL payloads.
-- JSON mode suppresses animation/logging.
-- CLI subprocess tests against local HTTP servers.
-
-## Release Channels
-
-Primary release is npm:
-
-- `npm publish --access public`
-- Users run `npx @flatkey-ai/cli` or install globally.
-
-Secondary release assets:
-
-- Homebrew formula that installs the npm package and exposes `flatkey`.
-- Debian package wrapping the npm package and generated launcher.
-- MSI package wrapping the npm package and generated Windows launcher.
-
-Release automation should be added after the CLI is working and tested.

package/release/deb/README.md

@@ -1,16 +0,0 @@
-# Debian Package
-
-Build `.deb` as a wrapper around the published npm package.
-
-Expected install behavior:
-
-```bash
-sudo apt-get install flatkey
-flatkey help --ai
-```
-
-Package contents:
-
-- Node runtime dependency.
-- Global install of `@flatkey-ai/cli`.
-- `/usr/bin/flatkey` launcher.

package/release/homebrew/flatkey.rb

@@ -1,16 +0,0 @@
-class Flatkey < Formula
-  desc "Flatkey media generation CLI"
-  homepage "https://github.com/flatkey-ai/flatkey-cli"
-  license "MIT"
-
-  depends_on "node"
-
-  def install
-    system "npm", "install", "-g", "@flatkey-ai/cli", "--prefix", libexec
-    bin.install_symlink Dir["#{libexec}/bin/flatkey"].first
-  end
-
-  test do
-    system "#{bin}/flatkey", "help", "--ai"
-  end
-end

package/release/msi/README.md

@@ -1,15 +0,0 @@
-# Windows MSI
-
-Build MSI as a wrapper around the published npm package.
-
-Expected install behavior:
-
-```powershell
-flatkey help --ai
-```
-
-Package contents:
-
-- Node runtime prerequisite or bundled runtime.
-- Install of `@flatkey-ai/cli`.
-- `flatkey.cmd` on PATH.

package/test/animation.test.js

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