@flatkey-ai/cli 0.1.5 → 0.1.6

package/README.md

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

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.5",
+  "version": "0.1.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,11 +43,24 @@ export function generateVideo(options) {
 }
 
 export function planVideoRequest(options) {
+  const ratio = validateOptionalValue(
+    optionValue(options, "ratio", "aspect"),
+    ["16:9", "9:16", "4:3", "3:4", "21:9", "1:1"],
+    "ratio",
+  );
+  const resolution = validateOptionalValue(
+    options.resolution,
+    ["480p", "720p", "1080p"],
+    "resolution",
+  );
   return planJsonPost(options, "/v1/video/generations", cleanObject({
     model: options.model ?? "veo-3",
     prompt: options.prompt,
     duration: parseOptionalInteger(options.duration),
-    aspect: options.aspect,
+    aspect: ratio,
+    ratio,
+    resolution,
+    quality: resolution,
     fps: parseOptionalInteger(options.fps),
   }));
 }
@@ -223,6 +236,12 @@ function optionValue(options, ...keys) {
   return undefined;
 }
 
+function validateOptionalValue(value, allowed, name) {
+  if (value === undefined) return undefined;
+  if (allowed.includes(value)) return value;
+  throw new Error(`Invalid ${name}: ${value}. Allowed values: ${allowed.join(", ")}`);
+}
+
 function cleanObject(value) {
   return Object.fromEntries(
     Object.entries(value).filter(([, entry]) => entry !== undefined),

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;

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 });

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,7 +14,7 @@ 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 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]
@@ -29,7 +30,7 @@ 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.
@@ -40,7 +41,7 @@ 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 speech with ElevenLabs voices
@@ -57,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/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,50 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

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

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/CONTRIBUTING.md

@@ -1,37 +0,0 @@
-# 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/SECURITY.md

@@ -1,13 +0,0 @@
-# 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/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`.