@drakulavich/kesha-voice-kit 1.23.0 → 1.24.0

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.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": {
@@ -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,90 @@ 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);
+
+/**
+ * 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[] } {
+  let flag = false;
+  const cleaned: string[] = [];
+  for (const arg of rawArgs) {
+    if (arg === "--no-color") {
+      flag = true;
+    } else if (arg.startsWith("--no-color=")) {
+      flag = !isFalsey(arg.slice("--no-color=".length));
+    } else {
+      cleaned.push(arg);
+    }
+  }
+  const ci = env.CI !== undefined && !isFalsey(env.CI);
+  return { disableColor: flag || 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[] } {
+  let flag = false;
+  const cleaned: string[] = [];
+  for (const arg of rawArgs) {
+    if (arg === "--quiet" || arg === "-q") {
+      flag = true;
+    } else if (arg.startsWith("--quiet=")) {
+      flag = !isFalsey(arg.slice("--quiet=".length));
+    } else {
+      cleaned.push(arg);
+    }
+  }
+  return { quiet: flag, 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,6 @@
 import { defineCommand } from "citty";
 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 +8,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 +21,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[] = [],
@@ -71,14 +117,14 @@ function finishInstallDiagnostic(
 
 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 +137,7 @@ export async function performInstall(
       command: "install",
       backend: backend ?? "auto",
       noCache,
-      tts,
+      tts: ttsLangs.length > 0,
       vad,
       diarize,
     });
@@ -111,7 +157,7 @@ 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) {
@@ -166,6 +212,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(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+    await performInstall(
+      resolveNoCacheFlag(args, rawArgs),
+      backend,
+      ttsLangs,
+      args.vad,
+      args.diarize,
+      args.plan,
+    );
   },
 });

package/src/cli/main.ts

@@ -37,6 +37,8 @@ interface MainCommandArgs {
   "include-errors": boolean;
   format?: string;
   lang?: string;
+  quiet: boolean;
+  "no-color": boolean;
 }
 
 export function detectLanguage(text: string): string {
@@ -116,7 +118,9 @@ export function shouldReportTranscribeProgress(input: {
   stderrIsTty: boolean;
   stdoutIsTty: boolean;
   debugEnabled: boolean;
+  quiet?: boolean;
 }): boolean {
+  if (input.quiet) return false;
   if (input.debugEnabled) return false;
   return input.stderrIsTty || !input.stdoutIsTty;
 }
@@ -147,6 +151,12 @@ export const mainCommand = defineCommand({
     description:
       "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
       "\n" +
+      "Examples:\n" +
+      "  kesha audio.ogg          Transcribe an audio file.\n" +
+      "  kesha --json audio.ogg   Transcribe with machine-readable output.\n" +
+      "  kesha say \"hello\"        Speak text (text-to-speech).\n" +
+      "  kesha init               Guided first-time setup.\n" +
+      "\n" +
       "Commands:\n" +
       "  completions  Print shell completion script.\n" +
       "  doctor     Collect support diagnostics.\n" +
@@ -178,7 +188,7 @@ export const mainCommand = defineCommand({
     },
     speakers: {
       type: "boolean",
-      description: "Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).",
+      description: "Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first. Implies --timestamps.",
       default: false,
     },
     "include-errors": {
@@ -197,7 +207,7 @@ export const mainCommand = defineCommand({
     },
     lang: {
       type: "string",
-      description: "Expected language code (ISO 639-1), warn if mismatch",
+      description: "Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch",
     },
     debug: {
       type: "boolean",
@@ -214,9 +224,25 @@ export const mainCommand = defineCommand({
       description: "Force full-file ASR for short/medium files; long audio fails early",
       default: false,
     },
+    // quiet and no-color are resolved before citty in dispatch.ts (so they
+    // apply to every command, not just transcribe); declared here only so they
+    // appear in `kesha --help`.
+    quiet: {
+      type: "boolean",
+      alias: "q",
+      description: "Suppress progress output; print only results and errors",
+      default: false,
+    },
+    "no-color": {
+      type: "boolean",
+      description: "Disable ANSI colors (also via NO_COLOR=1; auto-off when CI=true)",
+      default: false,
+    },
   },
   async run({ args, rawArgs }: { args: MainCommandArgs; rawArgs: string[] }) {
     if (args.debug) log.debugEnabled = true;
+    // `log.quietEnabled` is set globally in dispatch.ts (where --quiet/-q is
+    // resolved and stripped before citty), so it already reflects --quiet here.
     const files = args._;
 
     // Validate `--format <value>` and normalize into the boolean flags
@@ -297,6 +323,7 @@ export const mainCommand = defineCommand({
       stderrIsTty: process.stderr.isTTY === true,
       stdoutIsTty: process.stdout.isTTY === true,
       debugEnabled: log.isDebugEnabled(),
+      quiet: log.quietEnabled,
     });
 
     for (const file of files) {

package/src/cli/say.ts

@@ -111,7 +111,7 @@ export const sayCommand = defineCommand({
     lang: {
       type: "string",
       description:
-        "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.",
     },
     out: { type: "string", description: "Write audio to file instead of stdout" },
     rate: { type: "string", description: "Speaking rate 0.5–2.0", default: "1.0" },
@@ -239,16 +239,16 @@ export const sayCommand = defineCommand({
       const startedAt = performance.now();
       if (opts.out) {
         const voiceLabel = opts.voice ?? "default voice";
-        console.error(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
+        log.status(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
       }
       const audio = await stats.timeStage("tts", () => say(opts));
       const ttsTimeMs = Math.round(performance.now() - startedAt);
       if (opts.out) {
-        console.error(`Saved ${opts.out} (${ttsTimeMs}ms)`);
+        log.status(`Saved ${opts.out} (${ttsTimeMs}ms)`);
       }
       if (args.verbose && !opts.out) {
         // stderr — stdout may carry raw audio bytes when --out is omitted.
-        console.error(`TTS time: ${ttsTimeMs}ms`);
+        log.status(`TTS time: ${ttsTimeMs}ms`);
       }
       let outputFormat: string = opts.format ?? "wav";
       let outputSizeBytes: number | null | undefined = audio.byteLength;

package/src/engine-install.ts

@@ -325,9 +325,25 @@ async function warmDarwinKokoro(binPath: string): Promise<void> {
   }
 }
 
+/** Build the `kesha-engine install` argv from options. Exported for testing. */
+export function buildEngineInstallArgs(opts: {
+  noCache: boolean;
+  ttsLangs?: string[];
+  vad?: boolean;
+  diarize?: boolean;
+}): string[] {
+  return [
+    "install",
+    ...(opts.noCache ? ["--no-cache"] : []),
+    ...(opts.ttsLangs && opts.ttsLangs.length > 0 ? ["--tts", ...opts.ttsLangs] : []),
+    ...(opts.vad ? ["--vad"] : []),
+    ...(opts.diarize ? ["--diarize"] : []),
+  ];
+}
+
 export interface InstallOptions {
-  /** Also install Kokoro + Vosk-TTS models. */
-  tts?: boolean;
+  /** TTS languages to install (empty/undefined = no TTS). */
+  ttsLangs?: string[];
   /** Also install Silero VAD model for long-audio preprocessing. */
   vad?: boolean;
   /** Also install the Sortformer streaming-diarization model (~245MB,
@@ -498,13 +514,12 @@ export async function downloadEngine(
   }
 
   log.progress("Installing models...");
-  const installArgs = [
-    "install",
-    ...(noCache ? ["--no-cache"] : []),
-    ...(options.tts ? ["--tts"] : []),
-    ...(options.vad ? ["--vad"] : []),
-    ...(options.diarize ? ["--diarize"] : []),
-  ];
+  const installArgs = buildEngineInstallArgs({
+    noCache,
+    ttsLangs: options.ttsLangs,
+    vad: options.vad,
+    diarize: options.diarize,
+  });
   const proc = Bun.spawnSync([binPath, ...installArgs], {
     stdout: "pipe",
     stderr: "pipe",
@@ -520,7 +535,11 @@ export async function downloadEngine(
     throw new Error(detail ? `Failed to install models: ${detail}` : "Failed to install models");
   }
 
-  if (options.tts) {
+  // Warm the FluidAudio Kokoro CoreML cache only when a Kokoro language is
+  // requested. Russian (`ru`) routes through Vosk-TTS, not Kokoro, so a
+  // Russian-only install has nothing to warm.
+  const wantsKokoro = (options.ttsLangs ?? []).some((l) => l !== "ru");
+  if (wantsKokoro) {
     await warmDarwinKokoro(binPath);
   }
 

package/src/engine.ts

@@ -340,10 +340,16 @@ export async function detectTextLanguageEngine(
   return parseLangResult(stdout);
 }
 
+export interface TtsLanguageCapability {
+  code: string;
+  engines: string[];
+}
+
 export interface EngineCapabilities {
   protocolVersion: number;
   backend: string;
   features: string[];
+  tts?: { languages: TtsLanguageCapability[] };
 }
 
 let cachedEngineCapabilities:

package/src/install-plan.ts

@@ -13,7 +13,8 @@ import {
 export interface InstallPlanOptions {
   noCache?: boolean;
   backend?: string;
-  tts?: boolean;
+  /** Resolved TTS language codes, e.g. ["en", "ru"]. */
+  ttsLangs?: string[];
   vad?: boolean;
   diarize?: boolean;
 }
@@ -70,17 +71,29 @@ const G2P_CHARSIU_FILES: PlanFile[] = [
   { relPath: "models/g2p/byt5-tiny/decoder_with_past_model.onnx", sizeBytes: 5_427_260 },
 ];
 
-const KOKORO_FILES: PlanFile[] = [
-  { relPath: "models/kokoro-82m/model.onnx", sizeBytes: 325_532_387 },
-  { relPath: "models/kokoro-82m/voices/am_michael.bin", sizeBytes: 522_240 },
-  // Multilingual voice packs for es/fr/it/pt (#212).
-  // em_alex (es, male), ff_siwis (fr, female — only French voice in Kokoro v1.0),
-  // im_nicola (it, male), pm_alex (pt, male).
-  { relPath: "models/kokoro-82m/voices/em_alex.bin", sizeBytes: 522_240 },
-  { relPath: "models/kokoro-82m/voices/ff_siwis.bin", sizeBytes: 522_240 },
-  { relPath: "models/kokoro-82m/voices/im_nicola.bin", sizeBytes: 522_240 },
-  { relPath: "models/kokoro-82m/voices/pm_alex.bin", sizeBytes: 522_240 },
-];
+// Kokoro ONNX graph (shared by all Kokoro languages on non-darwin builds).
+const KOKORO_GRAPH_FILE: PlanFile = { relPath: "models/kokoro-82m/model.onnx", sizeBytes: 325_532_387 };
+
+// Per-language default voice files.
+// Multilingual voice packs for es/fr/it/pt (#212).
+// em_alex (es, male), ff_siwis (fr, female — only French voice in Kokoro v1.0),
+// im_nicola (it, male), pm_alex (pt, male).
+const KOKORO_VOICE_FILES: Record<string, PlanFile> = {
+  en: { relPath: "models/kokoro-82m/voices/am_michael.bin", sizeBytes: 522_240 },
+  es: { relPath: "models/kokoro-82m/voices/em_alex.bin", sizeBytes: 522_240 },
+  fr: { relPath: "models/kokoro-82m/voices/ff_siwis.bin", sizeBytes: 522_240 },
+  it: { relPath: "models/kokoro-82m/voices/im_nicola.bin", sizeBytes: 522_240 },
+  pt: { relPath: "models/kokoro-82m/voices/pm_alex.bin", sizeBytes: 522_240 },
+};
+
+function kokoroPlanFiles(langs: string[]): PlanFile[] {
+  const files: PlanFile[] = [KOKORO_GRAPH_FILE];
+  for (const l of langs) {
+    const v = KOKORO_VOICE_FILES[l];
+    if (v) files.push(v);
+  }
+  return files;
+}
 
 const VOSK_RU_FILES: PlanFile[] = [
   { relPath: "models/vosk-ru/model.onnx", sizeBytes: 179_314_533 },
@@ -240,53 +253,59 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
     ),
   );
 
-  if (options.tts) {
+  const ttsLangs = options.ttsLangs ?? [];
+  // Darwin ANE serves every non-ru language through Kokoro (en/es/fr/it/pt + the
+  // ANE-only hi/ja/zh), so the warm-up gate mirrors engine-install.ts's
+  // `some((l) => l !== "ru")`. The ONNX component, by contrast, only covers the
+  // graph-backed en/es/fr/it/pt set (hi/ja/zh are darwin-only and rejected on ONNX).
+  const wantsAnyKokoro = ttsLangs.some((l) => l !== "ru");
+  const wantsOnnxKokoro = ttsLangs.some((l) => ["en", "es", "fr", "it", "pt"].includes(l));
+  const wantsG2p = ttsLangs.some((l) => ["es", "fr", "it", "pt"].includes(l));
+  const wantsRu = ttsLangs.includes("ru");
+
+  if (ttsLangs.length > 0) {
     if (isDarwinArm64()) {
-      components.push(
-        bundleComponent(
-          cacheRoot,
-          "TTS Vosk RU",
-          "model cache",
-          VOSK_RU_FILES,
-          noCache,
-          "Russian ru-vosk-* voices",
-        ),
-      );
-      warmups.push({
-        name: "TTS Kokoro EN",
-        note: `${FLUID_KOKORO_CACHE_NOTE} (${fluidKokoroCachePath()})`,
-      });
+      if (wantsAnyKokoro) {
+        warmups.push({
+          name: "TTS Kokoro (ANE)",
+          note: `${FLUID_KOKORO_CACHE_NOTE} (${fluidKokoroCachePath()})`,
+        });
+      }
+      if (wantsRu) {
+        components.push(
+          bundleComponent(cacheRoot, "TTS Vosk RU", "model cache", VOSK_RU_FILES, noCache, "Russian ru-vosk-* voices"),
+        );
+      }
     } else {
-      components.push(
-        bundleComponent(
-          cacheRoot,
-          "TTS Kokoro EN/ES/FR/IT/PT",
-          "model cache",
-          KOKORO_FILES,
-          noCache,
-          "English en-* voices + multilingual es-*/fr-*/it-*/pt-* voices",
-        ),
-      );
-      components.push(
-        bundleComponent(
-          cacheRoot,
-          "G2P CharsiuG2P byt5-tiny",
-          "model cache",
-          G2P_CHARSIU_FILES,
-          noCache,
-          "multilingual grapheme-to-phoneme for es/fr/it/pt Kokoro voices (CC-BY 4.0)",
-        ),
-      );
-      components.push(
-        bundleComponent(
-          cacheRoot,
-          "TTS Vosk RU",
-          "model cache",
-          VOSK_RU_FILES,
-          noCache,
-          "Russian ru-vosk-* voices",
-        ),
-      );
+      if (wantsOnnxKokoro) {
+        components.push(
+          bundleComponent(
+            cacheRoot,
+            "TTS Kokoro graph + voices",
+            "model cache",
+            kokoroPlanFiles(ttsLangs),
+            noCache,
+            `voices for ${ttsLangs.filter((l) => l !== "ru").join(", ")}`,
+          ),
+        );
+      }
+      if (wantsG2p) {
+        components.push(
+          bundleComponent(
+            cacheRoot,
+            "G2P CharsiuG2P byt5-tiny",
+            "model cache",
+            G2P_CHARSIU_FILES,
+            noCache,
+            "multilingual G2P for es/fr/it/pt (CC-BY 4.0)",
+          ),
+        );
+      }
+      if (wantsRu) {
+        components.push(
+          bundleComponent(cacheRoot, "TTS Vosk RU", "model cache", VOSK_RU_FILES, noCache, "Russian ru-vosk-* voices"),
+        );
+      }
     }
   }
 
@@ -370,7 +389,7 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
     "  - install warms the ASR backend after downloads; CoreML warm-up is typically 20-30 s, ONNX warm-up is about 500 ms.",
   );
 
-  if (options.tts && isDarwinArm64()) {
+  if (ttsLangs.length > 0 && wantsAnyKokoro && isDarwinArm64()) {
     lines.push(
       "  - --tts also warms FluidAudio Kokoro CoreML; FluidAudio may download/compile its own Kokoro cache on first use.",
     );
@@ -382,7 +401,7 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
     options.noCache ? "--no-cache" : "",
     options.backend === "coreml" ? "--coreml" : "",
     options.backend === "onnx" ? "--onnx" : "",
-    options.tts ? "--tts" : "",
+    ...(ttsLangs.length > 0 ? ["--tts", ...ttsLangs] : []),
     options.vad ? "--vad" : "",
     options.diarize ? "--diarize" : "",
   ].filter(Boolean);

package/src/lib.ts

@@ -29,9 +29,13 @@ export type {
   TranscribeResult,
 } from "./types";
 
-/** Install Kokoro TTS models. Shorthand for `downloadModel({ tts: true })`. */
-export async function downloadTts(noCache = false): Promise<void> {
-  await downloadEngine(noCache, undefined, { tts: true });
+/**
+ * Install TTS models for the given languages (default: English only, matching
+ * `kesha install --tts`). Pass e.g. `["en", "ru"]` for more. Unsupported-on-platform
+ * codes are rejected by the engine.
+ */
+export async function downloadTts(noCache = false, langs: string[] = ["en"]): Promise<void> {
+  await downloadEngine(noCache, undefined, { ttsLangs: langs });
 }
 
 /** @deprecated Use `downloadModel` instead. */

package/src/log.ts

@@ -1,5 +1,21 @@
 import pc from "picocolors";
 
+/**
+ * Colorizer indirection (#531). `picocolors` decides color support once at
+ * import time (honoring `NO_COLOR`, TTY, `FORCE_COLOR`). To support a runtime
+ * `--no-color` flag we keep a swappable reference: `setColorEnabled(false)`
+ * replaces it with a no-op colorizer. Methods below read `colors.*`, never the
+ * frozen default binding, so the toggle takes effect immediately.
+ */
+// Narrower type than the default export (which also carries `createColors`),
+// so the no-op colorizer from `createColors(false)` is assignable back.
+let colors: ReturnType<typeof pc.createColors> = pc;
+
+/** Force colors on/off at runtime (used by `--no-color`). */
+export function setColorEnabled(enabled: boolean): void {
+  colors = enabled ? pc : pc.createColors(false);
+}
+
 /**
  * Debug mode (#148): when `KESHA_DEBUG` is truthy OR the caller has flipped
  * `log.debugEnabled = true` (via `--debug`), `log.debug()` writes structured
@@ -28,11 +44,30 @@ const PROCESS_T0_MS = performance.now();
 
 export const log = {
   info: (msg: string) => console.log(msg),
-  success: (msg: string) => console.log(pc.green(msg)),
-  progress: (msg: string) => console.log(pc.cyan(msg)),
-  warn: (msg: string) => console.error(pc.yellow(msg)),
-  error: (msg: string) => console.error(pc.red(msg)),
+  success: (msg: string) => console.log(colors.green(msg)),
+  // `--quiet` (#526) silences status/progress chatter; warnings and errors
+  // always print, and results are written straight to stdout (not via log.*).
+  progress: (msg: string) => {
+    if (log.quietEnabled) return;
+    console.log(colors.cyan(msg));
+  },
+  // stderr via process.stderr.write (not console.error): Bun auto-colors
+  // console.error red in a TTY, and that decision is frozen at startup — it
+  // would survive `--no-color`. Writing the stream directly leaves picocolors
+  // (which `setColorEnabled` controls) as the only colorizer, so `--no-color`
+  // and `CI=true` produce genuinely plain output. (#531)
+  warn: (msg: string) => void process.stderr.write(colors.yellow(msg) + "\n"),
+  error: (msg: string) => void process.stderr.write(colors.red(msg) + "\n"),
+  // Status/progress line on STDERR (e.g. `say --out`, where stdout may carry
+  // raw audio bytes). Suppressed under `--quiet` and colored via the swappable
+  // colorizer so `--no-color` applies; process.stderr.write (not console.error)
+  // avoids Bun's startup-frozen TTY auto-red. (#526/#531)
+  status: (msg: string) => {
+    if (log.quietEnabled) return;
+    process.stderr.write(colors.cyan(msg) + "\n");
+  },
 
+  quietEnabled: false,
   debugEnabled: false,
   isDebugEnabled(): boolean {
     return this.debugEnabled || envDebug();
@@ -47,7 +82,7 @@ export const log = {
       // process", read the prefix difference; for cross-process spans,
       // the spawn→exit `dt=Nms` inside the message remains authoritative.
       const t = Math.round(performance.now() - PROCESS_T0_MS);
-      console.error(pc.dim(`[debug +${t}ms] ${msg}`));
+      process.stderr.write(colors.dim(`[debug +${t}ms] ${msg}`) + "\n");
     }
   },
 };