@drakulavich/kesha-voice-kit 1.30.0 → 1.31.0

package/README.md

@@ -158,7 +158,7 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - [Use cases](docs/use-cases.md) — copy-paste recipes (transcribe a meeting, speak from OpenClaw, run offline, move the cache).
 - [Product positioning](docs/product-positioning.md) — supported workflows, non-goals, maturity labels, platform matrix.
 - [Changelog](CHANGELOG.md) — every release, with the behaviour changes spelled out.
-- **Diagnostics:** `kesha doctor`, `kesha support-bundle` (redacted `.tar.gz` for issues), and `kesha logs` produce local, content-free diagnostics — see [docs/diagnostic-logs.md](docs/diagnostic-logs.md). Every failure prints a stable `error [CODE]: …` line and a documented [process exit code](docs/errors.md#process-exit-codes).
+- **Diagnostics:** `kesha doctor`, `kesha support-bundle` (redacted `.tar.gz` for issues), and `kesha logs` produce local, content-free diagnostics — see [docs/diagnostic-logs.md](docs/diagnostic-logs.md). One variable, `KESHA_HOME`, moves everything Kesha writes (models, logs, stats) into a directory of your choice — see [where Kesha keeps its files](docs/diagnostic-logs.md#where-kesha-keeps-its-files). Every failure prints a stable `error [CODE]: …` line and a documented [process exit code](docs/errors.md#process-exit-codes).
 - **Scripting & CI:** `--json` (or `--toon`) for machine-readable output, `--include-errors` (with either) to get per-file failures on stdout alongside the results, `--quiet`/`-q` to silence progress, and `--no-color` (or `NO_COLOR=1`) for plain logs. Colors switch off automatically when `CI=true`.
 - **Privacy / Local Stats:** Stats are **off by default** and fully local. Opt in with `kesha stats enable` to record content-free operational metrics in a local SQLite database — never networked, never storing audio, transcripts, text, or paths. Full commands & lifecycle: [docs/local-stats.md](docs/local-stats.md).
 

package/completions/kesha.bash

@@ -38,4 +38,4 @@ _kesha_completion() {
   fi
 }
 
-complete -F _kesha_completion kesha
+complete -o default -F _kesha_completion kesha

package/completions/kesha.fish

@@ -1,5 +1,4 @@
 # fish completion for kesha.
-complete -c kesha -f
 complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
 complete -c kesha -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
 complete -c kesha -n '__fish_use_subcommand' -a 'init' -d 'Interactive setup guide for Kesha features'

package/completions/kesha.zsh

@@ -40,6 +40,7 @@ _kesha() {
       '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
     else
       _describe -t commands 'kesha command' commands
+      _files
     fi
     return
   fi
@@ -155,7 +156,8 @@ _kesha() {
       '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
       '--no-vad[Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers]' \
       '--quiet[Suppress progress output; print only results and errors]' \
-      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
+      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]' \
+      '*:audio file:_files'
       ;;
   esac
 }

package/docs/diagnostic-logs.md

@@ -43,9 +43,11 @@ stage names, exit codes, duration numbers, and stable error codes.
 
 When enabled, `kesha install`, `kesha <audio>`, and `kesha say` record command
 lifecycle events such as `command.start`, `input.audio`, `input.missing`,
-`engine.exit`, and `command.finish`. These events use only counts, booleans,
-format extensions, duration milliseconds, and bucket labels. In the default
-`retain-on-failure` mode, successful runs still leave no log file behind.
+`engine.exit`, `engine.debug` (the Engine's own `KESHA_DEBUG` timeline, carrying
+its event name and typed fields but never its message text), and `command.finish`.
+These events use only counts, booleans, format extensions, duration milliseconds,
+and bucket labels. In the default `retain-on-failure` mode, successful runs still
+leave no log file behind.
 
 Diagnostic logs must not store:
 
@@ -75,6 +77,37 @@ Set `KESHA_LOG_DIR` to override the directory. The active file is
 `kesha.ndjson`; rotated files are named `kesha.1.ndjson`, `kesha.2.ndjson`, and
 so on.
 
+## Where Kesha keeps its files
+
+Kesha writes to four places. Each resolves by the same rule: its own variable
+when set, otherwise the path under `KESHA_HOME` when that is set, otherwise the
+platform default. `KESHA_HOME` uses one layout on every platform, so a test run,
+a CI job or a second profile needs exactly one variable to leave your real
+models, logs and Stats untouched. Nothing is moved when you set it: a fresh
+`KESHA_HOME` starts with an empty cache, and `kesha install` fills it. Two roots FluidAudio owns stay outside it on darwin-arm64: the Kokoro ANE bundles and voice packs under `~/.cache/fluidaudio`, and its Silero VAD copy under `~/Library/Application Support/FluidAudio`; `status --disk` reports both as external roots, and `kesha install --tts` stages into the first regardless of `KESHA_HOME`.
+
+| What | Default (macOS / Windows / Linux) | Under `KESHA_HOME` | Own variable |
+|---|---|---|---|
+| Model cache: engine, models, `recordings/` | `~/.cache/kesha` everywhere | `<home>/cache` | `KESHA_CACHE_DIR` |
+| Diagnostic log directory | `~/Library/Logs/kesha` / `%LOCALAPPDATA%\kesha\logs` / `$XDG_STATE_HOME/kesha/logs` | `<home>/logs` | `KESHA_LOG_DIR` |
+| Stats DB | `~/Library/Application Support/kesha/stats.sqlite` / `%APPDATA%\kesha\stats.sqlite` / `$XDG_DATA_HOME/kesha/stats.sqlite` | `<home>/stats.sqlite` | `KESHA_STATS_DB` |
+| MCP audio (`kesha mcp` synthesis output) | `<tmpdir>/kesha-mcp` | `<home>/mcp-audio` | none |
+
+`kesha status --json` and `kesha doctor --json` report every path together with
+the rule that decided it (`default`, `KESHA_HOME`, or the variable name), so an
+isolated run can be verified from one command:
+
+```bash
+KESHA_HOME=/tmp/kesha-ci kesha status --json | jq .paths
+```
+
+An empty variable counts as unset; a relative path is resolved against the
+working directory when the command starts. The engine itself reads only
+`KESHA_CACHE_DIR`, so the CLI hands it the resolved cache root under that name
+whenever `KESHA_HOME` decided it. FluidAudio's own Silero VAD copy under
+`~/Library/Application Support/FluidAudio` is placed by FluidAudio and stays
+outside `KESHA_HOME`; `kesha status --disk` lists it as an external root.
+
 The first implementation rotates at 10 MB and keeps 5 rotated files. `kesha logs
 reset` deletes Kesha log files but preserves the selected mode.
 

package/model-plan.json

@@ -34,6 +34,136 @@
     { "relPath": "models/vosk-ru/bert/model.onnx", "sizeBytes": 654361598 },
     { "relPath": "models/vosk-ru/bert/vocab.txt", "sizeBytes": 1780720 }
   ],
+  "aneEn": [
+    { "relPath": "KokoroAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlbert.mlmodelc/coremldata.bin", "sizeBytes": 433 },
+    { "relPath": "KokoroAlbert.mlmodelc/metadata.json", "sizeBytes": 2480 },
+    { "relPath": "KokoroAlbert.mlmodelc/model.mil", "sizeBytes": 101485 },
+    { "relPath": "KokoroAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 5718848 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/coremldata.bin", "sizeBytes": 556 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/metadata.json", "sizeBytes": 4171 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/model.mil", "sizeBytes": 60047 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 13806464 },
+    { "relPath": "KokoroAlignment.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlignment.mlmodelc/coremldata.bin", "sizeBytes": 484 },
+    { "relPath": "KokoroAlignment.mlmodelc/metadata.json", "sizeBytes": 3021 },
+    { "relPath": "KokoroAlignment.mlmodelc/model.mil", "sizeBytes": 8194 },
+    { "relPath": "KokoroAlignment.mlmodelc/weights/weight.bin", "sizeBytes": 4128 },
+    { "relPath": "KokoroProsody.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroProsody.mlmodelc/coremldata.bin", "sizeBytes": 421 },
+    { "relPath": "KokoroProsody.mlmodelc/metadata.json", "sizeBytes": 2721 },
+    { "relPath": "KokoroProsody.mlmodelc/model.mil", "sizeBytes": 79705 },
+    { "relPath": "KokoroProsody.mlmodelc/weights/weight.bin", "sizeBytes": 8454272 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/coremldata.bin", "sizeBytes": 440 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/metadata.json", "sizeBytes": 3020 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/model.mil", "sizeBytes": 93152 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
+    { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 626 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4392 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309130 },
+    { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
+    { "relPath": "KokoroTail.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "vocab.json", "sizeBytes": 1416 },
+    { "relPath": "af_heart.bin", "sizeBytes": 522240 }
+  ],
+  "kokoroG2p": [
+    { "relPath": "G2PEncoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "G2PEncoder.mlmodelc/coremldata.bin", "sizeBytes": 398 },
+    { "relPath": "G2PEncoder.mlmodelc/metadata.json", "sizeBytes": 2034 },
+    { "relPath": "G2PEncoder.mlmodelc/model.mil", "sizeBytes": 20392 },
+    { "relPath": "G2PEncoder.mlmodelc/weights/weight.bin", "sizeBytes": 694592 },
+    { "relPath": "G2PDecoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "G2PDecoder.mlmodelc/coremldata.bin", "sizeBytes": 545 },
+    { "relPath": "G2PDecoder.mlmodelc/metadata.json", "sizeBytes": 3064 },
+    { "relPath": "G2PDecoder.mlmodelc/model.mil", "sizeBytes": 19737 },
+    { "relPath": "G2PDecoder.mlmodelc/weights/weight.bin", "sizeBytes": 828030 },
+    { "relPath": "g2p_vocab.json", "sizeBytes": 1665 },
+    { "relPath": "us_lexicon_cache.json", "sizeBytes": 10444631 }
+  ],
+  "aneVoices": [
+    { "relPath": "af_alloy.bin", "sizeBytes": 522240 },
+    { "relPath": "af_aoede.bin", "sizeBytes": 522240 },
+    { "relPath": "af_bella.bin", "sizeBytes": 522240 },
+    { "relPath": "af_jessica.bin", "sizeBytes": 522240 },
+    { "relPath": "af_kore.bin", "sizeBytes": 522240 },
+    { "relPath": "af_nicole.bin", "sizeBytes": 522240 },
+    { "relPath": "af_nova.bin", "sizeBytes": 522240 },
+    { "relPath": "af_river.bin", "sizeBytes": 522240 },
+    { "relPath": "af_sarah.bin", "sizeBytes": 522240 },
+    { "relPath": "af_sky.bin", "sizeBytes": 522240 },
+    { "relPath": "am_adam.bin", "sizeBytes": 522240 },
+    { "relPath": "am_echo.bin", "sizeBytes": 522240 },
+    { "relPath": "am_eric.bin", "sizeBytes": 522240 },
+    { "relPath": "am_fenrir.bin", "sizeBytes": 522240 },
+    { "relPath": "am_liam.bin", "sizeBytes": 522240 },
+    { "relPath": "am_michael.bin", "sizeBytes": 522240 },
+    { "relPath": "am_onyx.bin", "sizeBytes": 522240 },
+    { "relPath": "am_puck.bin", "sizeBytes": 522240 },
+    { "relPath": "am_santa.bin", "sizeBytes": 522240 },
+    { "relPath": "bm_lewis.bin", "sizeBytes": 522240 },
+    { "relPath": "em_alex.bin", "sizeBytes": 522240 },
+    { "relPath": "ff_siwis.bin", "sizeBytes": 522240 },
+    { "relPath": "hm_omega.bin", "sizeBytes": 522240 },
+    { "relPath": "im_nicola.bin", "sizeBytes": 522240 },
+    { "relPath": "jm_kumo.bin", "sizeBytes": 522240 },
+    { "relPath": "pm_alex.bin", "sizeBytes": 522240 }
+  ],
+  "aneZh": [
+    { "relPath": "KokoroAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlbert.mlmodelc/coremldata.bin", "sizeBytes": 433 },
+    { "relPath": "KokoroAlbert.mlmodelc/metadata.json", "sizeBytes": 2480 },
+    { "relPath": "KokoroAlbert.mlmodelc/model.mil", "sizeBytes": 101485 },
+    { "relPath": "KokoroAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 5718848 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/coremldata.bin", "sizeBytes": 556 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/metadata.json", "sizeBytes": 4171 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/model.mil", "sizeBytes": 60047 },
+    { "relPath": "KokoroPostAlbert.mlmodelc/weights/weight.bin", "sizeBytes": 13806464 },
+    { "relPath": "KokoroAlignment.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroAlignment.mlmodelc/coremldata.bin", "sizeBytes": 484 },
+    { "relPath": "KokoroAlignment.mlmodelc/metadata.json", "sizeBytes": 3021 },
+    { "relPath": "KokoroAlignment.mlmodelc/model.mil", "sizeBytes": 8194 },
+    { "relPath": "KokoroAlignment.mlmodelc/weights/weight.bin", "sizeBytes": 4128 },
+    { "relPath": "KokoroProsody.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroProsody.mlmodelc/coremldata.bin", "sizeBytes": 422 },
+    { "relPath": "KokoroProsody.mlmodelc/metadata.json", "sizeBytes": 2721 },
+    { "relPath": "KokoroProsody.mlmodelc/model.mil", "sizeBytes": 79705 },
+    { "relPath": "KokoroProsody.mlmodelc/weights/weight.bin", "sizeBytes": 8454272 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/coremldata.bin", "sizeBytes": 440 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/metadata.json", "sizeBytes": 3091 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/model.mil", "sizeBytes": 93152 },
+    { "relPath": "KokoroNoise_v2.mlmodelc/weights/weight.bin", "sizeBytes": 4580160 },
+    { "relPath": "KokoroVocoder.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroVocoder.mlmodelc/coremldata.bin", "sizeBytes": 627 },
+    { "relPath": "KokoroVocoder.mlmodelc/metadata.json", "sizeBytes": 4392 },
+    { "relPath": "KokoroVocoder.mlmodelc/model.mil", "sizeBytes": 309127 },
+    { "relPath": "KokoroVocoder.mlmodelc/weights/weight.bin", "sizeBytes": 48889920 },
+    { "relPath": "KokoroTail.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "KokoroTail.mlmodelc/coremldata.bin", "sizeBytes": 392 },
+    { "relPath": "KokoroTail.mlmodelc/metadata.json", "sizeBytes": 1872 },
+    { "relPath": "KokoroTail.mlmodelc/model.mil", "sizeBytes": 7014 },
+    { "relPath": "KokoroTail.mlmodelc/weights/weight.bin", "sizeBytes": 81088 },
+    { "relPath": "vocab.json", "sizeBytes": 1796 },
+    { "relPath": "voices/zf_001.bin", "sizeBytes": 522240 },
+    { "relPath": "voices/zm_050.bin", "sizeBytes": 522240 },
+    { "relPath": "g2pw/g2pw.mlmodelc/analytics/coremldata.bin", "sizeBytes": 243 },
+    { "relPath": "g2pw/g2pw.mlmodelc/coremldata.bin", "sizeBytes": 515 },
+    { "relPath": "g2pw/g2pw.mlmodelc/metadata.json", "sizeBytes": 3717 },
+    { "relPath": "g2pw/g2pw.mlmodelc/model.mil", "sizeBytes": 245446 },
+    { "relPath": "g2pw/g2pw.mlmodelc/weights/weight.bin", "sizeBytes": 159294962 }
+  ],
+  "aneZhG2p": [
+    { "relPath": "g2p/pinyin_phrases.bin", "sizeBytes": 9552083 },
+    { "relPath": "g2p/pinyin_single.bin", "sizeBytes": 480169 }
+  ],
   "diarize": [
     { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Manifest.json", "sizeBytes": 617 },
     { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/model.mlmodel", "sizeBytes": 856521 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     }
   },
   "keshaEngine": {
-    "version": "1.25.0"
+    "version": "1.26.0"
   },
   "scripts": {
     "test": "bun test --timeout 30000",

package/src/cli/action-result.ts

@@ -1,4 +1,5 @@
 import { log } from "../log";
+import { renderInvalidArg } from "./options";
 
 export type ActionMessage = { level: "success" | "info" | "warn"; text: string };
 
@@ -9,7 +10,7 @@ export type ActionResult =
 /** Renders an action's messages, writing `stdout` verbatim; a rejected action exits 2. */
 export function emitActionResult(result: ActionResult): void {
   if (!result.ok) {
-    log.error(result.error);
+    log.error(renderInvalidArg(result.error));
     if (result.hint) log.warn(result.hint);
     process.exit(2);
   }

package/src/cli/command-session.ts

@@ -50,9 +50,8 @@ export async function runCommandSession(
   setEngineDebugSink((event) =>
     session.diagnosticLog.event("engine.debug", {
       t_ms: event.t_ms,
-      event: event.event ?? null,
-      message: event.message,
-      fields: event.fields === undefined ? null : JSON.stringify(event.fields),
+      engineEvent: event.event ?? null,
+      ...engineDebugFields(event.fields),
     }),
   );
   let outcome: CommandOutcome;
@@ -74,6 +73,18 @@ export async function runCommandSession(
   return outcome;
 }
 
+// The message is prose and `event` is a reserved log field, so only the engine's typed fields ride along (Exploratory S9-F5).
+function engineDebugFields(fields: unknown): DiagnosticLogFields {
+  const out: DiagnosticLogFields = {};
+  if (!fields || typeof fields !== "object" || Array.isArray(fields)) return out;
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
 function closeSessionQuietly(
   session: CommandSession,
   command: StatsCommandName,

package/src/cli/completions.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { log } from "../log";
+import { renderInvalidArg } from "./options";
 // Inlined because import.meta.url escapes the embedded filesystem in the compiled .deb/.rpm binary (#914).
 import bashCompletions from "../../completions/kesha.bash" with { type: "text" };
 import zshCompletions from "../../completions/kesha.zsh" with { type: "text" };
@@ -29,14 +30,15 @@ export const completionsCommand = defineCommand({
   args: {
     shell: {
       type: "positional",
-      required: true,
+      required: false,
       description: "Shell: bash | zsh | fish",
     },
   },
   async run({ args }: { args: CompletionsCommandArgs }) {
     const shell = args.shell;
     if (!shell || !isShell(shell)) {
-      log.error("usage: kesha completions <bash|zsh|fish>");
+      log.error(renderInvalidArg(shell ? `unknown shell '${shell}' (bash, zsh or fish)` : "missing shell (bash, zsh or fish)"));
+      process.stderr.write("usage: kesha completions <bash|zsh|fish>\n");
       process.exit(2);
     }
     process.stdout.write(SHELL_SCRIPTS[shell]);

package/src/cli/dispatch.ts

@@ -1,9 +1,10 @@
-import { runMain, type CommandDef } from "citty";
+import { runMain, type ArgsDef, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
 import { guardStdoutWrites } from "../stdout-pipe";
 import { suggestCommand } from "../suggest-command";
 import { applyCliContext, resolveCliContext } from "./context";
+import { 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.
@@ -89,18 +90,42 @@ export function unknownCommandMessages(token: string, subcommandKeys: string[]):
   return { errorLine: `unknown command '${token}'`, warnLines };
 }
 
+async function resolveArgsDef(command: CommandDef<any>): Promise<ArgsDef> {
+  const args = command.args;
+  return (typeof args === "function" ? await args() : await args) ?? {};
+}
+
+/** `kesha --json record --out j.wav` is `record --json --out j.wav`: flag-shaped tokens before a subcommand name move behind it (S3-F3). */
+export function hoistLeadingFlags(rawArgs: string[], subcommandKeys: string[]): string[] {
+  let i = 0;
+  while (i < rawArgs.length && rawArgs[i]!.startsWith("-") && rawArgs[i] !== "--") i++;
+  const name = rawArgs[i];
+  if (i === 0 || name === undefined || !subcommandKeys.includes(name)) return rawArgs;
+  return [name, ...rawArgs.slice(0, i), ...rawArgs.slice(i + 1)];
+}
+
+/** A subcommand name that a valued leading flag hid from hoisting, unless a file of that name exists. */
+function misplacedSubcommand(rawArgs: string[], subcommandKeys: string[]): string | undefined {
+  const end = rawArgs.indexOf("--");
+  return rawArgs.slice(0, end === -1 ? undefined : end).find((arg) => subcommandKeys.includes(arg) && !existsSync(arg));
+}
+
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
   guardStdoutWrites();
   const context = resolveCliContext(argv);
   applyCliContext(context);
 
-  const [firstArg, ...restArgs] = context.rawArgs;
   const subcommandKeys = SUBCOMMAND_NAMES;
+  const rawArgs = hoistLeadingFlags(context.rawArgs, subcommandKeys);
+  const [firstArg, ...restArgs] = rawArgs;
 
   switch (classifyFirstArg(firstArg, subcommandKeys)) {
-    case "subcommand":
-      await runMain(await SUBCOMMANDS[firstArg!]!(), { rawArgs: restArgs });
+    case "subcommand": {
+      const command = await SUBCOMMANDS[firstArg!]!();
+      rejectUnknownOptions(restArgs, await resolveArgsDef(command));
+      await runMain(command, { rawArgs: restArgs });
       return;
+    }
 
     case "unknown": {
       // Extensionless existing files are valid transcription inputs; bare non-path tokens are likely command typos.
@@ -112,8 +137,15 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
     }
 
     default: {
+      const misplaced = misplacedSubcommand(rawArgs, subcommandKeys);
+      if (misplaced !== undefined) {
+        log.error(renderInvalidArg(`put global flags after the subcommand: kesha ${misplaced} ...`));
+        process.exit(2);
+      }
       const { createMainCommand } = await import("./main");
-      await runMain(createMainCommand(context), { rawArgs: context.rawArgs });
+      const command = createMainCommand(context);
+      rejectUnknownOptions(rawArgs, await resolveArgsDef(command));
+      await runMain(command, { rawArgs });
     }
   }
 }

package/src/cli/init.ts

@@ -32,16 +32,16 @@ export type TtsLangPrompt = (preselect: string[]) => Promise<string[]>;
 /** Signature of the interactive yes/no prompt (injectable for tests). */
 export type ConfirmPrompt = (message: string, initialValue: boolean) => Promise<boolean>;
 
-/** Ctrl-C at any prompt ends init without downloading, rather than falling through with a default. */
+/** Ctrl-C at any prompt ends init without downloading, exiting 130 like an interrupted install so `kesha init && …` stops (S4-F1). */
 function exitIfCancelled<T>(answer: T | symbol): T {
   if (isCancel(answer)) {
     cancel("Init cancelled.");
-    process.exit(0);
+    process.exit(130);
   }
   return answer as T;
 }
 
-async function promptTtsLangs(preselect: string[]): Promise<string[]> {
+export async function promptTtsLangs(preselect: string[]): Promise<string[]> {
   // A corrupt engine must leave init offering the fallback list rather than aborting the
   // guided setup that would replace it (#770).
   const caps = await getEngineCapabilities().catch(() => null);
@@ -57,7 +57,7 @@ async function promptTtsLangs(preselect: string[]): Promise<string[]> {
 }
 
 /** #677: keep every prompt on clack — its close() unpipes stdin, deadlocking any readline sharing it. */
-async function promptConfirm(message: string, initialValue: boolean): Promise<boolean> {
+export async function promptConfirm(message: string, initialValue: boolean): Promise<boolean> {
   return exitIfCancelled(await confirm({ message, initialValue }));
 }
 

package/src/cli/install.ts

@@ -6,6 +6,7 @@ import { getEngineBinPath, getEngineCapabilities, type EngineCapabilities } from
 import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
+import { renderInvalidArg } from "./options";
 import { log } from "../log";
 import { packageVersion } from "../package-info";
 import { isSemver } from "../semver.mjs";
@@ -321,8 +322,8 @@ export const installCommand = defineCommand({
     try {
       ttsLangs = resolveTtsLangs({ tts: args.tts === true, positionals }, supported);
     } catch (err) {
-      log.error(errorMessage(err));
-      process.exit(1);
+      log.error(renderInvalidArg(errorMessage(err)));
+      process.exit(2);
     }
     await performInstall({
       noCache: resolveNoCacheFlag(args, rawArgs),