@pyai/sdk 0.3.1 → 0.5.0

package/src/cli.ts

@@ -1,338 +1,474 @@
 #!/usr/bin/env node
-/**
- * pyai, CLI for the PyAI API: proves your key, the endpoint, and audio in one
- * command (`smoke`) or runs a deeper diagnosis with remediation hints (`doctor`).
- *
- * Commands:
- *   pyai doctor                         diagnose key/scopes + endpoint + Speak→Hear round-trip
- *   pyai smoke [--tolerate-upstream]    run models+voices+speak and report PASS/FAIL
- *                                       (--tolerate-upstream: transient 5xx/429 → WARN, not FAIL)
- *   pyai models                         list models
- *   pyai voices [--gender g --region r] list voices
- *   pyai speak --text T [--voice V] [--out f.wav]
- *   pyai transcribe --url U [--diarize] [--poll]
- *
- * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
- * Zero deps, uses the bundled SDK.
- */
+import "./cli-runtime.ts";
+/** Human and automation CLI. Stdout is results; stderr is errors. */
+import { createWriteStream, unlinkSync } from "node:fs";
+import { readFile, link, rename, unlink, stat, lstat } from "node:fs/promises";
+import { basename, dirname, resolve, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { CliHttp, CliError } from "./cli-http.ts";
+import { browserLogin } from "./cli-web-auth.ts";
+import { CliConfigError, resolveConfig, saveProfile, removeProfile, useProfile, listProfiles, validateApiKey, validateProfileName } from "./cli-config.ts";
+import { routes } from "./cli-routes.ts";
+import { aliases, shortFlags, recipes } from "./cli-dx.ts";
+import { CLI_TEMPLATES, scaffoldProject, CliInitError } from "./cli-init.ts";
+import { SPEECH_FORMATS, SPEECH_SAMPLE_RATES } from "./index.ts";
 
-import { writeFile } from "node:fs/promises";
-import PyAI, { PyAIError } from "./index.ts";
+type FlagType = "boolean" | "string" | "repeat";
+type Flags = Record<string, string | boolean | string[]>;
+type Command = { command: string; description: string; flags?: Record<string, FlagType>; args?: string[]; optionalArgs?: boolean; variadic?: boolean; example?: string };
+const globals: Record<string, FlagType> = {
+  "api-key": "string", "base-url": "string", profile: "string", json: "boolean",
+  timeout: "string", retries: "string", "dry-run": "boolean", help: "boolean", version: "boolean",
+};
+const bodyFlags: Record<string, FlagType> = { data: "string", "idempotency-key": "string" };
+const outputFlags: Record<string, FlagType> = { out: "string", force: "boolean" };
+const waitFlags: Record<string, FlagType> = { "wait-timeout": "string", "poll-interval": "string" };
+const commands: Command[] = [
+  { command: "auth login", description: "Sign in through the browser, or save an explicitly supplied API key", flags: { web: "boolean", "no-browser": "boolean", "login-timeout": "string", "key-stdin": "boolean" }, example: "pyai auth login --profile production" },
+  { command: "auth sandbox", description: "Create a sandbox tenant and save its key in a profile" },
+  { command: "auth status", description: "Inspect the active key with /v1/me" },
+  { command: "auth logout", description: "Remove a saved local profile (does not revoke the key)" },
+  { command: "profiles list", description: "List saved profiles without revealing keys" },
+  { command: "profiles use", description: "Select the default profile", args: ["name"] },
+  { command: "models list", description: "List available models" },
+  { command: "voices list", description: "List voices", flags: { gender: "string", region: "string", language: "string", tier: "string", q: "string", source: "string" } },
+  { command: "voices get", description: "Get one voice", args: ["id"] },
+  { command: "speak", description: "Synthesize text or stdin to an audio file", args: ["text"], optionalArgs: true, flags: { text: "string", "text-file": "string", voice: "string", model: "string", format: "string", "sample-rate": "string", ...outputFlags }, example: 'pyai speak "Hello from PyAI" -o hello.wav' },
+  { command: "transcribe", description: "Transcribe a local file, or submit an audio URL as a job", args: ["input"], optionalArgs: true, flags: { file: "string", url: "string", filename: "string", language: "string", "text-only": "boolean", diarize: "boolean", poll: "boolean", wait: "boolean", ...waitFlags, "idempotency-key": "string" }, example: "pyai transcribe call.wav --text-only" },
+  { command: "dub", description: "Dub a file or URL: submit, wait, and save the audio", args: ["input"], optionalArgs: true, flags: { file: "string", filename: "string", url: "string", from: "string", to: "string", ...outputFlags, ...waitFlags, ...bodyFlags }, example: "pyai dub original.wav --from en --to hi -o dubbed.wav" },
+  { command: "clones create", description: "Clone a voice from a reference audio file", flags: { file: "string", filename: "string", name: "string" } },
+  { command: "dub create", description: "Submit a local file or URL for dubbing", flags: { file: "string", filename: "string", url: "string", language: "string", "source-language": "string", ...bodyFlags } },
+  { command: "request", description: "Call a relative API route with JSON, including future endpoints", args: ["method", "path"], flags: { ...bodyFlags, ...outputFlags, query: "repeat" }, example: "pyai request GET /v1/me --json" },
+  { command: "schema", description: "Discover CLI commands offline, or retrieve live OpenAPI", args: ["command"], optionalArgs: true, variadic: true, flags: { openapi: "boolean" }, example: "pyai schema agents create --json" },
+  { command: "recipes", description: "Browse copyable workflows offline; never executes the examples", args: ["name"], optionalArgs: true, example: "pyai recipes speak" },
+  { command: "init", description: "Create a new project with API context and request examples offline", args: ["directory"], flags: { template: "string" }, example: "pyai init voice-demo --template typescript" },
+  { command: "smoke", description: "Check models, voices, and speech synthesis", flags: { "tolerate-upstream": "boolean" } },
+  { command: "doctor", description: "Diagnose key, catalogs, and a Speak to Hear round-trip" },
+  ...routes.map((r): Command => ({ command: r.command, description: r.description, args: r.id ? ["id"] : [], flags: {
+    ...(r.body ? bodyFlags : {}), ...(r.binary ? outputFlags : {}), ...(r.wait ? waitFlags : {}),
+    ...(r.command.endsWith(" list") || r.command === "amd calls" ? { limit: "string" as const, cursor: "string" as const } : {}),
+  } })),
+];
 
-interface Flags {
-  _: string[];
-  [k: string]: string | boolean | string[];
+function usage(message: string): never { throw new CliError("invalid_arguments", message, 2); }
+function value(flags: Flags, name: string): string | undefined { return typeof flags[name] === "string" ? flags[name] as string : undefined; }
+function required(flags: Flags, name: string): string { const v = value(flags, name); if (!v) usage(`--${name} is required`); return v; }
+function number(flags: Flags, name: string, fallback: number, min = 0, max = 86400): number {
+  const input = value(flags, name); const n = input === undefined ? fallback : Number(input);
+  if (!Number.isFinite(n) || n < min || n > max || input?.trim() === "") usage(`--${name} must be a number from ${min} to ${max}`);
+  return n;
 }
-
-function parseArgs(argv: string[]): Flags {
-  const flags: Flags = { _: [] };
+function parse(argv: string[]): { spec?: Command; flags: Flags; args: string[] } {
+  const known: Record<string, FlagType> = Object.assign(Object.create(null), globals);
+  for (const c of commands) Object.assign(known, c.flags);
+  const flags: Flags = Object.create(null); const words: string[] = [];
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]!;
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      const next = argv[i + 1];
-      if (next === undefined || next.startsWith("--")) {
-        flags[key] = true;
-      } else {
-        flags[key] = next;
-        i++;
-      }
+    let a = argv[i]!;
+    if (a === "--") { words.push(...argv.slice(i + 1)); break; }
+    a = shortFlags[a] ?? a;
+    if (!a.startsWith("--")) { if (a.startsWith("-") && a !== "-") usage(`Unknown option ${a}`); words.push(a); continue; }
+    const equal = a.indexOf("="); const key = a.slice(2, equal < 0 ? undefined : equal); const type = known[key];
+    if (!type) usage(`Unknown option --${key}; run pyai --help`);
+    if (type === "boolean") { if (equal >= 0) usage(`--${key} does not take a value`); flags[key] = true; continue; }
+    const v = equal >= 0 ? a.slice(equal + 1) : argv[++i];
+    if (v === undefined || (equal < 0 && (v.startsWith("--") || v in shortFlags))) usage(`--${key} requires a value`);
+    if (type === "repeat") { const list = (flags[key] ?? []) as string[]; list.push(v); flags[key] = list; }
+    else { if (flags[key] !== undefined) usage(`--${key} may only be supplied once`); flags[key] = v; }
+  }
+  if (words[0] === "help") { flags.help = true; words.shift(); }
+  if (words[0] && aliases[words[0]]) words.splice(0, 1, ...aliases[words[0]]!.split(" "));
+  if (["models", "voices", "profiles"].includes(words[0] ?? "") && words.length === 1) words.push("list");
+  const spec = [...commands].sort((a, b) => b.command.length - a.command.length).find(c => c.command.split(" ").every((w, i) => words[i] === w));
+  if (!spec) {
+    if (words.length && !flags.help) usage(`Unknown command ${words.join(" ")}; run pyai --help`);
+    return { flags, args: words };
+  }
+  const args = words.slice(spec.command.split(" ").length);
+  const expected = spec.args?.length ?? 0;
+  if (!flags.help && ((!spec.optionalArgs && args.length < expected) || (!spec.variadic && args.length > expected))) usage(`Usage: pyai ${spec.command} ${(spec.args ?? []).map(x => spec.optionalArgs ? `[${x}]` : `<${x}>`).join(" ")}`);
+  for (const k of Object.keys(flags)) if (!(k in globals) && !(k in (spec.flags ?? {}))) usage(`--${k} is not supported by ${spec.command}`);
+  if (!flags.help && args.length && ["speak", "transcribe", "dub"].includes(spec.command)) {
+    if (spec.command === "speak") {
+      if (flags.text !== undefined || flags["text-file"] !== undefined) usage("Choose positional text, --text, or --text-file, not multiple inputs");
+      flags.text = args[0]!;
     } else {
-      (flags._ as string[]).push(a);
+      if (flags.file !== undefined || flags.url !== undefined) usage("Choose a positional input, --file, or --url, not multiple inputs");
+      flags[/^https?:\/\//i.test(args[0]!) ? "url" : "file"] = args[0]!;
     }
   }
-  return flags;
+  return { spec, flags, args };
 }
 
-function flag(flags: Flags, key: string): string | undefined {
-  const v = flags[key];
-  return typeof v === "string" ? v : undefined;
+const secrets = new Set<string>();
+const optionArgs = process.argv.slice(2, process.argv.indexOf("--", 2) < 0 ? undefined : process.argv.indexOf("--", 2));
+const jsonMode = optionArgs.includes("--json") || optionArgs.includes("-j");
+function redact(input: unknown, redactFields = true): unknown {
+  if (typeof input === "string") { let s = input; for (const secret of secrets) s = s.split(secret).join("[REDACTED]"); return s; }
+  if (Array.isArray(input)) return input.map(v => redact(v, redactFields));
+  if (input && typeof input === "object") return Object.fromEntries(Object.entries(input).map(([k, v]) => [k, redactFields && /(?:api[_-]?key|authorization|password|secret|token)$/i.test(k) ? "[REDACTED]" : redact(v, redactFields)]));
+  return input;
 }
-
-function client(flags: Flags): PyAI {
-  const apiKey = flag(flags, "api-key") ?? process.env.PYAI_API_KEY;
-  if (!apiKey) {
-    fail("No API key. Set PYAI_API_KEY or pass --api-key pyai_test_...");
+function output(data: unknown, flags: Flags, human?: string, redactFields = true): void {
+  process.stdout.write(flags.json || !human ? `${JSON.stringify(redact(data, redactFields), null, flags.json ? 0 : 2)}\n` : `${redact(human)}\n`);
+}
+function transcriptOutput(data: unknown, flags: Flags, path?: string): void {
+  if (!flags["text-only"]) { output(data, flags); return; }
+  const result = data as { text?: unknown; result?: { text?: unknown }; result_url?: unknown } | null;
+  const text = result?.text ?? result?.result?.text;
+  if (typeof text !== "string") {
+    if (typeof result?.result_url === "string") throw new CliError("transcript_offloaded", "Transcript is stored as an external result. Use jobs get with --json to retrieve its result_url.", 1, { path });
+    throw new CliError("invalid_response", "The API response did not contain transcript text", 1, { path });
   }
-  return new PyAI({ apiKey: apiKey!, baseURL: flag(flags, "base-url") ?? process.env.PYAI_BASE_URL });
+  process.stdout.write(`${redact(text)}${text.endsWith("\n") ? "" : "\n"}`);
 }
-
-function out(msg: string): void {
-  process.stdout.write(`${msg}\n`);
+async function stdin(): Promise<Buffer> {
+  if (process.stdin.isTTY) usage("Pipe input through stdin, or supply a file path");
+  const chunks: Buffer[] = []; let size = 0;
+  for await (const chunk of process.stdin) { const b = Buffer.from(chunk); size += b.length; if (size > 128 * 1024 * 1024) usage("stdin exceeds 128 MiB; use a file or hosted audio URL"); chunks.push(b); }
+  return Buffer.concat(chunks);
 }
-function fail(msg: string): never {
-  process.stderr.write(`pyai: ${msg}\n`);
-  process.exit(1);
+async function inputFile(path: string): Promise<Buffer> { return path === "-" ? stdin() : readFile(path); }
+async function jsonInput(flags: Flags, objectOnly: true): Promise<Record<string, unknown>>;
+async function jsonInput(flags: Flags, objectOnly?: false): Promise<unknown>;
+async function jsonInput(flags: Flags, objectOnly = false): Promise<unknown> {
+  const raw = required(flags, "data");
+  const text = raw.startsWith("@") ? (await inputFile(raw.slice(1))).toString("utf8") : raw;
+  let parsed: unknown; try { parsed = JSON.parse(text); } catch { usage("--data must contain valid JSON (inline, @file.json, or @-)"); }
+  if (objectOnly && (!parsed || typeof parsed !== "object" || Array.isArray(parsed))) usage("--data must be a JSON object");
+  return parsed;
 }
-
-const USAGE = `pyai, PyAI API CLI
-
-Usage:
-  pyai doctor                             diagnose key/scopes + endpoint + Speak→Hear round-trip
-  pyai smoke [--tolerate-upstream]        run a key/endpoint/audio smoke test
-                                          (--tolerate-upstream: transient 5xx/429 warn, don't fail)
-  pyai models                             list models
-  pyai voices [--gender g] [--region r]   list voices
-  pyai speak --text T [--voice V] [--out f.wav]
-  pyai transcribe --url U [--diarize] [--poll]
-
-Auth: PYAI_API_KEY (or --api-key). Base: PYAI_BASE_URL (or --base-url).`;
-
-async function cmdModels(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  const res = await pyai.models.list();
-  out(JSON.stringify(res, null, 2));
+function headers(flags: Flags): Record<string, string> { const key = value(flags, "idempotency-key"); return key ? { "Idempotency-Key": key } : {}; }
+function safeId(id: string): string { if (!id || id === "." || id === ".." || /[\x00-\x1f\x7f]/.test(id)) usage("Invalid resource id"); return encodeURIComponent(id); }
+function withQuery(path: string, fields: Record<string, string | undefined>): string {
+  const q = new URLSearchParams(Object.entries(fields).filter((kv): kv is [string, string] => kv[1] !== undefined));
+  return q.toString() ? `${path}${path.includes("?") ? "&" : "?"}${q}` : path;
 }
-
-async function cmdVoices(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  const res = await pyai.voices.list({ gender: flag(flags, "gender"), region: flag(flags, "region") });
-  out(JSON.stringify(res, null, 2));
+function describeBody(body: unknown): unknown {
+  if (!(body instanceof FormData)) return body;
+  const fields: Record<string, unknown> = {};
+  body.forEach((v, k) => { fields[k] = typeof v === "string" ? v : { filename: v.name, bytes: v.size, type: v.type }; });
+  return fields;
 }
-
-async function cmdSpeak(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  const text = flag(flags, "text");
-  if (!text) fail("speak requires --text");
-  const audio = await pyai.audio.speech({ input: text!, voice: flag(flags, "voice") });
-  const outPath = flag(flags, "out") ?? "pyai-speak.wav";
-  await writeFile(outPath, Buffer.from(audio));
-  out(`wrote ${Buffer.from(audio).byteLength} bytes -> ${outPath}`);
+function preview(flags: Flags, baseURL: string, method: string, path: string, body?: unknown): boolean {
+  if (!flags["dry-run"]) return false;
+  output({ dry_run: true, method, url: `${baseURL}${path}`, body: describeBody(body) ?? null, headers: headers(flags) }, flags); return true;
 }
-
-async function cmdTranscribe(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  const url = flag(flags, "url");
-  if (!url) fail("transcribe requires --url (an https audio URL)");
-  const job = await pyai.transcriptionJobs.create({ audio_url: url!, diarize: flags.diarize === true });
-  out(`job ${job.job_id} (${job.status})`);
-  if (flags.poll !== true) return;
-  for (let i = 0; i < 60; i++) {
-    await new Promise((r) => setTimeout(r, 2000));
-    const j = await pyai.transcriptionJobs.get(job.job_id);
-    if (j.status === "completed" || j.status === "failed" || j.status === "cancelled") {
-      out(JSON.stringify(j, null, 2));
-      return;
-    }
+async function upload(flags: Flags, field: string): Promise<FormData> {
+  const file = required(flags, "file"); const bytes = await inputFile(file);
+  if (!bytes.length) usage("Audio input is empty");
+  const form = new FormData(); form.set(field, new Blob([new Uint8Array(bytes)]), value(flags, "filename") ?? (file === "-" ? "audio.wav" : basename(file)));
+  return form;
+}
+async function dubForm(flags: Flags, language: string, sourceLanguage?: string): Promise<FormData> {
+  if (!!value(flags, "file") === !!value(flags, "url")) usage("Provide exactly one audio file or URL");
+  if (value(flags, "file") === "-" && value(flags, "data") === "@-") usage("Audio and JSON cannot both consume stdin");
+  const form = value(flags, "file") ? await upload(flags, "file") : new FormData();
+  if (value(flags, "url")) form.set("source_url", value(flags, "url")!);
+  form.set("target_lang", language);
+  if (sourceLanguage) form.set("source_lang", sourceLanguage);
+  if (flags.data !== undefined) for (const [k, v] of Object.entries(await jsonInput(flags, true))) {
+    if (form.has(k) || ["file", "source_url"].includes(k)) usage(`Duplicate or reserved Dub field ${k}`);
+    form.set(k, typeof v === "string" ? v : JSON.stringify(v));
   }
-  out(`job ${job.job_id} still running after polling; check later.`);
+  return form;
 }
-
-// Transient upstream conditions: a momentary engine/capacity blip or network
-// hiccup, NOT a key/scope/contract problem. 5xx = engine unhealthy (e.g. Speak
-// "503 service_unavailable"), 429 = rate/capacity, a non-PyAIError = network.
-// These self-heal; the others (401/403/404/400) are real and must fail loudly.
-const TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);
-function isTransient(err: unknown): boolean {
-  if (err instanceof PyAIError) return TRANSIENT_STATUSES.has(err.status);
-  return true; // network / timeout / unknown, worth a retry, never a hard fail on its own
+async function checkOutput(path: string, flags: Flags): Promise<void> {
+  if (path === "-" && flags.json) usage("--out - cannot be combined with --json; use a file for a JSON receipt");
+  if (path === "-" && process.stdout.isTTY) usage("Refusing binary audio on a terminal; use --out FILE or pipe stdout");
+  if (path === "-") return;
+  const parent = await stat(dirname(resolve(path)));
+  if (!parent.isDirectory()) usage("Output parent must be a directory");
+  if (flags.force) return;
+  try { await lstat(path); } catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return; throw e; }
+  usage(`Output already exists: ${path}; choose another path or pass --force`);
 }
-
-/** Retry `fn` on transient upstream errors with exponential backoff. Real
- * (non-transient) errors throw immediately, we never paper over a bad key. */
-async function withRetry<T>(fn: () => Promise<T>, attempts = 4, baseMs = 800): Promise<T> {
-  let lastErr: unknown;
-  for (let i = 0; i < attempts; i++) {
-    try {
-      return await fn();
-    } catch (err) {
-      lastErr = err;
-      if (!isTransient(err) || i === attempts - 1) throw err;
-      await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+const pendingAudioFiles = new Set<string>();
+async function writeAudio(response: Response, path: string, flags: Flags, metadata: Record<string, unknown> = {}): Promise<void> {
+  if (!response.body) throw new CliError("empty_audio", "The API returned an empty audio body");
+  let bytes = 0;
+  const counter = new Transform({ transform(chunk, _encoding, callback) { bytes += chunk.length; callback(null, chunk); } });
+  const source = Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]);
+  if (path === "-") { await pipeline(source, counter, process.stdout, { end: false }); return; }
+  const destination = resolve(path); const temporary = join(dirname(destination), `.pyai-${randomUUID()}.tmp`);
+  pendingAudioFiles.add(temporary);
+  try {
+    await pipeline(source, counter, createWriteStream(temporary, { flags: "wx", mode: 0o600 }));
+    if (!bytes) throw new CliError("empty_audio", "The API returned an empty audio body");
+    if (flags.force) await rename(temporary, destination);
+    else await link(temporary, destination);
+  } finally { await unlink(temporary).catch(() => {}); pendingAudioFiles.delete(temporary); }
+  output({ ...metadata, path: destination, bytes, content_type: response.headers.get("content-type") }, flags, `wrote ${bytes} bytes -> ${path}`);
+}
+async function waitForJob(http: CliHttp, path: string, flags: Flags, success: string[], failure: string[]): Promise<unknown> {
+  const timeout = number(flags, "wait-timeout", 120, 0.001) * 1000;
+  const interval = number(flags, "poll-interval", 2, 0.001, 60) * 1000;
+  const requestTimeout = number(flags, "timeout", 30, 0.001) * 1000;
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new CliError("job_timeout", "Job is still running; use its get or wait command to resume", 4, { path });
+    let job;
+    try { job = await http.json("GET", path, { timeoutMs: Math.min(remaining, requestTimeout) }); }
+    catch (e) {
+      if (e instanceof CliError && e.code === "timeout" && remaining <= requestTimeout) throw new CliError("job_timeout", "Job is still running; use its get or wait command to resume", 4, { path });
+      if (e instanceof CliError) throw new CliError(e.code, e.message, e.exitCode, { ...e.details, path });
+      throw e;
     }
+    if (!job || typeof job.status !== "string") throw new CliError("invalid_response", "Job response is missing status", 1, { path });
+    if (success.includes(job.status)) return job;
+    if (failure.includes(job.status)) throw new CliError("job_failed", "Job ended without a successful result", 1, { path, job });
+    await new Promise(r => setTimeout(r, Math.min(interval, Math.max(0, deadline - Date.now()))));
   }
-  throw lastErr;
 }
 
-/** The headline: prove key + endpoint + audio in one command. */
-async function cmdSmoke(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  // CI/ops opt-in: a transient upstream blip (engine warming, a brief 503,
-  // rate-limit) should not red the build, it isn't the commit's fault. With this
-  // on, such failures are reported as WARN (exit 0); real key/scope/contract
-  // failures still FAIL (exit 1). Off by default so a developer running `pyai
-  // smoke` gets the strict, honest answer.
-  const tolerateUpstream = flags["tolerate-upstream"] === true || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1";
-  // Retry tuning is env-overridable (tests drive it fast; default rides brief blips).
-  const retryAttempts = Number(process.env.PYAI_SMOKE_RETRY_ATTEMPTS ?? 4);
-  const retryBaseMs = Number(process.env.PYAI_SMOKE_RETRY_BASE_MS ?? 800);
-  type Status = "PASS" | "WARN" | "FAIL";
-  const checks: Array<{ name: string; status: Status; detail: string }> = [];
-  const run = async (name: string, fn: () => Promise<string>) => {
-    try {
-      checks.push({ name, status: "PASS", detail: await withRetry(fn, retryAttempts, retryBaseMs) });
-    } catch (err) {
-      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : (err as Error).message;
-      const status: Status = isTransient(err) && tolerateUpstream ? "WARN" : "FAIL";
-      checks.push({ name, status, detail });
+async function diagnostics(http: CliHttp, cmd: string, flags: Flags): Promise<void> {
+  const checks: Array<{ name: string; status: string; detail: string; hint?: string }> = [];
+  const tolerate = cmd === "smoke" && (flags["tolerate-upstream"] || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1");
+  const check = async (name: string, fn: () => Promise<string>) => {
+    try { checks.push({ name, status: "PASS", detail: await fn() }); }
+    catch (err) {
+      const e = err as CliError; const status = Number(e.details?.status);
+      if (name === "key (/v1/me)" && status === 404) { checks.push({ name, status: "SKIP", detail: "introspection route not on this deployment" }); return; }
+      const transient = status === 429 || status >= 500 || e.exitCode === 4;
+      const hint = status === 401 ? "Check PYAI_API_KEY or run pyai auth login." : status === 403 ? "Check required API key scopes in the console." : status === 404 ? "Check PYAI_BASE_URL and the endpoint." : status === 402 ? "Check account credit and key budget in the console." : status === 429 ? "Wait for Retry-After before trying again." : "Check endpoint availability; retry when healthy.";
+      checks.push({ name, status: tolerate && transient ? "WARN" : "FAIL", detail: e.message, hint });
     }
   };
-
-  await run("models.list", async () => {
-    const r = await pyai.models.list();
-    return `${r.data.length} models`;
-  });
-  await run("voices.list", async () => {
-    const r = await pyai.voices.list();
-    return `${r.data.length} voices`;
+  if (cmd === "doctor") await check("key (/v1/me)", async () => { const me = await http.json("GET", "/v1/me"); return `env=${me.environment ?? me.env ?? "unknown"}; scopes: ${(me.scopes ?? []).join(", ")}`; });
+  await check("models.list", async () => `${(await http.json("GET", "/v1/models")).data.length} models`);
+  await check("voices.list", async () => `${(await http.json("GET", "/v1/voices")).data.length} voices`);
+  await check(cmd === "doctor" ? "speak→hear round-trip" : "audio.speech", async () => {
+    const response = await http.request("POST", "/v1/audio/speech", { json: { model: "pyai-speak", input: "The quick brown fox jumps over the lazy dog." } });
+    const audio = await response.arrayBuffer();
+    if (!audio.byteLength) throw new CliError("empty_audio", "Speech returned no audio");
+    if (cmd === "smoke") return `${audio.byteLength} bytes of audio`;
+    const form = new FormData(); form.set("file", new Blob([audio], { type: "audio/wav" }), "doctor.wav"); form.set("model", "pyai-hear");
+    const tr = await http.json("POST", "/v1/audio/transcriptions", { body: form });
+    if (!tr.text?.trim()) throw new CliError("empty_transcript", "Transcription came back empty");
+    return `synth ${audio.byteLength} bytes → ${tr.text.slice(0, 80)}`;
   });
-  await run("audio.speech", async () => {
-    const audio = await pyai.audio.speech({ input: "PyAI smoke test." });
-    return `${Buffer.from(audio).byteLength} bytes of audio`;
-  });
-
-  for (const c of checks) out(`${c.status}  ${c.name}, ${c.detail}`);
-  const failed = checks.filter((c) => c.status === "FAIL");
-  const warned = checks.filter((c) => c.status === "WARN");
-  // GitHub Actions annotation: a tolerated blip is still surfaced in the run UI.
-  for (const c of warned) out(`::warning title=PyAI smoke transient::${c.name}: ${c.detail}`);
-  if (failed.length === 0 && warned.length === 0) {
-    out("\nAll checks passed. Your key, the endpoint, and audio synthesis work.");
-  } else if (failed.length === 0) {
-    out(`\n${warned.length} transient upstream issue(s) tolerated (self-healing engine blip), not failing the build.`);
-  } else {
-    out("\nSome checks failed (see above).");
-    process.exit(1);
+  const failed = checks.filter(c => c.status === "FAIL").length; const warned = checks.filter(c => c.status === "WARN").length;
+  if (flags.json) output({ ok: !failed, checks }, flags);
+  else {
+    for (const c of checks) { process.stdout.write(`${redact(`${c.status.padEnd(4)}  ${c.name}, ${c.detail}`)}\n`); if (c.hint) process.stdout.write(`        ↳ ${c.hint}\n`); }
+    if (cmd === "doctor") process.stdout.write(failed ? `\nDiagnosis: ${failed} check(s) failed.\n` : "\nDiagnosis: healthy.\n");
+    else if (failed) process.stdout.write("\nSome checks failed (see above).\n");
+    else if (warned) { process.stdout.write(`\n${warned} transient upstream issue(s) tolerated.\n`); for (const c of checks.filter(c => c.status === "WARN")) process.stdout.write(`::warning title=PyAI smoke transient::${c.name}\n`); }
+    else process.stdout.write("\nAll checks passed.\n");
   }
+  if (failed) process.exitCode = 1;
 }
 
-/** Turn an error into an actionable, code-first remediation hint. */
-function remediation(err: unknown): string {
-  if (!(err instanceof PyAIError)) return (err as Error)?.message ?? String(err);
-  switch (err.code) {
-    case "unauthorized":
-      return "Invalid or missing key, check PYAI_API_KEY (a pyai_test_ or pyai_live_ key).";
-    case "forbidden":
-      return "Key is missing a required scope, add it to the key in the console.";
-    case "origin_not_allowed":
-      return "Publishable token origin not allow-listed, fix the allowed origins.";
-    case "credit_exhausted":
-      return "Out of prepaid credit, add credit, or use a pyai_test_ sandbox key.";
-    case "key_budget_exceeded":
-      return "Per-key monthly budget hit, raise the budget in the console.";
-    case "insufficient_quota":
-      return "Plan quota exhausted, upgrade your plan.";
-    case "rate_limit_exceeded":
-      return "Rate limited, back off and retry (honor Retry-After).";
-    case "concurrency_limit_exceeded":
-      return "Too many concurrent sessions, retry shortly.";
-    case "daily_cap_exceeded":
-      return "Daily cap reached, wait until it resets.";
-    default:
-      break;
+async function main(): Promise<void> {
+  const { spec, flags, args } = parse(process.argv.slice(2));
+  if (flags.version) { const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")); output({ version: pkg.version }, flags, pkg.version); return; }
+  if (!spec || flags.help) {
+    const group = args.join(" ");
+    const grouped = group ? commands.filter(c => c.command.startsWith(`${group} `)) : commands;
+    const visible = spec ? [spec, ...commands.filter(c => c.command.startsWith(`${spec.command} `))] : grouped.length ? grouped : commands;
+    if (flags.json) output({ name: "pyai", globals, aliases, short_flags: shortFlags, commands: visible }, flags, undefined, false);
+    else if (!spec && !group) process.stdout.write(`PyAI CLI — speech, agents, and automation\n\nStart here\n  pyai login                                 Sign in through your browser\n  pyai speak "Hello from PyAI" -o hello.wav    Turn text into audio\n  pyai hear call.wav --text-only              Print a transcript\n  pyai dub call.wav --from en --to hi -o hi.wav\n                                             Submit, wait, and save dubbed audio\n  pyai init voice-demo --template typescript  Create a starter project offline\n\nDiscover\n  pyai recipes [name]        Copyable workflows\n  pyai help <command>        Command options and examples\n  pyai help all              Every command\n  pyai schema [command] -j   Machine-readable command definitions\n\nGroups\n  auth  profiles  models  voices  agents  jobs  clones  design\n  cast  dub  recap  trace  tools  vocabulary  amd\n\nShortcuts: login, logout, whoami, use, say (speak), hear (transcribe)\nOptions: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nGlobal: --base-url URL --api-key KEY --timeout SECONDS --retries N --dry-run\nCredentials: pyai login or PYAI_API_KEY. Run pyai doctor for a usage-consuming diagnostic.\n`);
+    else process.stdout.write(`PyAI CLI — speech, agents, and automation\n\n${visible.map(c => `  pyai ${c.command}${(c.args ?? []).map(a => c.optionalArgs ? ` [${a}${c.variadic ? "..." : ""}]` : ` <${a}>`).join("")}\n    ${c.description}${c.flags ? `\n    Options: ${Object.keys(c.flags).map(k => `--${k}${c.flags![k] === "boolean" ? "" : " VALUE"}`).join(" ")}` : ""}${c.example ? `\n    ${c.example}` : ""}`).join("\n")}\n\nGlobal: --profile NAME --json --timeout SECONDS --retries N --dry-run\n        --base-url URL --api-key KEY --help --version\nShort flags: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nAuth: pyai login or PYAI_API_KEY. Discover: pyai schema --json\n`);
+    return;
   }
-  switch (err.status) {
-    case 401:
-      return "Invalid or missing key, check PYAI_API_KEY.";
-    case 403:
-      return "Forbidden, the key likely lacks the required scope.";
-    case 404:
-      return "Not found, check PYAI_BASE_URL and the route.";
-    case 429:
-      return "Rate/concurrency limited, back off and retry.";
-    default:
-      return err.message;
+  const cmd = spec.command;
+  if (cmd === "schema" && flags.openapi && args.length) usage("--openapi returns the complete live contract; omit the command filter");
+  if (cmd === "schema" && !flags.openapi) {
+    const filterWords = [...args];
+    if (filterWords[0] && aliases[filterWords[0]]) filterWords.splice(0, 1, ...aliases[filterWords[0]]!.split(" "));
+    const filter = filterWords.join(" ");
+    const matches = (c: { command: string }) => !filter || c.command === filter || c.command.startsWith(`${filter} `);
+    const selected = commands.filter(matches);
+    if (!selected.length) usage(`Unknown command group ${filter}; run pyai --help`);
+    output({ schema_version: 1, name: "pyai", global_flags: globals, short_flags: shortFlags, aliases, commands: selected, routes: routes.filter(matches), templates: CLI_TEMPLATES, output: { success: "JSON result on stdout with --json; no progress mixed in", error: "JSON error on stderr with --json", authorization: "Browser login emits public authorization events as NDJSON on stderr while waiting", binary: "--out - streams bytes; cannot combine with --json", text: "transcribe --text-only prints transcript text; cannot combine with --json" }, exit_codes: { "0": "success", "1": "API or job failure", "2": "arguments or local configuration", "3": "authentication or permission", "4": "network or timeout", "130": "interrupted" } }, flags, undefined, false); return;
   }
-}
-
-interface DoctorCheck {
-  name: string;
-  status: "PASS" | "FAIL" | "SKIP";
-  detail: string;
-  hint?: string;
-}
-
-async function doctorCheck(checks: DoctorCheck[], name: string, fn: () => Promise<string>): Promise<void> {
-  try {
-    checks.push({ name, status: "PASS", detail: await fn() });
-  } catch (err) {
-    const detail =
-      err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : (err as Error).message;
-    checks.push({ name, status: "FAIL", detail, hint: remediation(err) });
+  if (cmd === "recipes") {
+    const recipe = args[0] ? recipes.find(r => r.name === args[0]) : undefined;
+    if (args[0] && !recipe) usage(`Unknown recipe ${args[0]}; run pyai recipes`);
+    output(recipe ?? { recipes }, flags, recipe ? `${recipe.title}\n${recipe.description}\n\n${recipe.commands.map(c => `  ${c}`).join("\n")}\n\n${recipe.notes.join("\n")}` : `PyAI recipes — copy and adapt; nothing is executed\n\n${recipes.map(r => `  ${r.name.padEnd(12)}${r.title}`).join("\n")}\n\nRun pyai recipes <name> for commands, or add --json for automation.`); return;
   }
-}
-
-/** Deeper than smoke: key/scopes, endpoint liveness, and a Speak→Hear round-trip. */
-async function cmdDoctor(flags: Flags): Promise<void> {
-  const pyai = client(flags);
-  const checks: DoctorCheck[] = [];
-
-  // (a) Key validity + scopes via GET /v1/me. The route is new, so a 404 means
-  // "not deployed here yet", skip it rather than failing the whole doctor.
-  try {
-    const me = await pyai.me();
-    const scopes = Array.isArray(me.scopes) ? me.scopes : [];
-    const env = me.environment ?? me.env ?? "unknown";
-    checks.push({
-      name: "key (/v1/me)",
-      status: "PASS",
-      detail: `env=${env}; ${scopes.length} scope(s)${scopes.length ? `: ${scopes.join(", ")}` : ""}`,
-    });
-  } catch (err) {
-    if (err instanceof PyAIError && err.status === 404) {
-      checks.push({ name: "key (/v1/me)", status: "SKIP", detail: "introspection route not on this deployment" });
-    } else {
-      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""}`.trim() : (err as Error).message;
-      checks.push({ name: "key (/v1/me)", status: "FAIL", detail, hint: remediation(err) });
+  if (cmd === "init") {
+    const result = await scaffoldProject({ directory: args[0]!, template: value(flags, "template") as Parameters<typeof scaffoldProject>[0]["template"], dryRun: flags["dry-run"] === true });
+    output(result, flags, `${result.created ? "Created" : "Would create"} ${result.template} starter at ${result.directory}\n\n${result.files.map(f => `  ${f}`).join("\n")}\n\n${result.next_steps.join("\n")}`); return;
+  }
+  if (cmd === "profiles list") { output(await listProfiles(), flags); return; }
+  if (cmd === "profiles use") { if (!flags["dry-run"]) await useProfile(args[0]!); output({ profile: args[0], dry_run: !!flags["dry-run"] }, flags, `${flags["dry-run"] ? "Would select" : "Selected"} profile ${args[0]}`); return; }
+  if (cmd === "auth login") {
+    const profile = validateProfileName(value(flags, "profile") ?? process.env.PYAI_PROFILE ?? "default");
+    if (flags["key-stdin"] && value(flags, "api-key")) usage("Choose --key-stdin or --api-key");
+    const explicitKey = flags["key-stdin"] || flags["api-key"] !== undefined;
+    if (explicitKey && (flags.web || flags["no-browser"] || flags["login-timeout"] !== undefined)) usage("Browser login options cannot be combined with --key-stdin or --api-key");
+    if (!explicitKey) {
+      const { baseURL } = await resolveConfig({ baseURL: value(flags, "base-url"), profile, allowMissingProfile: true, ignoreApiKey: true });
+      const timeoutMs = number(flags, "timeout", 30, 0.001) * 1000;
+      const loginTimeoutMs = number(flags, "login-timeout", 600, 0.001, 3600) * 1000;
+      if (flags["dry-run"]) { output({ dry_run: true, method: "POST", url: `${baseURL}/auth/cli/device`, profile, browser: !flags["no-browser"], authorization: "Approve the displayed code in the console; credentials are saved after approval" }, flags); return; }
+      const result = await browserLogin({ http: new CliHttp({ baseURL, timeoutMs, maxRetries: 0 }), baseURL,
+        noBrowser: flags["no-browser"] === true || (!!process.env.CI && !flags.web), timeoutMs: loginTimeoutMs, requestTimeoutMs: timeoutMs,
+        onSecret: key => secrets.add(key),
+        onAuthorization: notice => {
+          if (flags.json) process.stderr.write(`${JSON.stringify(notice)}\n`);
+          else process.stderr.write(`Open ${notice.verification_uri_complete}\nConfirm code ${notice.user_code} in the browser, then choose a project.\nWaiting for approval…\n`);
+        },
+        onBrowserUnavailable: () => {
+          process.stderr.write(flags.json ? `${JSON.stringify({ event: "browser_unavailable", message: "Open the verification link manually" })}\n` : "Could not launch a browser. Open the link above manually.\n");
+        },
+      });
+      await saveProfile(profile, { api_key: result.api_key, base_url: baseURL });
+      const { api_key: _key, ...metadata } = result;
+      output({ ...metadata, profile, base_url: baseURL, saved: true }, flags, `Signed in. Saved ${result.environment} credentials for profile ${profile}.`);
+      return;
     }
+    const key = flags["key-stdin"] ? (await stdin()).toString("utf8").trim() : required(flags, "api-key");
+    secrets.add(key); validateApiKey(key);
+    const { baseURL } = await resolveConfig({ apiKey: key, baseURL: value(flags, "base-url"), profile, allowMissingProfile: true });
+    if (!flags["dry-run"]) await saveProfile(profile, { api_key: key, base_url: baseURL });
+    output({ profile, base_url: baseURL, saved: !flags["dry-run"] }, flags, `${flags["dry-run"] ? "Would save" : "Saved"} credentials for ${profile}`); return;
   }
-
-  // (b) Endpoint liveness.
-  await doctorCheck(checks, "models.list", async () => `${(await pyai.models.list()).data.length} models`);
-  await doctorCheck(checks, "voices.list", async () => `${(await pyai.voices.list()).data.length} voices`);
-
-  // (c) Speak -> Hear round-trip: synthesize a sentence, then transcribe it.
-  await doctorCheck(checks, "speak→hear round-trip", async () => {
-    const audio = await pyai.audio.speech({ input: "The quick brown fox jumps over the lazy dog." });
-    const bytes = Buffer.from(audio).byteLength;
-    const blob = new Blob([audio], { type: "audio/wav" });
-    const tr = await pyai.audio.transcriptions.create({ file: blob, filename: "doctor.wav" });
-    const text = (tr.text ?? "").trim();
-    if (!text) throw new Error(`synthesized ${bytes} bytes but transcription came back empty`);
-    return `synth ${bytes} bytes → "${text.length > 60 ? `${text.slice(0, 60)}…` : text}"`;
-  });
-
-  for (const c of checks) {
-    out(`${c.status.padEnd(4)}  ${c.name}, ${c.detail}`);
-    if (c.hint) out(`        ↳ ${c.hint}`);
+  const sandbox = cmd === "auth sandbox";
+  const sandboxProfile = sandbox ? validateProfileName(value(flags, "profile") ?? process.env.PYAI_PROFILE ?? "sandbox") : undefined;
+  const config = await resolveConfig({ apiKey: value(flags, "api-key"), baseURL: value(flags, "base-url"), profile: sandboxProfile ?? value(flags, "profile"), allowMissingProfile: sandbox });
+  if (config.apiKey) secrets.add(config.apiKey);
+  const retries = number(flags, "retries", 2, 0, 5); if (!Number.isInteger(retries)) usage("--retries must be an integer");
+  const http = new CliHttp({ baseURL: config.baseURL, apiKey: config.apiKey, timeoutMs: number(flags, "timeout", 30, 0.001) * 1000, maxRetries: retries });
+  if (cmd === "auth logout") { if (!flags["dry-run"]) await removeProfile(config.profile); output({ profile: config.profile, removed: !flags["dry-run"] }, flags, `${flags["dry-run"] ? "Would remove" : "Removed"} saved profile ${config.profile}`); return; }
+  if (sandbox) {
+    if (preview(flags, config.baseURL, "POST", "/v1/sandbox/keys", {})) return;
+    const result = await http.json("POST", "/v1/sandbox/keys", { auth: false, json: {} });
+    if (!result || typeof result.api_key !== "string") throw new CliError("invalid_response", "Sandbox response did not contain an API key");
+    secrets.add(result.api_key); validateApiKey(result.api_key);
+    const profile = sandboxProfile!;
+    await saveProfile(profile, { api_key: result.api_key, base_url: config.baseURL });
+    const { api_key: _key, ...metadata } = result;
+    output({ ...metadata, profile, saved: true }, flags, `Sandbox ready. Saved credentials in profile ${profile}.`); return;
   }
-  const failed = checks.filter((c) => c.status === "FAIL");
-  if (failed.length === 0) {
-    out("\nDiagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.");
-  } else {
-    out(`\nDiagnosis: ${failed.length} check(s) failed, see the remediation hints above.`);
-    process.exit(1);
+  if (cmd === "smoke" || cmd === "doctor") {
+    if (flags["dry-run"]) { output({ dry_run: true, command: cmd, requests: ["GET /v1/models", "GET /v1/voices", "POST /v1/audio/speech", ...(cmd === "doctor" ? ["GET /v1/me", "POST /v1/audio/transcriptions"] : [])] }, flags); return; }
+    await diagnostics(http, cmd, flags); return;
   }
-}
-
-async function main(): Promise<void> {
-  const flags = parseArgs(process.argv.slice(2));
-  const cmd = (flags._ as string[])[0];
-  switch (cmd) {
-    case "doctor":
-      return cmdDoctor(flags);
-    case "smoke":
-      return cmdSmoke(flags);
-    case "models":
-      return cmdModels(flags);
-    case "voices":
-      return cmdVoices(flags);
-    case "speak":
-      return cmdSpeak(flags);
-    case "transcribe":
-      return cmdTranscribe(flags);
-    case "help":
-    case undefined:
-      out(USAGE);
-      return;
-    default:
-      fail(`unknown command: ${cmd}\n\n${USAGE}`);
+  if (cmd === "speak") {
+    if (flags.text === undefined && flags["text-file"] === undefined && !process.stdin.isTTY) flags["text-file"] = "-";
+    if (!!value(flags, "text") === !!value(flags, "text-file")) usage("Provide exactly one of --text or --text-file (use - for stdin)");
+    const text = value(flags, "text") ?? (await inputFile(required(flags, "text-file"))).toString("utf8");
+    if (!text.trim()) usage("Speech text is empty");
+    const format = value(flags, "format") ?? "wav";
+    if (!(SPEECH_FORMATS as readonly string[]).includes(format)) usage(`--format must be one of ${SPEECH_FORMATS.join(", ")}`);
+    const sampleRate = value(flags, "sample-rate") === undefined ? undefined : number(flags, "sample-rate", 24000, 8000, 48000);
+    if (sampleRate !== undefined && !(SPEECH_SAMPLE_RATES as readonly number[]).includes(sampleRate)) usage(`--sample-rate must be one of ${SPEECH_SAMPLE_RATES.join(", ")}`);
+    if (format.startsWith("g711_") && sampleRate !== undefined && sampleRate !== 8000) usage("G.711 audio requires --sample-rate 8000");
+    const payload = { input: text, model: value(flags, "model") ?? "pyai-speak", voice: value(flags, "voice"), response_format: format, sample_rate: sampleRate };
+    const path = value(flags, "out") ?? `pyai-speak.${format.startsWith("g711_") ? "raw" : format}`;
+    await checkOutput(path, flags);
+    if (preview(flags, config.baseURL, "POST", "/v1/audio/speech", payload)) return;
+    await writeAudio(await http.request("POST", "/v1/audio/speech", { json: payload }), path, flags); return;
+  }
+  if (cmd === "transcribe") {
+    if (flags["text-only"] && flags.json) usage("--text-only cannot be combined with --json");
+    if (!!value(flags, "file") === !!value(flags, "url")) usage("Provide exactly one of --file or --url");
+    const isJob = !!value(flags, "url");
+    if (flags["text-only"] && isJob && !flags.wait && !flags.poll) usage("--text-only with a URL requires --wait");
+    if (!isJob && (flags.diarize || flags.wait || flags.poll || flags["idempotency-key"])) usage("--diarize, --wait, --poll and --idempotency-key require --url (async jobs)");
+    const path = isJob ? "/v1/transcription/jobs" : "/v1/audio/transcriptions";
+    const body = isJob ? { audio_url: value(flags, "url"), diarize: flags.diarize === true, ...(value(flags, "language") ? { language: value(flags, "language") } : {}) } : await upload(flags, "file");
+    if (body instanceof FormData) { body.set("model", "pyai-hear"); if (value(flags, "language")) body.set("language", value(flags, "language")!); }
+    if (flags.wait || flags.poll) { number(flags, "wait-timeout", 120, 0.001); number(flags, "poll-interval", 2, 0.001, 60); }
+    if (preview(flags, config.baseURL, "POST", path, body)) return;
+    const result = await http.json("POST", path, { ...(body instanceof FormData ? { body } : { json: body }), headers: headers(flags) });
+    if (isJob && (flags.wait || flags.poll)) {
+      if (!result || typeof result.job_id !== "string") throw new CliError("invalid_response", "Job response is missing job_id");
+      const completed = await waitForJob(http, `${path}/${safeId(result.job_id)}`, flags, ["completed"], ["failed", "cancelled"]);
+      transcriptOutput(completed, flags, `${path}/${safeId(result.job_id)}`);
+    } else transcriptOutput(result, flags);
+    return;
+  }
+  if (cmd === "dub") {
+    const language = required(flags, "to");
+    const out = value(flags, "out") ?? "pyai-dub.wav";
+    await checkOutput(out, flags);
+    number(flags, "wait-timeout", 120, 0.001); number(flags, "poll-interval", 2, 0.001, 60);
+    const body = await dubForm(flags, language, value(flags, "from"));
+    if (flags["dry-run"]) {
+      output({ dry_run: true, command: "dub", method: "POST", url: `${config.baseURL}/v1/dub`, body: describeBody(body), headers: headers(flags), out, steps: ["submit", "wait for done", "download audio"], wait_timeout_seconds: number(flags, "wait-timeout", 120) }, flags); return;
+    }
+    const created = await http.json("POST", "/v1/dub", { body, headers: headers(flags) });
+    if (!created || typeof created.job_id !== "string" || !created.job_id) throw new CliError("invalid_response", "Dub response is missing job_id");
+    const path = `/v1/dub/jobs/${safeId(created.job_id)}`;
+    if (!flags.json) process.stderr.write(`Dub job ${redact(created.job_id)} submitted. Waiting for audio…\n`);
+    try {
+      await waitForJob(http, path, flags, ["done"], ["error"]);
+      await writeAudio(await http.request("GET", `${path}/audio`), out, flags, { job_id: created.job_id, status: "done" });
+    } catch (error) {
+      if (error instanceof CliError) throw new CliError(error.code, error.message, error.exitCode, { ...error.details, job_id: created.job_id, path });
+      throw new CliError("local_error", (error as Error).message, 2, { job_id: created.job_id, path });
+    }
+    return;
+  }
+  if (cmd === "clones create" || cmd === "dub create") {
+    let form: FormData;
+    if (cmd === "clones create") { const name = required(flags, "name"); form = await upload(flags, "file"); form.set("name", name); }
+    else form = await dubForm(flags, required(flags, "language"), value(flags, "source-language"));
+    const path = cmd === "clones create" ? "/v1/voice/clones" : "/v1/dub";
+    if (preview(flags, config.baseURL, "POST", path, form)) return;
+    output(await http.json("POST", path, { body: form, headers: headers(flags) }), flags); return;
+  }
+  if (cmd === "request") {
+    const method = args[0]!.toUpperCase(); if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(method)) usage("Unsupported HTTP method");
+    let path = args[1]!;
+    if (!/^\/(?!\/)/.test(path) || path.includes("\\") || /[\x00-\x20\x7f]/.test(path)) usage("Use a relative API path such as /v1/models");
+    const q = new URLSearchParams();
+    for (const item of (flags.query ?? []) as string[]) { const i = item.indexOf("="); if (i < 1) usage("--query requires name=value"); q.append(item.slice(0, i), item.slice(i + 1)); }
+    if (q.toString()) path += `${path.includes("?") ? "&" : "?"}${q}`;
+    http.validatePath(path);
+    const data = flags.data !== undefined ? await jsonInput(flags) : undefined;
+    if (data !== undefined && ["GET", "HEAD"].includes(method)) usage(`${method} does not accept --data`);
+    const out = value(flags, "out"); if (out) await checkOutput(out, flags);
+    if (preview(flags, config.baseURL, method, path, data)) return;
+    if (out) await writeAudio(await http.request(method, path, { json: data, headers: headers(flags) }), out, flags);
+    else output(await http.json(method, path, { json: data, headers: headers(flags) }), flags);
+    return;
   }
+  const simplePaths: Record<string, string> = { "auth status": "/v1/me", "models list": "/v1/models", "voices list": "/v1/voices", "voices get": `/v1/voices/${args[0] ? safeId(args[0]) : ""}`, schema: "/openapi.json" };
+  if (cmd in simplePaths) {
+    const path = withQuery(simplePaths[cmd]!, Object.fromEntries(["gender", "region", "language", "tier", "q", "source"].map(k => [k, value(flags, k)])));
+    if (preview(flags, config.baseURL, "GET", path)) return;
+    output(await http.json("GET", path, { auth: cmd !== "schema" }), flags, undefined, cmd !== "schema"); return;
+  }
+  const route = routes.find(r => r.command === cmd)!;
+  let path = route.path.replace("{id}", route.id ? safeId(args[0]!) : "");
+  if (value(flags, "limit") !== undefined) { const limit = number(flags, "limit", 20, 1, 100); if (!Number.isInteger(limit)) usage("--limit must be an integer"); }
+  path = withQuery(path, { limit: value(flags, "limit"), cursor: value(flags, "cursor") });
+  const data = route.body ? await jsonInput(flags, true) : undefined;
+  const out = route.binary ? required(flags, "out") : undefined;
+  if (out) await checkOutput(out, flags);
+  if (preview(flags, config.baseURL, route.method, path, data)) return;
+  if (route.wait) output(await waitForJob(http, path, flags, route.wait.success, route.wait.failure), flags);
+  else if (out) await writeAudio(await http.request(route.method, path, { json: data, headers: headers(flags) }), out, flags);
+  else output(await http.json(route.method, path, { json: data, headers: headers(flags) }), flags);
 }
 
-main().catch((err) => {
-  if (err instanceof PyAIError) {
-    fail(`API error ${err.status}${err.code ? ` (${err.code})` : ""}: ${err.message}`);
+for (const stream of [process.stdout, process.stderr]) stream.on("error", err => { if ((err as NodeJS.ErrnoException).code === "EPIPE") process.exit(0); throw err; });
+process.once("SIGINT", () => {
+  for (const path of pendingAudioFiles) { try { unlinkSync(path); } catch { /* Best effort cleanup on interruption. */ } }
+  process.stderr.write(jsonMode ? `${JSON.stringify({ error: { code: "interrupted", message: "Interrupted" } })}\n` : "pyai: interrupted\n");
+  process.exit(130);
+});
+if (process.env.PYAI_API_KEY) secrets.add(process.env.PYAI_API_KEY);
+// Register explicit keys before parsing so even invalid-command errors cannot echo them.
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i]!;
+  const key = a.startsWith("--api-key=") ? a.slice(10) : a === "--api-key" ? process.argv[i + 1] : undefined;
+  if (key) secrets.add(key);
+}
+main().catch(err => {
+  const e = err instanceof CliError ? err : err instanceof CliConfigError || err instanceof CliInitError ? new CliError(err.code, err.message, 2) : new CliError("local_error", (err as Error).message, 2);
+  const detail = { code: e.code, message: e.message, ...e.details };
+  if (jsonMode) process.stderr.write(`${JSON.stringify({ error: redact(detail) })}\n`);
+  else {
+    process.stderr.write(`pyai: ${redact(e.message)} (${redact(e.code)})\n`);
+    if (typeof e.details?.path === "string") process.stderr.write(`Reference: ${redact(e.details.path)}\n`);
+    if (typeof e.details?.job_id === "string") process.stderr.write(`Job ID: ${redact(e.details.job_id)}\n`);
   }
-  fail((err as Error).message);
+  process.exitCode = e.exitCode;
 });