@pyai/sdk 0.3.1 → 0.5.0

package/dist/cli.js

@@ -1,320 +1,724 @@
 #!/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 { writeFile } from "node:fs/promises";
-import PyAI, { PyAIError } from "./index.js";
-function parseArgs(argv) {
-    const flags = { _: [] };
+import "./cli-runtime.js";
+/** 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.js";
+import { browserLogin } from "./cli-web-auth.js";
+import { CliConfigError, resolveConfig, saveProfile, removeProfile, useProfile, listProfiles, validateApiKey, validateProfileName } from "./cli-config.js";
+import { routes } from "./cli-routes.js";
+import { aliases, shortFlags, recipes } from "./cli-dx.js";
+import { CLI_TEMPLATES, scaffoldProject, CliInitError } from "./cli-init.js";
+import { SPEECH_FORMATS, SPEECH_SAMPLE_RATES } from "./index.js";
+const globals = {
+    "api-key": "string", "base-url": "string", profile: "string", json: "boolean",
+    timeout: "string", retries: "string", "dry-run": "boolean", help: "boolean", version: "boolean",
+};
+const bodyFlags = { data: "string", "idempotency-key": "string" };
+const outputFlags = { out: "string", force: "boolean" };
+const waitFlags = { "wait-timeout": "string", "poll-interval": "string" };
+const commands = [
+    { 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: 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", cursor: "string" } : {}),
+        } })),
+];
+function usage(message) { throw new CliError("invalid_arguments", message, 2); }
+function value(flags, name) { return typeof flags[name] === "string" ? flags[name] : undefined; }
+function required(flags, name) { const v = value(flags, name); if (!v)
+    usage(`--${name} is required`); return v; }
+function number(flags, name, fallback, min = 0, max = 86400) {
+    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 parse(argv) {
+    const known = Object.assign(Object.create(null), globals);
+    for (const c of commands)
+        Object.assign(known, c.flags);
+    const flags = Object.create(null);
+    const words = [];
     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] ?? []);
+            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._.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, key) {
-    const v = flags[key];
-    return typeof v === "string" ? v : undefined;
+const secrets = new Set();
+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, redactFields = true) {
+    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 output(data, flags, human, redactFields = true) {
+    process.stdout.write(flags.json || !human ? `${JSON.stringify(redact(data, redactFields), null, flags.json ? 0 : 2)}\n` : `${redact(human)}\n`);
 }
-function client(flags) {
-    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 transcriptOutput(data, flags, path) {
+    if (!flags["text-only"]) {
+        output(data, flags);
+        return;
+    }
+    const result = data;
+    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) {
-    process.stdout.write(`${msg}\n`);
+async function stdin() {
+    if (process.stdin.isTTY)
+        usage("Pipe input through stdin, or supply a file path");
+    const chunks = [];
+    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) {
-    process.stderr.write(`pyai: ${msg}\n`);
-    process.exit(1);
+async function inputFile(path) { return path === "-" ? stdin() : readFile(path); }
+async function jsonInput(flags, objectOnly = false) {
+    const raw = required(flags, "data");
+    const text = raw.startsWith("@") ? (await inputFile(raw.slice(1))).toString("utf8") : raw;
+    let parsed;
+    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;
+}
+function headers(flags) { const key = value(flags, "idempotency-key"); return key ? { "Idempotency-Key": key } : {}; }
+function safeId(id) { if (!id || id === "." || id === ".." || /[\x00-\x1f\x7f]/.test(id))
+    usage("Invalid resource id"); return encodeURIComponent(id); }
+function withQuery(path, fields) {
+    const q = new URLSearchParams(Object.entries(fields).filter((kv) => kv[1] !== undefined));
+    return q.toString() ? `${path}${path.includes("?") ? "&" : "?"}${q}` : path;
+}
+function describeBody(body) {
+    if (!(body instanceof FormData))
+        return body;
+    const fields = {};
+    body.forEach((v, k) => { fields[k] = typeof v === "string" ? v : { filename: v.name, bytes: v.size, type: v.type }; });
+    return fields;
 }
-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) {
-    const pyai = client(flags);
-    const res = await pyai.models.list();
-    out(JSON.stringify(res, null, 2));
+function preview(flags, baseURL, method, path, body) {
+    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 cmdVoices(flags) {
-    const pyai = client(flags);
-    const res = await pyai.voices.list({ gender: flag(flags, "gender"), region: flag(flags, "region") });
-    out(JSON.stringify(res, null, 2));
+async function upload(flags, field) {
+    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 cmdSpeak(flags) {
-    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}`);
+async function dubForm(flags, language, sourceLanguage) {
+    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));
+        }
+    return form;
 }
-async function cmdTranscribe(flags) {
-    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)
+async function checkOutput(path, flags) {
+    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;
-    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));
+    try {
+        await lstat(path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
             return;
-        }
+        throw e;
     }
-    out(`job ${job.job_id} still running after polling; check later.`);
+    usage(`Output already exists: ${path}; choose another path or pass --force`);
 }
-// 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) {
-    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
+const pendingAudioFiles = new Set();
+async function writeAudio(response, path, flags, metadata = {}) {
+    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);
+    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}`);
 }
-/** 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(fn, attempts = 4, baseMs = 800) {
-    let lastErr;
-    for (let i = 0; i < attempts; i++) {
+async function waitForJob(http, path, flags, success, failure) {
+    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 {
-            return await fn();
+            job = await http.json("GET", path, { timeoutMs: Math.min(remaining, requestTimeout) });
         }
-        catch (err) {
-            lastErr = err;
-            if (!isTransient(err) || i === attempts - 1)
-                throw err;
-            await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+        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) {
-    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);
+async function diagnostics(http, cmd, flags) {
     const checks = [];
-    const run = async (name, fn) => {
+    const tolerate = cmd === "smoke" && (flags["tolerate-upstream"] || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1");
+    const check = async (name, fn) => {
         try {
-            checks.push({ name, status: "PASS", detail: await withRetry(fn, retryAttempts, retryBaseMs) });
+            checks.push({ name, status: "PASS", detail: await fn() });
         }
         catch (err) {
-            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : err.message;
-            const status = isTransient(err) && tolerateUpstream ? "WARN" : "FAIL";
-            checks.push({ name, status, detail });
+            const e = err;
+            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.`);
-    }
+    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 {
-        out("\nSome checks failed (see above).");
-        process.exit(1);
+        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) {
-    if (!(err instanceof PyAIError))
-        return err?.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() {
+    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;
     }
-    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;
+    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;
     }
-}
-async function doctorCheck(checks, name, fn) {
-    try {
-        checks.push({ name, status: "PASS", detail: await fn() });
+    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) => !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;
     }
-    catch (err) {
-        const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : err.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) {
-    const pyai = client(flags);
-    const checks = [];
-    // (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" });
+    if (cmd === "init") {
+        const result = await scaffoldProject({ directory: args[0], template: value(flags, "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;
         }
-        else {
-            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""}`.trim() : err.message;
-            checks.push({ name: "key (/v1/me)", status: "FAIL", detail, hint: remediation(err) });
+        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;
+    }
+    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;
+    }
+    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;
     }
-    // (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}`);
+    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.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.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;
     }
-    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.");
+    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;
     }
-    else {
-        out(`\nDiagnosis: ${failed.length} check(s) failed, see the remediation hints above.`);
-        process.exit(1);
+    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.message, 2, { job_id: created.job_id, path });
+        }
+        return;
     }
-}
-async function main() {
-    const flags = parseArgs(process.argv.slice(2));
-    const cmd = flags._[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);
+    if (cmd === "clones create" || cmd === "dub create") {
+        let form;
+        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;
-        default:
-            fail(`unknown command: ${cmd}\n\n${USAGE}`);
+        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 ?? [])) {
+            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 = { "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.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.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.message);
+    process.exitCode = e.exitCode;
 });