@drakulavich/kesha-voice-kit 2.0.0 → 2.2.0-beta.1

package/README.md

@@ -11,9 +11,9 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI — CoreML on Apple Silicon, ONNX on Linux and Windows.</p>
+<p align="center"><b>Kesha listens and talks back.</b><br>Your agent gets a voice message, Kesha turns it into text on your machine, and speaks the reply once you add <code>kesha install --tts</code> (<a href="docs/use-cases.md#sending-voice-replies">voice replies</a>). Fastest on Apple Silicon with CoreML, and it runs on Linux and Windows through ONNX.</p>
 
-- **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
+- **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~10x on an x86 CPU
 - **Speak back** — text-to-speech in [9 languages](docs/languages.md#text-to-speech)
 - **Plug into agents** — ship voice workflows as CLI commands, an MCP server, an <a href="docs/openclaw.md">OpenClaw</a> skill, or a <a href="docs/hermes.md">Hermes</a> agent
 - **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
@@ -24,7 +24,7 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
+Runtime: **[Bun](https://bun.sh)** >= 1.4.0.
 
 ```bash
 # 1. Install Bun (skip if you have it)
@@ -64,6 +64,14 @@ All three targets transcribe, detect the spoken language, run VAD, and speak. Th
 
 Intel Macs get no published engine binary. Full matrix with maturity labels: [docs/product-positioning.md](docs/product-positioning.md#platform-matrix).
 
+## Plug into your agent
+
+- **MCP server** — `kesha mcp` exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: [docs/mcp.md](docs/mcp.md).
+- **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
+- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
+- **Raycast** (macOS) — offline microphone dictation from the launcher: *Dictate to Clipboard* records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. [Install from the Raycast Store](https://www.raycast.com/drakulavich/kesha-voice-kit) · source: [`raycast/`](raycast/).
+- **Programmatic API** — `@drakulavich/kesha-voice-kit/core` for use inside a Bun program. See [docs/api.md](docs/api.md).
+
 ## Speech-to-text
 
 ```bash
@@ -126,13 +134,13 @@ kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in
 
 ## Performance
 
-> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~2.5x faster** on CPU
+> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~10x faster** on an x86 Linux CPU (~2.5x faster than faster-whisper)
 
 Compared against Whisper `large-v3-turbo`, all engines auto-detecting language:
 
 ![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/benchmark.svg)
 
-Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The CPU figure is the ONNX engine on an M2's CPU cores; no x86 numbers are published yet.
+Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The chart is from an M2. The x86 figure comes from a GitHub-hosted `ubuntu-latest` runner (AMD EPYC, ONNX on CPU), where openai-whisper runs in FP32.
 
 ## Other install methods
 
@@ -144,14 +152,6 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/distribution.md](docs/distribution.md#nix)
 - **Shell completions + manpage** — `kesha completions bash|zsh|fish` and `kesha manpage` print the packaged files to install wherever your shell expects them.
 
-## Integrations
-
-- **MCP server** — `kesha mcp` exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: [docs/mcp.md](docs/mcp.md).
-- **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
-- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
-- **Raycast** (macOS) — offline microphone dictation from the launcher: *Dictate to Clipboard* records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. [Install from the Raycast Store](https://www.raycast.com/drakulavich/kesha-voice-kit) · source: [`raycast/`](raycast/).
-- **Programmatic API** — `@drakulavich/kesha-voice-kit/core` for use inside a Bun program. See [docs/api.md](docs/api.md).
-
 ## More
 
 - [Architecture](docs/architecture.md) — runtime data flow, the models that ship, the CLI ↔ Rust engine boundary, model pinning, and where tests live.

package/docs/product-positioning.md

@@ -1,6 +1,6 @@
 # Product positioning
 
-Kesha Voice Kit is a local-first voice toolkit for developers and agent workflows. It is built for small, scriptable jobs where a CLI can turn audio into text, text into audio, or voice messages into structured data without sending content to a hosted API.
+Kesha listens and talks back: an agent gets a voice message, Kesha turns it into text locally, and speaks the reply. It is a local-first voice toolkit for developers and agent workflows, and Apple Silicon is where it is fastest and most complete. It is built for small, scriptable jobs where a CLI can turn audio into text, text into audio, or voice messages into structured data without sending content to a hosted API.
 
 The product promise is not "one model for every audio problem." The promise is a boring, automatable local voice stack with clear platform limits, predictable install paths, and machine-readable output.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.0.0",
-  "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
+  "version": "2.2.0-beta.1",
+  "description": "Kesha listens and talks back: local speech to text and text to speech for agents and scripts, fastest on Apple Silicon.",
   "type": "module",
   "bin": {
     "kesha": "bin/kesha.js"
@@ -54,7 +54,7 @@
     "check": "bun run lint && bun run check:versions && bun run check:recipes && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
     "check:recipes": "bun .github/scripts/check-recipes.ts",
-    "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
+    "check:specs": "openspec validate --specs --strict",
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts",
     "check:engine-targets": "bun .github/scripts/check-engine-targets.ts",
@@ -83,9 +83,10 @@
     "url": "https://github.com/drakulavich/kesha-voice-kit/issues"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "1.14.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
     "typescript": "^7.0.2",
@@ -93,7 +94,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@toon-format/toon": "^4.1.0",
     "citty": "^0.2.2",
     "fastest-levenshtein": "^1.0.16",
@@ -109,19 +110,19 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.0.0",
+      "version": "2.2.0-beta.1",
       "sha256": {
-        "kesha-engine-darwin-arm64": "2d75bc773fb81917a0dd996124c0e18eea3b15ecc8f04fe274d41c68bda9276c",
-        "kesha-engine-linux-x64": "09082a1f3eb07d8f8051806a057669f098856d84541f087a1e614ca80d8235b2",
-        "kesha-engine-windows-x64.exe": "de86f350bfd3d076cf339d99d892605b1a37a99085e8ff4c8ef87057618193f3",
-        "say-avspeech-darwin-arm64": "a3aa5b75ddff68a48f1158e838310b37cac72ef86841d9cfcdf1ee233cb7451a",
+        "kesha-engine-darwin-arm64": "ccdd35b2433950175a6e3791ac3264969a732ea005fae4642b32842b2eb3443b",
+        "kesha-engine-linux-x64": "626fd32be46645e312ae3ad4cdf15838d0c4f54d56bdc67ec6d8f2a017813db8",
+        "kesha-engine-windows-x64.exe": "b38bc35bc2d0304f324da02b1d2857e86baf3c69e5351e5df2619c1c3a38889a",
+        "say-avspeech-darwin-arm64": "3a7e8b8fac92ce4ce0c34f736098a685dcb745f741db8303e1721e320ac73a98",
         "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
       },
       "size": {
-        "kesha-engine-darwin-arm64": 73623152,
-        "kesha-engine-linux-x64": 67392296,
-        "kesha-engine-windows-x64.exe": 66550272,
-        "say-avspeech-darwin-arm64": 64208,
+        "kesha-engine-darwin-arm64": 73639712,
+        "kesha-engine-linux-x64": 67404584,
+        "kesha-engine-windows-x64.exe": 66583040,
+        "say-avspeech-darwin-arm64": 82992,
         "kesha-textlang-darwin-arm64": 57648
       }
     }

package/src/cli/dispatch.ts

@@ -1,10 +1,12 @@
-import { runMain, type ArgsDef, type CommandDef } from "citty";
+import { renderUsage, runMain, type ArgsDef, type CommandDef } from "citty";
 import { existsSync } from "fs";
-import { log } from "../log";
+import { stripVTControlCharacters } from "util";
+import { isColorEnabled, log } from "../log";
+import { packageVersion } from "../package-info";
 import { guardStdoutWrites } from "../stdout-pipe";
 import { suggestCommand } from "../suggest-command";
 import { applyCliContext, resolveCliContext } from "./context";
-import { rejectUnknownOptions, renderInvalidArg } from "./options";
+import { rejectExtraPositionals, rejectUnknownOptions, renderInvalidArg } from "./options";
 
 // Lazy loaders so a cold CLI spawn transpiles only the invoked command, not the whole graph (#568).
 // `CommandDef<any>`: citty's generic is invariant in the arg shape and each command has its own schema.
@@ -87,7 +89,12 @@ export function unknownCommandMessages(token: string, subcommandKeys: string[]):
   if (suggestCommand(token, ["transcribe"]) === "transcribe") {
     warnLines.push("To transcribe, pass the audio path directly: kesha ./recording.ogg");
   }
-  return { errorLine: `unknown command '${token}'`, warnLines };
+  return { errorLine: renderInvalidArg(`unknown command '${token}'`), warnLines };
+}
+
+async function showUsage<T extends ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): Promise<void> {
+  const usage = await renderUsage(cmd, parent);
+  console.log((isColorEnabled() ? usage : stripVTControlCharacters(usage)) + "\n");
 }
 
 async function resolveArgsDef(command: CommandDef<any>): Promise<ArgsDef> {
@@ -121,9 +128,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
 
   switch (classifyFirstArg(firstArg, subcommandKeys)) {
     case "subcommand": {
+      if (restArgs.length === 1 && (restArgs[0] === "--version" || restArgs[0] === "-v")) {
+        process.stdout.write(`${packageVersion}\n`);
+        return;
+      }
       const command = await SUBCOMMANDS[firstArg!]!();
-      rejectUnknownOptions(restArgs, await resolveArgsDef(command));
-      await runMain(command, { rawArgs: restArgs });
+      const argsDef = await resolveArgsDef(command);
+      rejectUnknownOptions(restArgs, argsDef);
+      if (firstArg !== "install" && firstArg !== "say") rejectExtraPositionals(restArgs, argsDef);
+      await runMain(command, { rawArgs: restArgs, showUsage });
       return;
     }
 
@@ -132,7 +145,7 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
       const { errorLine, warnLines } = unknownCommandMessages(firstArg!, subcommandKeys);
       log.error(errorLine);
       for (const line of warnLines) log.warn(line);
-      process.exit(1);
+      process.exit(2);
       break;
     }
 
@@ -142,10 +155,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
         log.error(renderInvalidArg(`put global flags after the subcommand: kesha ${misplaced} ...`));
         process.exit(2);
       }
-      const { createMainCommand } = await import("./main");
+      const { briefMainUsage, createMainCommand } = await import("./main");
       const command = createMainCommand(context);
-      rejectUnknownOptions(rawArgs, await resolveArgsDef(command));
-      await runMain(command, { rawArgs });
+      const help = rawArgs.includes("--help") || rawArgs.includes("-h");
+      rejectUnknownOptions(help ? rawArgs.filter((arg) => arg !== "--all") : rawArgs, await resolveArgsDef(command));
+      if (help) {
+        await showUsage(rawArgs.includes("--all") ? command : briefMainUsage(command));
+        return;
+      }
+      await runMain(command, { rawArgs, showUsage });
     }
   }
 }

package/src/cli/init.ts

@@ -3,7 +3,7 @@ import { confirm, multiselect, isCancel, cancel } from "@clack/prompts";
 import { installCommandTokens, renderInstallPlan } from "../install-plan";
 import { log } from "../log";
 import { errorMessage } from "../error-utils";
-import { exitCodeFor } from "../engine/events";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { getEngineCapabilities } from "../engine";
 import {
   installableTtsLangs,
@@ -98,30 +98,6 @@ export function initInstallArgs(selection: InitSelection): string[] {
   return installCommandTokens(selection, selection.ttsLangs);
 }
 
-export function initSuggestionCommands(
-  selection: InitSelection,
-  canDiarize = canInstallDiarizeOnPlatform(),
-): string[][] {
-  const variants: InitSelection[] = [
-    selection,
-    { ...selection, ttsLangs: [], vad: true, diarize: false },
-    { ...selection, ttsLangs: ["en"], vad: true, diarize: false },
-  ];
-
-  // #768: --diarize installs VAD on its own, so no explicit --vad here.
-  if (canDiarize) {
-    variants.push({ ...selection, ttsLangs: [], vad: false, diarize: true });
-  }
-
-  const seen = new Set<string>();
-  return variants.map(initInstallArgs).filter((command) => {
-    const key = command.join("\0");
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
 export function omitUnsupportedDiarize(
   selection: InitSelection,
   canDiarize = canInstallDiarizeOnPlatform(),
@@ -176,14 +152,7 @@ export async function promptInitSelection(
   };
 }
 
-/** Mirrors the guard in `performInstall`: a preview must not describe an install this platform rejects (#684). */
-async function printPlan(selection: InitSelection): Promise<boolean> {
-  const backendError = unavailableBackendRefusal(selection.backend);
-  if (backendError) {
-    log.error(errorMessage(backendError));
-    process.exitCode = exitCodeFor(backendError);
-    return false;
-  }
+async function printPlan(selection: InitSelection): Promise<void> {
   log.info(
     await renderInstallPlan({
       noCache: selection.noCache,
@@ -193,21 +162,6 @@ async function printPlan(selection: InitSelection): Promise<boolean> {
       diarize: selection.diarize,
     }),
   );
-  return true;
-}
-
-async function runNonInteractive(selection: InitSelection): Promise<void> {
-  const canDiarize = canInstallDiarizeOnPlatform();
-  const printableSelection = omitUnsupportedDiarize(selection, canDiarize);
-  if (selection.diarize && !canDiarize) {
-    log.warn("--diarize is currently darwin-arm64 only; omitting it from non-interactive examples.");
-  }
-  log.info(renderInitOverview(canDiarize));
-  if (!(await printPlan(printableSelection))) return;
-  log.info("Run one of these commands from an interactive terminal:");
-  for (const command of initSuggestionCommands(printableSelection, canDiarize)) {
-    log.info(`  ${command.join(" ")}`);
-  }
 }
 
 export const initCommand = defineCommand({
@@ -262,6 +216,13 @@ export const initCommand = defineCommand({
     const noCache = resolveNoCacheFlag(args, rawArgs);
     const selection = resolveInitSelection(args, backend, noCache);
 
+    const backendError = args.yes && !args.plan ? null : unavailableBackendRefusal(backend);
+    if (backendError) {
+      log.error(errorMessage(backendError));
+      process.exitCode = exitCodeFor(backendError);
+      return;
+    }
+
     if (args.plan) {
       log.info(renderInitOverview());
       await printPlan(selection);
@@ -280,7 +241,11 @@ export const initCommand = defineCommand({
     const stdinIsTty = process.stdin.isTTY === true;
     const stdoutIsTty = process.stdout.isTTY === true;
     if (!stdinIsTty || !stdoutIsTty) {
-      await runNonInteractive(selection);
+      const noTerminal = new KeshaError("E_INVALID_ARG", "kesha init is interactive and needs a terminal", {
+        hint: "run `kesha init --yes` to install the defaults, or `kesha init --plan` to show the plan",
+      });
+      log.error(errorMessage(noTerminal));
+      process.exitCode = exitCodeFor(noTerminal);
       return;
     }
 
@@ -293,7 +258,7 @@ export const initCommand = defineCommand({
       noCache,
     );
     log.info("");
-    if (!(await printPlan(prompted))) return;
+    await printPlan(prompted);
     const confirmed = await promptConfirm(
       `Run \`${initInstallArgs(prompted).join(" ")}\` now?`,
       true,

package/src/cli/install.ts

@@ -246,7 +246,7 @@ export async function performInstall(options: PerformInstallOptions) {
       throw backendError;
     }
     await installEngine({ noCache, backend, ttsLangs, vad, diarize, version: engineVersion });
-    await maybeAskForStar(getEngineBinPath(), packageVersion, log);
+    if (!log.quietEnabled) await maybeAskForStar(getEngineBinPath(), packageVersion, { info: log.progress, warn: log.warn });
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
     const signalExitCode = getPendingSignalExitCode();

package/src/cli/logs.ts

@@ -23,6 +23,9 @@ export function runLogsAction(args: LogsCommandArgs): ActionResult {
   if (args.json && action !== "status") {
     return { ok: false, error: "usage: kesha logs status --json" };
   }
+  if (args.value !== undefined && action !== "mode" && SUPPORTED_ACTIONS.split(", ").includes(action)) {
+    return { ok: false, error: `unexpected argument '${args.value}' (kesha logs ${action} takes no value)` };
+  }
   switch (action) {
     case "enable": {
       const status = setDiagnosticLogMode("on");

package/src/cli/main.ts

@@ -1,10 +1,13 @@
-import { defineCommand } from "citty";
+import { defineCommand, type ArgsDef, type CommandDef } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
 import { isDirectoryPath, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
 
 export { isDirectoryPath };
-import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
+import { detectAudioLanguageEngine, detectTextLanguageEngine, isEngineInstalled } from "../engine";
+import { renderInstallPlan } from "../install-plan";
+import { canInstallDiarizeOnPlatform, promptConfirm } from "./init";
+import { performInstall } from "./install";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
 import type { TextLangDetectResult, TranscribeErrorRecord, TranscribeResult } from "../types";
@@ -409,7 +412,8 @@ async function processFile(
       error_code: code,
     });
     log.error(`${file}: ${stderrText}`);
-    return { ok: false, error: { file, code, message: stderrText }, exitCode: failureExitCode(err) };
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { file, code, message }, exitCode: failureExitCode(err) };
   }
 }
 
@@ -452,13 +456,41 @@ export const MAIN_VAD_ARGS = {
   },
 } as const;
 
+const BRIEF_HELP_DESCRIPTION =
+  "Kesha Voice Kit listens and talks back: local speech for agents and scripts.\n" +
+  "Try: kesha audio.ogg, or kesha say \"hello\"\n" +
+  "\n" +
+  "Commands:\n" +
+  "  init      Interactive setup guide.\n" +
+  "  install   Download engine and models.\n" +
+  "  say       Synthesize speech from text.\n" +
+  "  record    Record microphone audio.\n" +
+  "  status    Inspect installed backend.\n" +
+  "  doctor    Collect support diagnostics.\n" +
+  "  mcp       Run an MCP server over stdio.\n" +
+  "\n" +
+  "All commands and flags: kesha --help --all";
+
+const BRIEF_HELP_ARGS: ArgsDef = {
+  json: { type: "boolean", description: "Output results as JSON" },
+  format: { type: "string", description: "transcript | json | toon" },
+  lang: { type: "string", description: "Expected language code, e.g. en" },
+  timestamps: { type: "boolean", description: "Timestamped segments in JSON/TOON" },
+  quiet: { type: "boolean", alias: "q", description: "Print only results and errors" },
+};
+
+/** What plain `kesha --help` renders; parsing still uses every flag of createMainCommand. */
+export function briefMainUsage(command: CommandDef<any>): CommandDef<any> {
+  return { ...command, meta: { ...command.meta, description: BRIEF_HELP_DESCRIPTION }, args: BRIEF_HELP_ARGS };
+}
+
 export function createMainCommand(context: CliContext = { quiet: false, disableColor: false }) {
   return defineCommand({
     meta: {
       name: "kesha",
       version: packageVersion,
       description:
-        "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
+        "Kesha Voice Kit listens and talks back: local speech for agents and scripts.\n" +
         "\n" +
         "Examples:\n" +
         "  kesha audio.ogg          Transcribe an audio file.\n" +
@@ -572,6 +604,19 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         process.exit(2);
       }
 
+      if (
+        !isEngineInstalled() &&
+        process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY &&
+        files.every((f) => existsSync(f) && !isDirectoryPath(f)) &&
+        (!args.speakers || canInstallDiarizeOnPlatform())
+      ) {
+        const modules = { vad: vadMode === "on", diarize: Boolean(args.speakers) };
+        log.info(await renderInstallPlan(modules));
+        if (await promptConfirm("Kesha needs these downloads before it can transcribe. Download them now?", true)) {
+          await performInstall({ noCache: false, ttsLangs: [], ...modules });
+        }
+      }
+
       const wantsLangId = !!(args.lang || args.verbose || outputFormat !== "text");
       const reportProgress = shouldReportTranscribeProgress({
         stderrIsTty: process.stderr.isTTY === true,

package/src/cli/options.ts

@@ -17,6 +17,10 @@ function camelCase(name: string): string {
 
 /** The first flag `argsDef` does not declare, or null; citty parses non-strict, so the flag would otherwise vanish and its value become a positional (S9-F3). */
 export function findUnknownOption(rawArgs: string[], argsDef: ArgsDef): UnknownOption | null {
+  return scanArgs(rawArgs, argsDef).unknown;
+}
+
+function scanArgs(rawArgs: string[], argsDef: ArgsDef): { unknown: UnknownOption | null; positionals: string[] } {
   const long = new Set(RUNNER_LONG);
   const short = new Set(RUNNER_SHORT);
   const valued = new Set<string>();
@@ -41,23 +45,30 @@ export function findUnknownOption(rawArgs: string[], argsDef: ArgsDef): UnknownO
     const match = suggestCommand(name, suggestable);
     return match === null ? null : `--${match}`;
   };
+  const positionals: string[] = [];
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i]!;
-    if (arg === "--") break;
-    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) continue;
+    if (arg === "--") {
+      positionals.push(...rawArgs.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) {
+      positionals.push(arg);
+      continue;
+    }
     if (arg.startsWith("--")) {
       const eq = arg.indexOf("=");
       const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
-      if (!long.has(name)) return { name: `--${name}`, suggestion: suggest(name) };
+      if (!long.has(name)) return { unknown: { name: `--${name}`, suggestion: suggest(name) }, positionals };
       if (eq === -1 && valued.has(name)) i++;
       continue;
     }
     for (const letter of arg.slice(1)) {
-      if (!short.has(letter)) return { name: `-${letter}`, suggestion: null };
+      if (!short.has(letter)) return { unknown: { name: `-${letter}`, suggestion: null }, positionals };
     }
     if (valued.has(arg[arg.length - 1]!)) i++;
   }
-  return null;
+  return { unknown: null, positionals };
 }
 
 /** The coded line for a usage error the CLI refuses before doing anything (S9-F2). */
@@ -77,3 +88,13 @@ export function rejectUnknownOptions(rawArgs: string[], argsDef: ArgsDef): void
   log.error(renderUnknownOption(unknown));
   process.exit(2);
 }
+
+/** Exits 2 with one coded stderr line when `rawArgs` carries more positionals than the command declares. */
+export function rejectExtraPositionals(rawArgs: string[], argsDef: ArgsDef): void {
+  const declared = Object.values(argsDef).filter((def) => def.type === "positional").length;
+  const extra = scanArgs(rawArgs, argsDef).positionals[declared];
+  if (extra === undefined) return;
+  const tail = "output" in argsDef ? ` (did you mean --output ${extra}?)` : "";
+  log.error(renderInvalidArg(`unexpected argument '${extra}'${tail}`));
+  process.exit(2);
+}

package/src/cli/say.ts

@@ -358,8 +358,8 @@ export const sayCommand = defineCommand({
         log.error(errorMessage(err));
         process.exit(exitCodeFor(err));
       }
-      await Bun.write(Bun.stdout, ids.map((id) => `${id}\n`).join(""));
-      process.exit(0);
+      process.stdout.write(ids.map((id) => `${id}\n`).join(""));
+      return;
     }
 
     const flags = resolveSayFlags(args);
@@ -374,23 +374,26 @@ export const sayCommand = defineCommand({
       process.exit(2);
     }
 
-    const inlineText = typeof args.text === "string" ? args.text : undefined;
+    const positionals = (args._ ?? []).map(String);
+    const inlineText =
+      positionals.length > 0 ? positionals.join(" ") : typeof args.text === "string" ? args.text : undefined;
     const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;
     if (shouldRejectMissingSayText(inlineText, stdinIsTty)) {
       log.error(renderInvalidArg("kesha say requires text or piped stdin. Usage: kesha say <text>"));
       process.exit(2);
     }
+    const explicitVoice = flags.voice;
+    const langHint = flags.lang;
     let text: string;
+    let voice: string | undefined;
     try {
       text = await resolveText(inlineText);
       validateSayText(text);
+      voice = await resolveSayVoice(explicitVoice, langHint, text);
     } catch (err) {
       log.error(errorMessage(err));
       process.exit(exitCodeFor(err));
     }
-    const explicitVoice = flags.voice;
-    const langHint = flags.lang;
-    const voice = await resolveSayVoice(explicitVoice, langHint, text);
 
     const opts: SayOpts = {
       text,

package/src/cli/stats.ts

@@ -26,6 +26,14 @@ const SUPPORTED_ACTIONS = "enable, disable, status, week, errors, export, reset,
 /** Runs one `kesha stats` action and reports what to print; all output happens in the caller. */
 export function runStatsAction(args: StatsCommandArgs): ActionResult {
   const action = args.action ?? "status";
+  if (
+    args.value !== undefined &&
+    action !== "export" &&
+    action !== "retention" &&
+    SUPPORTED_ACTIONS.split(", ").includes(action)
+  ) {
+    return { ok: false, error: `unexpected argument '${args.value}' (kesha stats ${action} takes no value)` };
+  }
   switch (action) {
     case "enable": {
       enableStats();

package/src/cli/support-bundle.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { createSupportBundle } from "../support-bundle";
 import { log } from "../log";
 
@@ -26,16 +27,25 @@ export const supportBundleCommand = defineCommand({
   },
   async run({ args }: { args: SupportBundleCommandArgs }) {
     try {
+      if (args.output === "") {
+        throw new KeshaError("E_INVALID_ARG", "--output needs a file path", { hint: "pass --output path.tar.gz." });
+      }
+      if (args.output === "-") {
+        throw new KeshaError("E_INVALID_ARG", "--output - is not a file path", {
+          hint: "to write the archive to stdout, pass --output /dev/stdout.",
+        });
+      }
       const bundle = await createSupportBundle({
         output: args.output,
         includeLogs: Boolean(args["include-logs"]),
       });
-      log.status(`Created support bundle: ${bundle.path}`);
+      log.notice(`Created support bundle: ${bundle.path}`);
       log.status(`Entries: ${bundle.entries.length}`);
       log.status(`Size: ${bundle.sizeBytes} bytes`);
     } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "EPIPE") return;
       log.error(errorMessage(err));
-      process.exit(1);
+      process.exit(err instanceof KeshaError ? exitCodeFor(err) : 1);
     }
   },
 });

package/src/cli.ts

@@ -9,7 +9,6 @@ export {
   canInstallDiarizeOnPlatform,
   initCommand,
   initInstallArgs,
-  initSuggestionCommands,
   omitUnsupportedDiarize,
   promptInitSelection,
   renderInitOverview,

package/src/doctor.ts

@@ -10,7 +10,7 @@ import {
   NOT_FUNCTIONAL_STATE,
   probeExecutable,
 } from "./engine-health";
-import { readInstalledEngineVersion } from "./engine-version-marker";
+import { MIN_ENGINE_VERSION, predatesMinimumEngine, readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
 import { installedVoiceIds } from "./voice-inventory";
 import { engineVersion, packageName, packageVersion } from "./package-info";
@@ -85,13 +85,14 @@ type DoctorDiagnosticLogStatus = DiagnosticLogStatus & { error?: string };
  * is a supported state (`kesha install --engine-version`), not a fault — `unrecorded` is
  * separate so a missing marker is never reported as a difference.
  */
-export type EngineVersionState = "matches-pin" | "differs-from-pin" | "unrecorded";
+export type EngineVersionState = "matches-pin" | "differs-from-pin" | "unsupported" | "unrecorded";
 
 export function engineVersionState(
   versionMarker: string | null,
   pinnedVersion: string,
 ): EngineVersionState {
   if (versionMarker === null) return "unrecorded";
+  if (predatesMinimumEngine(versionMarker)) return "unsupported";
   return versionMarker === pinnedVersion ? "matches-pin" : "differs-from-pin";
 }
 
@@ -477,6 +478,11 @@ function formatVersionState(engine: DoctorReport["engine"]): string {
         `installed v${engine.versionMarker} differs from the pinned v${engine.pinnedVersion} — ` +
         "supported; `kesha install` without --engine-version restores the pin"
       );
+    case "unsupported":
+      return (
+        `installed v${engine.versionMarker} is older than v${MIN_ENGINE_VERSION}, ` +
+        "the oldest engine this CLI supports; run `kesha install`"
+      );
     case "unrecorded":
       return engine.installed
         ? "no recorded version beside the binary; `kesha install` records one"