@drakulavich/kesha-voice-kit 1.24.6 → 1.24.7

package/README.md

@@ -16,7 +16,7 @@
 - **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~2.5x on 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 ~20MB binary, no ffmpeg, no Python, no native Node addons
+- **Small Rust engine** — single ~60MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
   <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
@@ -24,16 +24,21 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64, Windows x64.
+Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64. Windows x64 is currently blocked at install ([#216](https://github.com/drakulavich/kesha-voice-kit/issues/216)).
 
 ```bash
 # 1. Install Bun (skip if you have it) — Linux & macOS:
 curl -fsSL https://bun.sh/install | bash        # or: brew install oven-sh/bun/bun
 # Windows: powershell -c "irm bun.sh/install.ps1 | iex"
+# if `bun --version` fails, reload PATH: exec $SHELL -l
 
 # 2. Install Kesha:
 bun add -g @drakulavich/kesha-voice-kit
-kesha install        # downloads engine + models (explicit — never automatic)
+kesha --version                                 # confirms `kesha` resolved on PATH
+kesha install --plan                            # preview exact download/disk sizes first — downloads nothing
+kesha install        # ~2.5 GB (engine + speech-to-text models), explicit — never automatic.
+                      # No progress bar during the model step; can take several minutes.
+                      # Prefer a guided wizard? `kesha init` walks through the same choices interactively.
 
 # 3. Transcribe:
 kesha audio.ogg      # transcript to stdout
@@ -51,6 +56,7 @@ kesha --format json audio.ogg              # full JSON with lang fields
 kesha --json --timestamps audio.ogg        # JSON with timestamped segments
 kesha --toon audio.ogg                     # compact LLM-friendly TOON
 kesha status                               # show installed backend info
+kesha status --disk                        # + recursive cache disk usage
 ```
 
 Multiple files get `head`-style headers; stdout is the transcript, stderr is errors — pipe-friendly:
@@ -64,6 +70,7 @@ $ kesha freedom.ogg tahiti.ogg
 Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
 ```
 
+- **Record from the mic (macOS):** `kesha record --out hello.wav` writes microphone audio to a WAV file (`kesha hello.wav` transcribes it). macOS prompts for microphone access on first use — grant it under System Settings → Privacy & Security → Microphone if it was denied. On Linux/Windows or headless boxes, pass any existing audio file straight to `kesha` instead.
 - **Long / silence-heavy audio:** install VAD (`kesha install --vad`); Kesha auto-uses it past 120 s. Without VAD, long audio falls back to fixed ASR chunks. See [docs/vad.md](docs/vad.md).
 - **Speaker diarization** (darwin-arm64): `kesha install --diarize`, then `kesha --json --vad --speakers meeting.m4a` stamps each segment with a `speaker` id. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
 
@@ -72,7 +79,8 @@ $ kesha freedom.ogg tahiti.ogg
 Kesha speaks back in [9 languages](docs/languages.md#text-to-speech), auto-picking the voice from the text's language. Override with `--lang <code>` or `--voice <id>`.
 
 ```bash
-kesha install --tts                              # opt-in models (~990MB)
+kesha install --tts                              # English voices; sizes differ per platform — preview: kesha install --plan
+kesha install --tts en ru                        # + Russian (+~890 MB, Vosk)
 kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav             # auto-routes by language
 kesha say --voice ru-vosk-m02 "Голос в текст." > ru.wav
@@ -117,7 +125,7 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - **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) — transcribe selected audio & speak the clipboard from the launcher. Source + install: [`raycast/`](raycast/).
+- **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

package/completions/kesha.fish

@@ -42,7 +42,7 @@ complete -c kesha -n '__fish_seen_subcommand_from init' -l onnx -d 'Preselect ON
 complete -c kesha -n '__fish_seen_subcommand_from init' -l no-cache -d 'Re-download even if cached'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l plan -d 'Show the selected install plan without downloading'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l yes -d 'Accept defaults and run without prompts'
-complete -c kesha -n '__fish_seen_subcommand_from init' -l tts -d 'Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from init' -l tts -d 'Preselect TTS models (English; more languages via kesha install --tts <langs>)'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l vad -d 'Preselect Silero VAD (~2.3MB) for long-audio preprocessing'
 complete -c kesha -n '__fish_seen_subcommand_from init' -l diarize -d 'Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
@@ -51,7 +51,7 @@ complete -c kesha -n '__fish_seen_subcommand_from install' -l coreml -d 'Force C
 complete -c kesha -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
-complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (English only; add codes for more, e.g. --tts en ru (preview sizes: kesha install --plan))'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
 complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
 complete -c kesha -n '__fish_seen_subcommand_from logs' -l help -d 'Show help'

package/completions/kesha.zsh

@@ -62,7 +62,7 @@ _kesha() {
         '--no-cache[Re-download even if cached]' \
         '--plan[Show the selected install plan without downloading]' \
         '--yes[Accept defaults and run without prompts]' \
-        '--tts[Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--tts[Preselect TTS models (English; more languages via kesha install --tts <langs>)]' \
         '--vad[Preselect Silero VAD (~2.3MB) for long-audio preprocessing]' \
         '--diarize[Preselect Sortformer speaker diarization (~245MB, darwin-arm64 only)]'
       ;;
@@ -73,7 +73,7 @@ _kesha() {
         '--onnx[Force ONNX backend]' \
         '--no-cache[Re-download even if cached]' \
         '--plan[Show download, disk, and warm-up plan without changing local state]' \
-        '--tts[Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--tts[Also install TTS models (English only; add codes for more, e.g. --tts en ru (preview sizes: kesha install --plan))]' \
         '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
         '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
       ;;

package/docs/product-positioning.md

@@ -60,19 +60,28 @@ The product promise is not "one model for every audio problem." The promise is a
 
 | Capability | macOS arm64 | macOS x64 | Linux x64 | Windows x64 | Nix path |
 |---|---|---|---|---|---|
-| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Supported, ONNX CPU path | `aarch64-darwin`, `x86_64-linux` |
-| Audio language detection | Supported | Not shipped | Supported | Supported | Supported where the flake builds |
-| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Supported with `kesha install --vad` | Supported where the engine path includes VAD assets |
-| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
-| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/nix-install.md` |
+| STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Blocked at install (#216) | `aarch64-darwin`, `x86_64-linux` |
+| Audio language detection | Supported | Not shipped | Supported | Blocked at install (#216) | Supported where the flake builds |
+| VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Blocked at install (#216) | Supported where the engine path includes VAD assets |
+| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
+| TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Blocked at install (#216) | Supported except where noted in `docs/nix-install.md` |
 | macOS system voices | Supported | Not shipped | Not applicable | Not applicable | Supported on `aarch64-darwin` |
 | Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
 | Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |
-| OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Supported through CLI route | Use the installed `kesha` command from the chosen path |
-| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Supported through command providers | Use the installed `kesha` command from the chosen path |
+| OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
+| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Blocked at install (#216) | Use the installed `kesha` command from the chosen path |
 
 `macOS x64` means Intel Macs. Kesha does not currently publish a `darwin-x64` engine binary, so Intel Macs are intentionally marked as not shipped rather than implied to use the ONNX fallback.
 
+`Windows x64` shows "Blocked at install" because the CLI's install step
+refuses to run on Windows, not because no binary exists — `build-engine.yml`
+builds and publishes `kesha-engine-windows-x64.exe` with every release. The
+Vosk-TTS native dependency trips MSVC at link time, so the CLI blocks the
+install client-side rather than shipping a broken engine. See
+[issue #216](https://github.com/drakulavich/kesha-voice-kit/issues/216) for
+the underlying failure and the v1.4.x workaround; the toolkit is unusable on
+Windows until that lands.
+
 ## When to choose something else
 
 Use a hosted transcription provider when you need managed uptime, centralized audit logs, team permissions, or no local model cache. Use a streaming ASR stack when partial transcripts during a live call matter more than local-first batch reliability. Use a domain-specific ASR model when medical, legal, or noisy industrial audio quality is the primary requirement.

package/man/kesha.1

@@ -112,7 +112,7 @@ Show the selected install plan without downloading
 Accept defaults and run without prompts
 .TP
 .B \-\-tts
-Preselect TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+Preselect TTS models (English; more languages via kesha install \-\-tts <langs>)
 .TP
 .B \-\-vad
 Preselect Silero VAD (~2.3MB) for long\-audio preprocessing
@@ -134,7 +134,7 @@ Re\-download even if cached
 Show download, disk, and warm\-up plan without changing local state
 .TP
 .B \-\-tts
-Also install TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+Also install TTS models (English only; add codes for more, e.g. \-\-tts en ru (preview sizes: kesha install \-\-plan))
 .TP
 .B \-\-vad
 Also install Silero VAD (~2.3MB) for long\-audio preprocessing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.24.6",
+  "version": "1.24.7",
   "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": {
@@ -38,14 +38,14 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.6"
+    "version": "1.24.7"
   },
   "scripts": {
-    "test": "bun test",
-    "test:watch": "bun test --watch",
+    "test": "bun test --timeout 30000",
+    "test:watch": "bun test --timeout 30000 --watch",
     "test:unit": "bun test tests/unit/",
-    "test:cli-fast": "bun test tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
-    "test:integration": "bun test tests/integration/",
+    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
+    "test:integration": "bun test --timeout 30000 tests/integration/",
     "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
     "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",
     "coverage:rust": "mkdir -p coverage/rust && cd rust && cargo llvm-cov nextest --features tts --lcov --output-path ../coverage/rust/lcov.info",
@@ -54,6 +54,7 @@
     "lint": "bunx tsc --noEmit",
     "check": "bun run lint && bun run check:versions && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
+    "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts"
   },

package/src/cli/action-result.ts

@@ -0,0 +1,18 @@
+import { log } from "../log";
+
+export type ActionMessage = { level: "success" | "info" | "warn"; text: string };
+
+export type ActionResult =
+  | { ok: true; messages: ActionMessage[]; stdout?: string }
+  | { ok: false; error: string; hint?: string };
+
+/** 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);
+    if (result.hint) log.warn(result.hint);
+    process.exit(2);
+  }
+  for (const message of result.messages) log[message.level](message.text);
+  if (result.stdout !== undefined) process.stdout.write(result.stdout);
+}

package/src/cli/command-session.ts

@@ -0,0 +1,86 @@
+import { createDiagnosticLogSession } from "../diagnostic-log";
+import type {
+  DiagnosticLogFields,
+  DiagnosticLogSession,
+  DiagnosticSessionStatus,
+} from "../diagnostic-log";
+import { errorMessage } from "../error-utils";
+import { log } from "../log";
+import { createStatsRecorder } from "../stats";
+import type { StatsCommandName, StatsRecorder } from "../stats";
+
+export interface CommandSession {
+  readonly stats: StatsRecorder;
+  readonly diagnosticLog: DiagnosticLogSession;
+}
+
+export interface CommandOutcome {
+  status: DiagnosticSessionStatus;
+  itemCount: number;
+  /** Merged into the `command.finish` event alongside `command` and `status`. */
+  finishFields?: DiagnosticLogFields;
+  /** Exit code the caller should terminate with; omitted means "don't exit". */
+  exitCode?: number;
+}
+
+export interface CommandSessionFactories {
+  createStats: (command: StatsCommandName) => StatsRecorder;
+  createDiagnosticLog: () => DiagnosticLogSession;
+}
+
+const defaultFactories: CommandSessionFactories = {
+  createStats: createStatsRecorder,
+  createDiagnosticLog: createDiagnosticLogSession,
+};
+
+/** Runs one CLI command's body between `command.start` / `command.finish`, closing both recorders exactly once; `body` reports failure by returning a {@link CommandOutcome}, never by exiting. */
+export async function runCommandSession(
+  command: StatsCommandName,
+  startFields: DiagnosticLogFields,
+  body: (session: CommandSession) => Promise<CommandOutcome>,
+  factories: CommandSessionFactories = defaultFactories,
+): Promise<CommandOutcome> {
+  const session: CommandSession = {
+    stats: factories.createStats(command),
+    diagnosticLog: factories.createDiagnosticLog(),
+  };
+  session.diagnosticLog.event("command.start", { command, ...startFields });
+
+  let outcome: CommandOutcome;
+  try {
+    outcome = await body(session);
+  } catch (err) {
+    closeSessionQuietly(session, command, { status: "failed", itemCount: 0 });
+    throw err;
+  }
+
+  // A flush error must not displace a failure the command already has to report (Greptile P1/P2 on #607).
+  if (outcome.status === "failed") {
+    closeSessionQuietly(session, command, outcome);
+  } else {
+    closeSession(session, command, outcome);
+  }
+  return outcome;
+}
+
+function closeSessionQuietly(
+  session: CommandSession,
+  command: StatsCommandName,
+  outcome: CommandOutcome,
+): void {
+  try {
+    closeSession(session, command, outcome);
+  } catch (err) {
+    log.debug(`command session cleanup failed: ${errorMessage(err)}`);
+  }
+}
+
+function closeSession(session: CommandSession, command: StatsCommandName, outcome: CommandOutcome): void {
+  session.diagnosticLog.event("command.finish", {
+    command,
+    status: outcome.status,
+    ...outcome.finishFields,
+  });
+  session.stats.finish(outcome.status, outcome.itemCount);
+  session.diagnosticLog.finish(outcome.status);
+}

package/src/cli/context.ts

@@ -0,0 +1,108 @@
+import { log, setColorEnabled } from "../log";
+
+/** The global flags resolved before citty, so every command sees the same decision. */
+export interface CliContext {
+  quiet: boolean;
+  disableColor: boolean;
+}
+
+export interface ResolvedCliContext extends CliContext {
+  /** `rawArgs` with the global flag tokens removed, ready to hand to citty. */
+  rawArgs: string[];
+}
+
+// Falsey grammar shared by --no-color, --quiet, and CI. Mirrors KESHA_DEBUG so
+// `CI=false`/`CI=0` and `--no-color=false` opt back in.
+const FALSEY_VALUES = new Set(["", "0", "false", "no", "off"]);
+function isFalsey(v: string): boolean {
+  return FALSEY_VALUES.has(v.trim().toLowerCase());
+}
+
+/** True when NO_COLOR came from the user's environment, so re-enabling colors must not clear it. */
+export const USER_FORCED_NO_COLOR =
+  process.env.NO_COLOR !== undefined && !isFalsey(process.env.NO_COLOR);
+
+/**
+ * Strip a boolean global flag out of rawArgs so citty never sees it. Matches
+ * any of `names` bare (sets the flag) and the `--name=<value>` form for the
+ * long names (`<falsey>` explicitly turns the flag back off).
+ */
+function stripBooleanFlag(
+  rawArgs: string[],
+  names: string[],
+): { value: boolean; rawArgs: string[] } {
+  const valuedPrefixes = names.filter((n) => n.startsWith("--")).map((n) => `${n}=`);
+  let value = false;
+  const cleaned: string[] = [];
+  for (const arg of rawArgs) {
+    if (names.includes(arg)) {
+      value = true;
+    } else if (valuedPrefixes.some((prefix) => arg.startsWith(prefix))) {
+      value = !isFalsey(arg.slice(arg.indexOf("=") + 1));
+    } else {
+      cleaned.push(arg);
+    }
+  }
+  return { value, rawArgs: cleaned };
+}
+
+/**
+ * Decide whether ANSI colors should be disabled (#531) and return rawArgs with
+ * any `--no-color[=value]` token stripped so citty never sees it.
+ *
+ * Colors are disabled when `--no-color` (bare) or `--no-color=<truthy>` is
+ * passed, or when the environment looks like CI (`CI` set to a non-falsey value
+ * — GitHub Actions, GitLab, CircleCI, … export `CI=true`). `--no-color=false`
+ * and `CI=false`/`CI=0` explicitly opt back in.
+ */
+export function resolveColorMode(
+  rawArgs: string[],
+  env: { CI?: string } = process.env as { CI?: string },
+): { disableColor: boolean; rawArgs: string[] } {
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--no-color"]);
+  const ci = env.CI !== undefined && !isFalsey(env.CI);
+  return { disableColor: value || ci, rawArgs: cleaned };
+}
+
+/**
+ * Detect `--quiet`/`-q` (and `--quiet=<value>`) and return rawArgs with the
+ * token stripped (#526). Resolved before citty — like `--no-color` — so quiet
+ * is global: it works for every command, not just the transcribe path, and a
+ * subcommand that doesn't declare it never sees the flag.
+ */
+export function resolveQuietMode(rawArgs: string[]): { quiet: boolean; rawArgs: string[] } {
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--quiet", "-q"]);
+  return { quiet: value, rawArgs: cleaned };
+}
+
+/** Resolves every pre-citty global flag into one value, with the tokens stripped from rawArgs. */
+export function resolveCliContext(
+  rawArgs: string[],
+  env: { CI?: string } = process.env as { CI?: string },
+): ResolvedCliContext {
+  const color = resolveColorMode(rawArgs, env);
+  const quiet = resolveQuietMode(color.rawArgs);
+  return { quiet: quiet.quiet, disableColor: color.disableColor, rawArgs: quiet.rawArgs };
+}
+
+/**
+ * Sync NO_COLOR with the resolved color decision so engine subprocesses inherit
+ * the right value. Separated from setColorEnabled so it can be tested without
+ * picocolors side-effects.
+ *
+ * Never clears a NO_COLOR the user exported before this process started.
+ */
+export function applyColorEnv(disableColor: boolean): void {
+  if (disableColor) {
+    process.env.NO_COLOR = "1";
+  } else if (!USER_FORCED_NO_COLOR) {
+    delete process.env.NO_COLOR;
+  }
+}
+
+/** Applies the context to the process-wide output sinks, writing every value so an earlier in-process run (unit tests, `kesha mcp`) can't leak its settings into a later one. */
+export function applyCliContext(context: CliContext): void {
+  setColorEnabled(!context.disableColor);
+  applyColorEnv(context.disableColor);
+  log.quietEnabled = context.quiet;
+}

package/src/cli/dispatch.ts

@@ -1,7 +1,8 @@
 import { runMain, type CommandDef } from "citty";
 import { existsSync } from "fs";
-import { log, setColorEnabled } from "../log";
+import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
+import { applyCliContext, resolveCliContext } from "./context";
 
 // 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.
@@ -25,86 +26,6 @@ function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
 }
 
-// Falsey grammar shared by --no-color and CI. Mirrors KESHA_DEBUG so
-// `CI=false`/`CI=0` and `--no-color=false` opt back in to colors.
-const FALSEY_VALUES = new Set(["", "0", "false", "no", "off"]);
-function isFalsey(v: string): boolean {
-  return FALSEY_VALUES.has(v.trim().toLowerCase());
-}
-
-// Captured at import so re-enabling colors never clobbers a user-exported NO_COLOR.
-const USER_FORCED_NO_COLOR =
-  process.env.NO_COLOR !== undefined && !isFalsey(process.env.NO_COLOR);
-
-/**
- * Strip a boolean global flag out of rawArgs so citty never sees it. Matches
- * any of `names` bare (sets the flag) and the `--name=<value>` form for the
- * long names (`<falsey>` explicitly turns the flag back off).
- */
-function stripBooleanFlag(
-  rawArgs: string[],
-  names: string[],
-): { value: boolean; rawArgs: string[] } {
-  const valuedPrefixes = names.filter((n) => n.startsWith("--")).map((n) => `${n}=`);
-  let value = false;
-  const cleaned: string[] = [];
-  for (const arg of rawArgs) {
-    if (names.includes(arg)) {
-      value = true;
-    } else if (valuedPrefixes.some((prefix) => arg.startsWith(prefix))) {
-      value = !isFalsey(arg.slice(arg.indexOf("=") + 1));
-    } else {
-      cleaned.push(arg);
-    }
-  }
-  return { value, rawArgs: cleaned };
-}
-
-/**
- * Decide whether ANSI colors should be disabled (#531) and return rawArgs with
- * any `--no-color[=value]` token stripped so citty never sees it.
- *
- * Colors are disabled when `--no-color` (bare) or `--no-color=<truthy>` is
- * passed, or when the environment looks like CI (`CI` set to a non-falsey value
- * — GitHub Actions, GitLab, CircleCI, … export `CI=true`). `--no-color=false`
- * and `CI=false`/`CI=0` explicitly opt back in.
- */
-export function resolveColorMode(
-  rawArgs: string[],
-  env: { CI?: string } = process.env as { CI?: string },
-): { disableColor: boolean; rawArgs: string[] } {
-  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--no-color"]);
-  const ci = env.CI !== undefined && !isFalsey(env.CI);
-  return { disableColor: value || ci, rawArgs: cleaned };
-}
-
-/**
- * Detect `--quiet`/`-q` (and `--quiet=<value>`) and return rawArgs with the
- * token stripped (#526). Resolved before citty — like `--no-color` — so quiet
- * is global: it works for every command, not just the transcribe path, and a
- * subcommand that doesn't declare it never sees the flag.
- */
-export function resolveQuietMode(rawArgs: string[]): { quiet: boolean; rawArgs: string[] } {
-  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--quiet", "-q"]);
-  return { quiet: value, rawArgs: cleaned };
-}
-
-/**
- * Sync NO_COLOR with the resolved color decision so engine subprocesses inherit
- * the right value. Separated from setColorEnabled so it can be tested without
- * picocolors side-effects.
- *
- * Never clears a NO_COLOR the user exported before this process started
- * (USER_FORCED_NO_COLOR guard).
- */
-export function applyColorEnv(disableColor: boolean): void {
-  if (disableColor) {
-    process.env.NO_COLOR = "1";
-  } else if (!USER_FORCED_NO_COLOR) {
-    delete process.env.NO_COLOR;
-  }
-}
-
 /**
  * Classify the first positional arg for routing.
  *
@@ -123,18 +44,35 @@ export function classifyFirstArg(
   return "unknown";
 }
 
-export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
-  // Global flags resolved before citty so they apply to every command and never reach a subcommand's arg schema.
-  const color = resolveColorMode(rawArgs);
-  // Reset on every invocation so an earlier --no-color/CI call doesn't leave colors off for later in-process calls (unit tests, `kesha mcp`).
-  setColorEnabled(!color.disableColor);
-  applyColorEnv(color.disableColor);
+export interface UnknownCommandMessages {
+  errorLine: string;
+  warnLines: string[];
+}
+
+/**
+ * Pure message builder for the unknown-token path (testable without
+ * `process.exit`). `transcribe` isn't a real subcommand — bare `kesha
+ * <audio-file>` is the invocation — so a near-miss of that word gets its own
+ * extra hint alongside the generic "pass a path" one.
+ */
+export function unknownCommandMessages(token: string, subcommandKeys: string[]): UnknownCommandMessages {
+  const suggestion = suggestCommand(token, subcommandKeys);
+  const warnLines: string[] = [];
+  if (suggestion && suggestion !== token) {
+    warnLines.push(`(Did you mean ${suggestion}?)`);
+  }
+  warnLines.push(`If this is an audio file, pass a path like './${token}'.`);
+  if (suggestCommand(token, ["transcribe"]) === "transcribe") {
+    warnLines.push("To transcribe, pass the audio path directly: kesha ./recording.ogg");
+  }
+  return { errorLine: `unknown command '${token}'`, warnLines };
+}
 
-  const quiet = resolveQuietMode(color.rawArgs);
-  log.quietEnabled = quiet.quiet;
+export async function runCli(argv = process.argv.slice(2)): Promise<void> {
+  const context = resolveCliContext(argv);
+  applyCliContext(context);
 
-  rawArgs = quiet.rawArgs;
-  const [firstArg, ...restArgs] = rawArgs;
+  const [firstArg, ...restArgs] = context.rawArgs;
   const subcommandKeys = Object.keys(SUBCOMMANDS);
 
   switch (classifyFirstArg(firstArg, subcommandKeys)) {
@@ -144,17 +82,16 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
 
     case "unknown": {
       // Extensionless existing files are valid transcription inputs; bare non-path tokens are likely command typos.
-      const suggestion = suggestCommand(firstArg!, subcommandKeys);
-      log.error(`unknown command '${firstArg}'`);
-      if (suggestion && suggestion !== firstArg) {
-        log.warn(`(Did you mean ${suggestion}?)`);
-      }
-      log.warn(`If this is an audio file, pass a path like './${firstArg}'.`);
+      const { errorLine, warnLines } = unknownCommandMessages(firstArg!, subcommandKeys);
+      log.error(errorLine);
+      for (const line of warnLines) log.warn(line);
       process.exit(1);
       break;
     }
 
-    default:
-      await runMain((await import("./main")).mainCommand, { rawArgs });
+    default: {
+      const { createMainCommand } = await import("./main");
+      await runMain(createMainCommand(context), { rawArgs: context.rawArgs });
+    }
   }
 }

package/src/cli/init.ts

@@ -127,7 +127,7 @@ export function renderInitOverview(canDiarize = canInstallDiarizeOnPlatform()):
     "Kesha is a local voice toolkit. The base install downloads the engine, speech-to-text models, and language detection models.",
     "",
     "Optional features:",
-    "  - Text-to-speech: enables `kesha say` with Kokoro English and Vosk-TTS Russian voices (~990MB).",
+    "  - Text-to-speech: enables `kesha say` with Kokoro English voices (more languages via `kesha install --tts <langs>`).",
     "  - VAD: skips silence in long audio and improves meeting, lecture, and podcast transcripts (~2.3MB).",
     canDiarize
       ? "  - Speaker diarization: labels speakers in JSON/TOON transcript segments (~245MB, darwin-arm64)."
@@ -234,7 +234,7 @@ export const initCommand = defineCommand({
     },
     tts: {
       type: "boolean",
-      description: "Preselect TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)",
+      description: "Preselect TTS models (English; more languages via kesha install --tts <langs>)",
       default: false,
     },
     vad: {

package/src/cli/install.ts

@@ -68,14 +68,26 @@ export function resolveNoCacheFlag(
   );
 }
 
-export function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
+export type BackendSelection =
+  | { ok: true; backend: string | undefined }
+  | { ok: false; error: string };
+
+export function selectBackend(coreml: boolean, onnx: boolean): BackendSelection {
   if (coreml && onnx) {
-    log.error('Choose only one backend: "--coreml" or "--onnx".');
+    return { ok: false, error: 'Choose only one backend: "--coreml" or "--onnx".' };
+  }
+  if (coreml) return { ok: true, backend: "coreml" };
+  if (onnx) return { ok: true, backend: "onnx" };
+  return { ok: true, backend: undefined };
+}
+
+export function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
+  const selection = selectBackend(coreml, onnx);
+  if (!selection.ok) {
+    log.error(selection.error);
     process.exit(1);
   }
-  if (coreml) return "coreml";
-  if (onnx) return "onnx";
-  return undefined;
+  return selection.backend;
 }
 
 function defaultBackendForPlatform(): string | undefined {
@@ -187,7 +199,7 @@ export const installCommand = defineCommand({
     },
     tts: {
       type: "boolean",
-      description: "Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)",
+      description: "Also install TTS models (English only; add codes for more, e.g. --tts en ru (preview sizes: kesha install --plan))",
       default: false,
     },
     vad: {