@flatkey-ai/cli 0.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,36 @@
+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/README.md

@@ -0,0 +1,51 @@
+# @flatkey-ai/cli
+
+Unified Flatkey CLI for media workers. Generate images, videos, and audio through Flatkey credits.
+
+## Install
+
+```bash
+npm install -g @flatkey-ai/cli
+```
+
+Or run without installing:
+
+```bash
+npx @flatkey-ai/cli help --ai
+```
+
+## Auth
+
+```bash
+flatkey onboard --api-key <key>
+```
+
+Or use:
+
+```bash
+export FLATKEY_API_KEY=<key>
+```
+
+## Commands
+
+```bash
+flatkey image generate --prompt "magazine cover" --json
+flatkey video generate --prompt "product launch clip" --json
+flatkey audio generate --prompt "30 second voiceover" --json
+flatkey credits --json
+flatkey status --json
+flatkey models --json
+flatkey help --ai
+```
+
+Default router: `https://router.flatkey.ai`.
+
+## Release Channels
+
+Primary release is npm package `@flatkey-ai/cli`.
+
+Planned wrappers:
+
+- Homebrew formula.
+- Debian `.deb` package for apt-based install.
+- Windows MSI package.

package/bin/flatkey.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  if (process.argv.includes("--json")) {
+    process.stderr.write(`${JSON.stringify({ error: { message: error.message } })}\n`);
+  } else {
+    process.stderr.write(`${error.message}\n`);
+  }
+  process.exitCode = 1;
+});

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

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

@@ -0,0 +1,209 @@
+# 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/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@flatkey-ai/cli",
+  "version": "0.1.0",
+  "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
+  "type": "module",
+  "bin": {
+    "flatkey": "bin/flatkey.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/release/deb/README.md

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

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

@@ -0,0 +1,15 @@
+# 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/src/animation.js

@@ -0,0 +1,40 @@
+const FRAMES = [
+  "[FLATKEY]  .    ",
+  "[FLATKEY]  ..   ",
+  "[FLATKEY]  ...  ",
+  "[FLATKEY]  .... ",
+  "[FLATKEY]  >>>> ",
+];
+
+export function createAnimation({
+  json = false,
+  stream = process.stderr,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+} = {}) {
+  let timer;
+  let active = false;
+  let frame = 0;
+
+  return {
+    start(kind = "media") {
+      if (json) return;
+      if (!stream.isTTY) {
+        stream.write(`flatkey ${kind} generation started\n`);
+        return;
+      }
+      active = true;
+      stream.write(`${FRAMES[0]}\r`);
+      timer = setIntervalFn(() => {
+        if (!active) return;
+        frame = (frame + 1) % FRAMES.length;
+        stream.write(`${FRAMES[frame]}\r`);
+      }, 120);
+    },
+    stop() {
+      active = false;
+      if (timer) clearIntervalFn(timer);
+      if (!json && stream.isTTY) stream.write("                 \r");
+    },
+  };
+}

package/src/api.js

@@ -0,0 +1,129 @@
+export const DEFAULT_BASE_URL = "https://router.flatkey.ai";
+
+export class FlatkeyError extends Error {
+  constructor(message, { status } = {}) {
+    super(message);
+    this.name = "FlatkeyError";
+    this.status = status;
+  }
+}
+
+export async function generateImage(options) {
+  const model = options.model ?? "nano-banana-pro-preview";
+  if (model.startsWith("gpt")) {
+    return postJson(options, "/v1/images/generations", cleanObject({
+      model,
+      prompt: options.prompt,
+      size: options.size,
+      n: parseOptionalInteger(options.n),
+      quality: options.quality,
+    }));
+  }
+
+  const path = `/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(options.apiKey)}`;
+  return requestJson(options, path, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: options.prompt }] }],
+    }),
+  });
+}
+
+export function generateVideo(options) {
+  return postJson(options, "/v1/videos/generations", cleanObject({
+    model: options.model ?? "veo-3",
+    prompt: options.prompt,
+    duration: parseOptionalInteger(options.duration),
+    aspect: options.aspect,
+    fps: parseOptionalInteger(options.fps),
+  }));
+}
+
+export function generateAudio(options) {
+  return postJson(options, "/v1/audio/generations", cleanObject({
+    model: options.model ?? "tts-1",
+    prompt: options.prompt,
+    voice: options.voice,
+    format: options.format,
+  }));
+}
+
+export function getCredits(options) {
+  return requestJson(options, "/v1/credits");
+}
+
+export function getStatus(options) {
+  return requestJson(options, "/v1/status");
+}
+
+export function getModels(options) {
+  return requestJson(options, "/v1/models");
+}
+
+async function postJson(options, path, payload) {
+  return requestJson(options, path, {
+    method: "POST",
+    headers: jsonHeaders(options.apiKey),
+    body: JSON.stringify(payload),
+  });
+}
+
+async function requestJson(options, path, init = {}) {
+  const fetchImpl = options.fetch ?? fetch;
+  const response = await fetchImpl(buildUrl(options.baseUrl, path), {
+    method: "GET",
+    ...init,
+    headers: {
+      ...authHeaders(options.apiKey),
+      ...init.headers,
+    },
+  });
+  const body = await readJson(response);
+  if (!response.ok) {
+    throw new FlatkeyError(extractErrorMessage(body, response.status), {
+      status: response.status,
+    });
+  }
+  return body;
+}
+
+function buildUrl(baseUrl = DEFAULT_BASE_URL, path) {
+  return `${baseUrl.replace(/\/$/, "")}${path}`;
+}
+
+function authHeaders(apiKey) {
+  return apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
+}
+
+function jsonHeaders(apiKey) {
+  return {
+    ...authHeaders(apiKey),
+    "content-type": "application/json",
+  };
+}
+
+function parseOptionalInteger(value) {
+  if (value === undefined) return undefined;
+  return Number.parseInt(value, 10);
+}
+
+function cleanObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  );
+}
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+
+function extractErrorMessage(body, status) {
+  if (typeof body?.error?.message === "string") return body.error.message;
+  if (typeof body?.message === "string") return body.message;
+  return `Flatkey API request failed with HTTP ${status}`;
+}