@drakulavich/kesha-voice-kit 1.23.0 → 1.24.1

package/README.md

@@ -125,7 +125,8 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - [Architecture](docs/architecture.md) — runtime data flow, the models that ship, the CLI ↔ Rust engine boundary, model pinning, and where tests live.
 - [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.
-- **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 ([docs/errors.md](docs/errors.md)).
+- **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).
+- **Scripting & CI:** `--json` (or `--toon`) for machine-readable output, `--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).
 
 ## Contributing

package/completions/kesha.bash

@@ -10,7 +10,7 @@ _kesha_completion() {
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
-      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" -- "$cur") )
+      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" -- "$cur") )
     else
       COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
     fi
@@ -30,7 +30,7 @@ _kesha_completion() {
     stats) opts="--help -h --format" ;;
     status) opts="--help -h --disk" ;;
     support-bundle) opts="--help -h --output --include-logs" ;;
-    *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" ;;
+    *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" ;;
   esac
 
   if [[ "$cur" == -* ]]; then

package/completions/kesha.fish

@@ -19,14 +19,16 @@ complete -c kesha -n '__fish_use_subcommand' -s v -d 'Show version'
 complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
 complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
 complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
-complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
+complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.'
 complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
 complete -c kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
 complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
-complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
+complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch'
 complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
 complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Force full-file ASR for short/medium files; long audio fails early'
+complete -c kesha -n '__fish_use_subcommand' -l quiet -d 'Suppress progress output; print only results and errors'
+complete -c kesha -n '__fish_use_subcommand' -l no-color -d 'Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
@@ -67,7 +69,7 @@ complete -c kesha -n '__fish_seen_subcommand_from record' -l debug -d 'Trace eng
 complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us). With no --voice, routes to that language\'s default voice and skips text-language detection.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language\'s default voice and skips text-language detection.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'

package/completions/kesha.zsh

@@ -27,14 +27,16 @@ _kesha() {
       '--json[Output results as JSON]' \
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
-      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.]' \
       '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
-      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--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]'
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]' \
+      '--quiet[Suppress progress output; print only results and errors]' \
+      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
     else
       _describe -t commands 'kesha command' commands
     fi
@@ -99,7 +101,7 @@ _kesha() {
       _arguments '--help[Show help]' \
         '-h[Show help]' \
         '--voice=[Voice id, e.g. en-am_michael]:voice:' \
-        '--lang=[BCP 47 language code (default en-us). With no --voice, routes to that language'\''s default voice and skips text-language detection.]:lang:' \
+        '--lang=[Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language'\''s default voice and skips text-language detection.]:lang:' \
         '--out=[Write audio to file instead of stdout]:out:' \
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
         '--list-voices[List installed voices and exit]' \
@@ -135,14 +137,16 @@ _kesha() {
       '--json[Output results as JSON]' \
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
-      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.]' \
       '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
-      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \
       '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
       '--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]'
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]' \
+      '--quiet[Suppress progress output; print only results and errors]' \
+      '--no-color[Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)]'
       ;;
   esac
 }

package/man/kesha.1

@@ -58,7 +58,7 @@ Output results as TOON (compact, LLM\-friendly encoding of the same data as \-\-
 Include timestamped transcript segments in JSON/TOON output
 .TP
 .B \-\-speakers
-Include speaker labels in transcript segments. Requires \-\-json / \-\-toon / \-\-format json. Implies \-\-timestamps. Currently darwin\-arm64 only (#199).
+Include speaker labels in segments. Needs \-\-json/\-\-toon and darwin\-arm64; run `kesha install \-\-diarize` first. Implies \-\-timestamps.
 .TP
 .B \-\-include\-errors
 With \-\-json, output { results, errors } so scripts can read per\-file failures without parsing stderr
@@ -70,7 +70,7 @@ Show language detection details
 Output format: transcript | json | toon (long\-form alias for \-\-json / \-\-toon)
 .TP
 .B \-\-lang
-Expected language code (ISO 639\-1), warn if mismatch
+Expected language code, e.g. en or en\-us (see docs/languages.md); warn if mismatch
 .TP
 .B \-\-debug
 Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
@@ -80,6 +80,12 @@ Force Silero VAD preprocessing (kesha install \-\-vad first). Without this, VAD
 .TP
 .B \-\-no\-vad
 Force full\-file ASR for short/medium files; long audio fails early
+.TP
+.B \-\-quiet
+Suppress progress output; print only results and errors
+.TP
+.B \-\-no\-color
+Disable ANSI colors (also via NO_COLOR=1; auto\-off when CI=true)
 .SH SUBCOMMAND OPTIONS
 .SS doctor
 .TP
@@ -155,7 +161,7 @@ Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
 Voice id, e.g. en\-am_michael
 .TP
 .B \-\-lang
-BCP 47 language code (default en\-us). With no \-\-voice, routes to that language's default voice and skips text\-language detection.
+Language code, e.g. en\-us (default en\-us; see docs/languages.md). With no \-\-voice, routes to that language's default voice and skips text\-language detection.
 .TP
 .B \-\-out
 Write audio to file instead of stdout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "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": {
@@ -42,6 +42,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:watch": "bun test --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/",
@@ -90,6 +91,7 @@
     "yaml": "^2.9.0"
   },
   "dependencies": {
+    "@clack/prompts": "^1.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@toon-format/toon": "^2.1.0",
     "citty": "^0.2.2",

package/src/cli/dispatch.ts

@@ -1,6 +1,6 @@
 import { runMain, type CommandDef } from "citty";
 import { existsSync } from "fs";
-import { log } from "../log";
+import { log, setColorEnabled } from "../log";
 import { suggestCommand } from "../suggest-command";
 import { completionsCommand } from "./completions";
 import { doctorCommand } from "./doctor";
@@ -39,7 +39,94 @@ 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());
+}
+
+// Whether the process was launched with NO_COLOR already forced on. Captured
+// once at import (before any runCli) so re-enabling colors never clobbers an
+// externally-set NO_COLOR — we only clear the var on re-enable when WE set it.
+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 };
+}
+
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
+  // Global flags resolved before citty so they apply to every command (and help
+  // output) and never reach a subcommand's arg schema.
+  const color = resolveColorMode(rawArgs);
+  // Reset on EVERY invocation (not just the disable path): an earlier
+  // --no-color / CI call must not leave colors permanently off for later
+  // in-process calls (unit tests, `kesha mcp`). picocolors already honors
+  // NO_COLOR at startup; setting the env var also propagates to the engine.
+  setColorEnabled(!color.disableColor);
+  // Keep NO_COLOR symmetric so it doesn't leak to engine subprocesses spawned
+  // by a later in-process call: set it when WE disable, clear it on re-enable —
+  // but never clear a NO_COLOR the user exported themselves.
+  if (color.disableColor) {
+    process.env.NO_COLOR = "1";
+  } else if (!USER_FORCED_NO_COLOR) {
+    delete process.env.NO_COLOR;
+  }
+
+  const quiet = resolveQuietMode(color.rawArgs);
+  log.quietEnabled = quiet.quiet;
+
+  rawArgs = quiet.rawArgs;
   const [firstArg, ...restArgs] = rawArgs;
 
   if (firstArg && Object.hasOwn(SUBCOMMANDS, firstArg)) {

package/src/cli/init.ts

@@ -1,9 +1,48 @@
 import { defineCommand } from "citty";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { multiselect, isCancel, cancel } from "@clack/prompts";
 import { renderInstallPlan } from "../install-plan";
 import { log } from "../log";
-import { performInstall, resolveBackendFlag, resolveNoCacheFlag } from "./install";
+import { getEngineCapabilities } from "../engine";
+import {
+  performInstall,
+  resolveBackendFlag,
+  resolveNoCacheFlag,
+  TTS_LANG_FALLBACK,
+} from "./install";
+
+const TTS_LANG_LABELS: Record<string, string> = {
+  en: "English (Kokoro)",
+  es: "Spanish (Kokoro)",
+  fr: "French (Kokoro)",
+  hi: "Hindi (Kokoro ANE)",
+  it: "Italian (Kokoro)",
+  ja: "Japanese (Kokoro ANE)",
+  pt: "Portuguese (Kokoro)",
+  zh: "Chinese (Kokoro ANE)",
+  ru: "Russian (Vosk-TTS)",
+};
+
+/** Signature of the interactive TTS-language picker (injectable for tests). */
+export type TtsLangPrompt = (preselect: string[]) => Promise<string[]>;
+
+async function promptTtsLangs(preselect: string[]): Promise<string[]> {
+  const caps = await getEngineCapabilities();
+  const supported = caps?.tts?.languages.map((l) => l.code) ?? TTS_LANG_FALLBACK;
+  const selected = await multiselect({
+    message:
+      "Select TTS languages to install (space to toggle, enter to confirm; none = skip TTS):",
+    options: supported.map((code) => ({ value: code, label: TTS_LANG_LABELS[code] ?? code })),
+    initialValues: preselect.filter((l) => supported.includes(l)),
+    required: false,
+  });
+  if (isCancel(selected)) {
+    cancel("Init cancelled.");
+    process.exit(0);
+  }
+  return selected as string[];
+}
 
 export interface InitCommandArgs {
   coreml: boolean;
@@ -21,7 +60,7 @@ export interface InitCommandArgs {
 export interface InitSelection {
   noCache: boolean;
   backend?: string;
-  tts: boolean;
+  ttsLangs: string[];
   vad: boolean;
   diarize: boolean;
 }
@@ -45,7 +84,7 @@ export function resolveInitSelection(
   return {
     noCache,
     backend,
-    tts: args.tts,
+    ttsLangs: args.tts ? ["en"] : [],
     vad: args.vad,
     diarize: args.diarize,
   };
@@ -58,7 +97,7 @@ export function initInstallArgs(selection: InitSelection): string[] {
     selection.noCache ? "--no-cache" : "",
     selection.backend === "coreml" ? "--coreml" : "",
     selection.backend === "onnx" ? "--onnx" : "",
-    selection.tts ? "--tts" : "",
+    ...(selection.ttsLangs.length > 0 ? ["--tts", ...selection.ttsLangs] : []),
     selection.vad ? "--vad" : "",
     selection.diarize ? "--diarize" : "",
   ].filter(Boolean);
@@ -70,12 +109,12 @@ export function initSuggestionCommands(
 ): string[][] {
   const variants: InitSelection[] = [
     selection,
-    { ...selection, tts: false, vad: true, diarize: false },
-    { ...selection, tts: true, vad: true, diarize: false },
+    { ...selection, ttsLangs: [], vad: true, diarize: false },
+    { ...selection, ttsLangs: ["en"], vad: true, diarize: false },
   ];
 
   if (canDiarize) {
-    variants.push({ ...selection, tts: false, vad: true, diarize: true });
+    variants.push({ ...selection, ttsLangs: [], vad: true, diarize: true });
   }
 
   const seen = new Set<string>();
@@ -118,8 +157,9 @@ export async function promptInitSelection(
   backend = resolveBackendFlag(args.coreml, args.onnx),
   canDiarize = canInstallDiarizeOnPlatform(),
   noCache = resolveNoCacheFlag(args),
+  promptTts: TtsLangPrompt = promptTtsLangs,
 ): Promise<InitSelection> {
-  const tts = await askYesNo(prompt, "Install text-to-speech models for `kesha say`?", args.tts);
+  const ttsLangs = await promptTts(args.tts ? ["en"] : []);
   const vad = await askYesNo(prompt, "Install VAD for long or silence-heavy audio?", args.vad);
   let diarize = false;
   if (canDiarize) {
@@ -131,7 +171,7 @@ export async function promptInitSelection(
   return {
     noCache,
     backend,
-    tts,
+    ttsLangs,
     vad,
     diarize,
   };
@@ -153,7 +193,7 @@ async function printPlan(selection: InitSelection): Promise<void> {
     await renderInstallPlan({
       noCache: selection.noCache,
       backend: selection.backend,
-      tts: selection.tts,
+      ttsLangs: selection.ttsLangs,
       vad: selection.vad,
       diarize: selection.diarize,
     }),
@@ -240,7 +280,7 @@ export const initCommand = defineCommand({
       await performInstall(
         installSelection.noCache,
         installSelection.backend,
-        installSelection.tts,
+        installSelection.ttsLangs,
         installSelection.vad,
         installSelection.diarize,
       );
@@ -265,7 +305,21 @@ export const initCommand = defineCommand({
         log.info(`Skipped install. Run later: ${initInstallArgs(prompted).join(" ")}`);
         return;
       }
-      await performInstall(prompted.noCache, prompted.backend, prompted.tts, prompted.vad, prompted.diarize);
+      await performInstall(
+        prompted.noCache,
+        prompted.backend,
+        prompted.ttsLangs,
+        prompted.vad,
+        prompted.diarize,
+      );
+      // Next-steps hint (#523): leave the user with something runnable rather
+      // than ending on the install log.
+      log.info("");
+      log.success("Kesha is ready. Try:");
+      log.info("  kesha path/to/audio.ogg     Transcribe a file.");
+      if (prompted.ttsLangs.length > 0) {
+        log.info('  kesha say "hello"           Speak text (TTS).');
+      }
     } finally {
       rl.close();
     }

package/src/cli/install.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from "citty";
+import { errorMessage } from "../error-utils";
 import { downloadEngine } from "../engine-install";
-import { getEngineBinPath } from "../engine";
+import { getEngineBinPath, getEngineCapabilities } from "../engine";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
@@ -8,6 +9,8 @@ import { packageVersion } from "../package-info";
 import { createDiagnosticLogSession, type DiagnosticLogSession } from "../diagnostic-log";
 
 export interface InstallCommandArgs {
+  /** Positional args after `install` — candidate TTS language codes. */
+  _?: string[];
   coreml: boolean;
   onnx: boolean;
   "no-cache": boolean;
@@ -19,6 +22,50 @@ export interface InstallCommandArgs {
   plan: boolean;
 }
 
+/**
+ * TTS languages installable on EVERY build, used when the engine binary isn't
+ * installed yet (capabilities unavailable). hi/ja/zh are darwin-arm64-only and
+ * can't be assumed without capabilities, so they're excluded here.
+ */
+export const TTS_LANG_FALLBACK = ["en", "es", "fr", "it", "pt", "ru"];
+
+export interface TtsArgInput {
+  /** Whether --tts was passed. */
+  tts: boolean;
+  /** Positional args after the install command (candidate language codes). */
+  positionals: string[];
+}
+
+/**
+ * Resolve the requested TTS language list. Bare `--tts` defaults to English.
+ * Positionals without `--tts` are an error. When `supported` is provided,
+ * unsupported codes are a hard error (nothing downloads); when it's undefined
+ * (engine not yet installed, capabilities unavailable) the check is skipped and
+ * the engine validates authoritatively at download time.
+ */
+export function resolveTtsLangs(input: TtsArgInput, supported: string[] | undefined): string[] {
+  if (!input.tts) {
+    if (input.positionals.length > 0) {
+      throw new Error(
+        `Language codes (${input.positionals.join(", ")}) require the --tts flag, ` +
+          `e.g. \`kesha install --tts ${input.positionals.join(" ")}\`.`,
+      );
+    }
+    return [];
+  }
+  const langs = input.positionals.length > 0 ? input.positionals : ["en"];
+  if (supported) {
+    const bad = langs.filter((l) => !supported.includes(l));
+    if (bad.length > 0) {
+      throw new Error(
+        `Unsupported TTS language(s): ${bad.join(", ")}. ` +
+          `Supported on this platform: ${supported.join(", ")}.`,
+      );
+    }
+  }
+  return langs;
+}
+
 export function resolveNoCacheFlag(
   args: Pick<InstallCommandArgs, "no-cache" | "noCache" | "no_cache">,
   rawArgs: string[] = [],
@@ -65,20 +112,20 @@ function finishInstallDiagnostic(
     });
     diagnosticLog.finish(status);
   } catch (err) {
-    log.debug(`install diagnostic log finish dropped: ${err instanceof Error ? err.message : String(err)}`);
+    log.debug(`install diagnostic log finish dropped: ${errorMessage(err)}`);
   }
 }
 
 export async function performInstall(
   noCache: boolean,
-  backend?: string,
-  tts = false,
+  backend: string | undefined,
+  ttsLangs: string[],
   vad = false,
   diarize = false,
   plan = false,
 ) {
   if (plan) {
-    log.info(await renderInstallPlan({ noCache, backend, tts, vad, diarize }));
+    log.info(await renderInstallPlan({ noCache, backend, ttsLangs, vad, diarize }));
     return;
   }
 
@@ -91,7 +138,7 @@ export async function performInstall(
       command: "install",
       backend: backend ?? "auto",
       noCache,
-      tts,
+      tts: ttsLangs.length > 0,
       vad,
       diarize,
     });
@@ -111,11 +158,11 @@ export async function performInstall(
           `the release engine uses "${platformBackend}".`,
       );
     }
-    await downloadEngine(noCache, backend, { tts, vad, diarize });
+    await downloadEngine(noCache, backend, { ttsLangs, vad, diarize });
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = errorMessage(err);
     finishInstallDiagnostic(diagnosticLog, startedAt, "failed", errorKind);
     log.error(message);
     process.exit(1);
@@ -166,6 +213,23 @@ export const installCommand = defineCommand({
   },
   async run({ args, rawArgs }: { args: InstallCommandArgs; rawArgs: string[] }) {
     const backend = resolveBackendFlag(args.coreml, args.onnx);
-    await performInstall(resolveNoCacheFlag(args, rawArgs), backend, args.tts, args.vad, args.diarize, args.plan);
+    const positionals = (args._ ?? []).map(String);
+    const caps = await getEngineCapabilities();
+    const supported = caps?.tts?.languages.map((l) => l.code);
+    let ttsLangs: string[];
+    try {
+      ttsLangs = resolveTtsLangs({ tts: args.tts === true, positionals }, supported);
+    } catch (err) {
+      log.error(errorMessage(err));
+      process.exit(1);
+    }
+    await performInstall(
+      resolveNoCacheFlag(args, rawArgs),
+      backend,
+      ttsLangs,
+      args.vad,
+      args.diarize,
+      args.plan,
+    );
   },
 });