@flatkey-ai/cli 0.1.5 → 0.1.7

package/src/help.js

@@ -2,7 +2,9 @@ export function getAiHelp() {
   return `Flatkey CLI protocol for agents
 
 Setup:
-- Prefer env: FLATKEY_API_KEY=<key>
+- Prefer browser auth: flatkey login
+- Or 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 +15,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]
@@ -22,6 +24,9 @@ Commands:
 - flatkey credits --json
 - flatkey status --json
 - flatkey models --json [--type image|video|audio|text]
+- flatkey login [--no-open] [--console-url <url>]
+- flatkey logout
+- flatkey auth status --json
 - flatkey help --ai
 
 Environment:
@@ -29,7 +34,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 +45,10 @@ export function getHumanHelp() {
   return `Usage: flatkey <command> [options]
 
 Commands:
-  onboard --api-key <key>        Save Flatkey API key
+  login                         Authorize CLI in browser
+  logout                        Remove saved Flatkey API key
+  auth status                    Show saved auth state
+  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 +65,167 @@ Global options:
   --json                         Print machine-readable JSON
   --output, -o <file>             Write generated output to a local file
   --base-url <url>               Override Flatkey router URL
+  --console-url <url>            Override Flatkey console URL for login
+
+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`,
+  auth: `Usage: flatkey auth <action> [options]
+
+Actions:
+  status                         Show saved auth state
+
+Options:
+  --json                         Print machine-readable JSON`,
+  "auth status": `Usage: flatkey auth status [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`,
+  login: `Usage: flatkey login [options]
+
+Options:
+  --no-open                      Print approval URL without opening a browser
+  --console-url <url>            Override Flatkey console URL
+  --json                         Print machine-readable JSON`,
+  logout: `Usage: flatkey logout [options]
+
+Options:
+  --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`.