tripo-cli 0.1.0

package/dist/knowledge/scenarios.js

@@ -0,0 +1,112 @@
+/**
+ * Scenario decision matrix: --for presets and the AI wizard both read this
+ * table. Changing production strategy means editing data here, not logic.
+ */
+import { MODEL_P1, MODEL_V31, RIG_MODEL_V25 } from './models.js';
+export const SCENARIOS = [
+    {
+        id: 'game-mobile',
+        label: { zh: '手游/低模', en: 'Mobile game / low-poly' },
+        description: { zh: '移动端游戏资产,面数预算严格,干净拓扑', en: 'Mobile game assets with strict face budgets and clean topology' },
+        model: MODEL_P1,
+        genParams: { texture: true, pbr: true, texture_quality: 'standard', face_limit: 15000 },
+        chain: [{ step: 'convert', args: { format: 'FBX', texture_size: 2048 } }],
+        deliverables: ['FBX', 'GLB'],
+        notes: {
+            zh: ['P1 原生低模,拓扑干净', '2K 贴图适配移动端', '需要骨骼时追加 --then rig'],
+            en: ['P1 native low-poly with clean topology', '2K textures for mobile budgets', 'append --then rig if you need a skeleton'],
+        },
+    },
+    {
+        id: 'game-pc',
+        label: { zh: '端游/主机', en: 'PC / console game' },
+        description: { zh: '高预算引擎资产,PBR 全开', en: 'High-budget engine assets with full PBR' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true, texture_quality: 'detailed' },
+        chain: [{ step: 'convert', args: { format: 'FBX' } }],
+        deliverables: ['FBX', 'GLTF'],
+        notes: {
+            zh: ['v3.1 高精度 + detailed 贴图', '需要 LOD 时追加 --then decimate:5000', '进 Blender/3dsMax 用 fbx_preset 对齐'],
+            en: ['v3.1 high fidelity + detailed textures', 'append --then decimate:5000 for LODs', 'use fbx_preset to match Blender/3dsMax'],
+        },
+    },
+    {
+        id: 'film',
+        label: { zh: '影视/离线渲染', en: 'Film / offline rendering' },
+        description: { zh: '细分友好四边面,规格拉满', en: 'Subdivision-friendly quads, maximum quality' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true, quad: true, geometry_quality: 'detailed', texture_quality: 'detailed' },
+        chain: [],
+        deliverables: ['FBX (quad)', 'USDZ/OBJ via convert'],
+        notes: {
+            zh: ['quad=true 输出 FBX(quad 进不了 GLB)', 'geometry detailed 加收 HD credit', '进 USD 管线追加 --then convert:usdz'],
+            en: ['quad=true outputs FBX (quads cannot be stored in GLB)', 'geometry detailed bills an extra HD credit', 'append --then convert:usdz for USD pipelines'],
+        },
+    },
+    {
+        id: 'print',
+        label: { zh: '3D 打印', en: '3D printing' },
+        description: { zh: '水密可打印几何,免贴图省积分', en: 'Watertight printable geometry, skipping textures saves credits' },
+        model: MODEL_V31,
+        genParams: { texture: false, pbr: false },
+        chain: [{ step: 'convert', args: { format: 'STL', flatten_bottom: true } }],
+        deliverables: ['STL', '3MF (colored)'],
+        notes: {
+            zh: ['白模生成,不花贴图积分', 'flatten_bottom 平底利于 FDM', '彩色打印改 --then convert:3mf,export_vertex_colors=true'],
+            en: ['bare geometry: no texture credits spent', 'flatten_bottom helps FDM adhesion', 'for color prints use --then convert:3mf,export_vertex_colors=true'],
+        },
+    },
+    {
+        id: 'ar-web',
+        label: { zh: 'AR/Web/电商', en: 'AR / Web / e-commerce' },
+        description: { zh: '移动端性能预算,glb+usdz 双交付', en: 'Mobile performance budgets with dual glb+usdz delivery' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true },
+        chain: [
+            { step: 'decimate', args: { face_limit: 20000 } },
+            { step: 'convert', args: { format: 'USDZ' } },
+        ],
+        deliverables: ['GLB', 'USDZ'],
+        notes: {
+            zh: ['v3.1 生成后减面到 2 万内', 'iOS QuickLook 需要 USDZ', 'decimate 默认 bake 烘焙贴图到低模'],
+            en: ['generate with v3.1, then decimate under 20k faces', 'iOS QuickLook requires USDZ', 'decimate bakes textures onto the low-poly by default'],
+        },
+    },
+    {
+        id: 'anim',
+        label: { zh: '角色动画', en: 'Character animation' },
+        description: { zh: '绑骨+动作重定向全链路', en: 'Full rig + retarget pipeline' },
+        model: MODEL_V31,
+        genParams: { texture: true, pbr: true },
+        chain: [
+            { step: 'rig-check', args: {} },
+            { step: 'rig', args: { model: RIG_MODEL_V25, spec: 'tripo', out_format: 'glb' } },
+            { step: 'retarget', args: { animations: ['preset:idle', 'preset:walk'] } },
+        ],
+        deliverables: ['GLB', 'FBX'],
+        notes: {
+            zh: ['先 rig-check 预检,不可绑骨即止损', '接 Mixamo/Unity Humanoid 用 rig:spec=mixamo', '提示词建议 T-pose 站姿,或先 text-to-image template=t_pose'],
+            en: ['rig-check first: stop early if not riggable', 'use rig:spec=mixamo for Mixamo/Unity Humanoid', 'prompt for a T-pose, or pre-generate with text-to-image template=t_pose'],
+        },
+    },
+    {
+        id: 'toy',
+        label: { zh: '风格化摆件', en: 'Stylized toy / desk piece' },
+        description: { zh: '低模可爱风或积木/体素风格化', en: 'Cute low-poly or brick/voxel stylization' },
+        model: MODEL_P1,
+        genParams: { texture: true, pbr: true, face_limit: 20000 },
+        chain: [],
+        deliverables: ['GLB', 'STL via convert'],
+        notes: {
+            zh: ['P1 出干净低模', '积木/体素风追加 --then stylize:lego 或 stylize:voxel', '要打印实物追加 --then convert:stl'],
+            en: ['P1 produces clean low-poly', 'append --then stylize:lego or stylize:voxel for brick/voxel looks', 'append --then convert:stl to print it'],
+        },
+    },
+];
+const byId = new Map(SCENARIOS.map((s) => [s.id, s]));
+export function getScenario(id) {
+    return byId.get(id);
+}
+export function scenarioIds() {
+    return SCENARIOS.map((s) => s.id);
+}

package/dist/pipeline/make.js

@@ -0,0 +1,233 @@
+/**
+ * The `make` orchestrator — one entry point that turns any input (text /
+ * image / multiview / model file / task ref) into finished artifacts,
+ * applying the dual-model rule, scenario presets, and the processing chain.
+ * Shared by `tripo make`, `tripo ai`, `tripo redo`, batch, and the MCP server.
+ */
+import { basename } from 'node:path';
+import { UsageError } from '../core/errors.js';
+import { log, warn } from '../core/output.js';
+import { buildImageToModel, buildMultiviewToModel, buildStepRequest, buildTextToModel, } from '../core/requests.js';
+import { precheckBalance, resolveInputValue, runTask } from '../core/task-service.js';
+import { t } from '../i18n.js';
+import { validateChain, ChainError } from '../knowledge/chains.js';
+import { chooseModel, detectLowPolyIntent } from '../knowledge/models.js';
+import { getScenario } from '../knowledge/scenarios.js';
+import { classifyInputs } from '../util/input-detect.js';
+import { runChain, assertSourceReady } from './runner.js';
+/** Build the full plan (no network calls except none): what model, what chain, why. */
+export async function planMake(client, options) {
+    const classified = classifyInputs(options.inputs);
+    const scenario = options.scenario ? getScenario(options.scenario) : undefined;
+    if (options.scenario && !scenario) {
+        throw new UsageError(`unknown scenario "${options.scenario}" (valid: game-mobile, game-pc, film, print, ar-web, anim, toy)`);
+    }
+    const userParams = options.params ?? {};
+    const genParams = { ...(scenario?.genParams ?? {}), ...userParams };
+    const chain = options.chain && options.chain.length > 0 ? options.chain : (scenario?.chain ?? []);
+    const warnings = [];
+    if (options.chain && options.chain.length > 0 && scenario && scenario.chain.length > 0) {
+        warnings.push(t({
+            zh: `--then 覆盖了 ${scenario.id} 场景默认加工链`,
+            en: `--then overrides the default ${scenario.id} processing chain`,
+        }));
+    }
+    switch (classified.kind) {
+        case 'text': {
+            const prompt = classified.values[0].value;
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+                lowPoly: detectLowPolyIntent(prompt),
+            });
+            const generation = buildTextToModel(prompt, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? prompt,
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'image':
+        case 'url-image': {
+            const raw = classified.values[0].value;
+            const { value } = await resolveInputValue(client, raw);
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+            });
+            const generation = buildImageToModel(value, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? basename(raw),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'multiview': {
+            const views = await assignViews(client, classified.values.map((v) => v.value));
+            const choice = chooseModel({
+                explicit: options.model ?? scenario?.model,
+                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+            });
+            const generation = buildMultiviewToModel(views, choice.model, genParams);
+            return {
+                generation,
+                chain,
+                model: choice.model,
+                modelReason: choice.reason,
+                name: options.name ?? basename(classified.values[0].value),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'model': {
+            const raw = classified.values[0].value;
+            const { value } = await resolveInputValue(client, raw);
+            const generation = buildStepRequest('import', value, {});
+            if (chain.length === 0) {
+                warnings.push(t({
+                    zh: '导入模型后没有加工步骤;用 --then 指定(如 --then texture,rig)',
+                    en: 'importing a model with no processing steps; add --then (e.g. --then texture,rig)',
+                }));
+            }
+            return {
+                generation,
+                chain,
+                name: options.name ?? basename(raw),
+                warnings: [...warnings, ...generation.warnings],
+            };
+        }
+        case 'task': {
+            const { value, sourceTaskType } = await resolveInputValue(client, classified.values[0].value);
+            if (chain.length === 0) {
+                throw new UsageError('a task reference needs processing steps: add --then (e.g. tripo make @last --then texture,convert:fbx)');
+            }
+            return {
+                sourceTaskId: value,
+                sourceType: sourceTaskType,
+                chain,
+                name: options.name ?? value.slice(0, 8),
+                warnings,
+            };
+        }
+    }
+}
+/** Execute a plan produced by planMake. */
+export async function executeMake(client, plan, options) {
+    for (const w of plan.warnings)
+        warn(w);
+    // Validate chain legality up front so an illegal plan spends zero credits.
+    if (plan.chain.length > 0) {
+        const upstream = plan.generation?.taskType ?? plan.sourceType;
+        if (upstream) {
+            try {
+                validateChain(plan.chain, upstream);
+            }
+            catch (error) {
+                if (error instanceof ChainError)
+                    throw new UsageError(error.message);
+                throw error;
+            }
+        }
+    }
+    await precheckBalance(client);
+    let sourceTaskId;
+    let sourceType;
+    let primary;
+    if (plan.generation) {
+        if (plan.model && plan.modelReason) {
+            log(t({ zh: `模型选择:${plan.model}(${plan.modelReason})`, en: `model: ${plan.model} (${plan.modelReason})` }));
+        }
+        primary = await runTask({
+            client,
+            request: plan.generation.request,
+            taskType: plan.generation.taskType,
+            name: plan.name,
+            outDir: options.outDir,
+            noWait: options.noWait,
+            noDownload: options.noDownload || plan.chain.length > 0,
+            timeoutMs: options.timeoutMs,
+            notify: options.notify && plan.chain.length === 0,
+            precheckBalance: false,
+        });
+        if (options.noWait)
+            return { primary, chainResults: [] };
+        sourceTaskId = primary.task_id;
+        sourceType = plan.generation.taskType;
+    }
+    else {
+        sourceTaskId = plan.sourceTaskId;
+        sourceType = plan.sourceType ?? (await assertSourceReady(client, sourceTaskId));
+        primary = { task_id: sourceTaskId, type: sourceType, status: 'success' };
+    }
+    if (plan.chain.length === 0) {
+        return { primary, chainResults: [] };
+    }
+    const { results, stoppedEarly } = await runChain({
+        client,
+        chain: plan.chain,
+        sourceTaskId,
+        sourceType,
+        namePrefix: plan.name,
+        outDir: options.outDir,
+        notify: false,
+        timeoutMs: options.timeoutMs,
+    });
+    // If the chain stopped early (not riggable) and nothing was downloaded yet,
+    // fetch the source artifacts so the user still gets their model.
+    if (stoppedEarly && plan.generation && !options.noDownload) {
+        const detail = await client.getTask(sourceTaskId);
+        const { downloadArtifacts, defaultOutputDir } = await import('../core/download.js');
+        const { slugify } = await import('../config/history.js');
+        const dir = defaultOutputDir(options.outDir ?? process.cwd(), slugify(plan.name), sourceTaskId);
+        const artifacts = await downloadArtifacts(detail, dir);
+        primary.output_dir = artifacts.outputDir;
+        primary.model_file = artifacts.modelFile;
+        primary.preview = artifacts.preview;
+    }
+    return { primary, chainResults: results, stoppedEarly };
+}
+/**
+ * Map 2–4 images to views. Filename hints (front/back/left/right, 前/后/左/右)
+ * win; remaining slots fill positionally in [front, left, back, right] order.
+ */
+export async function assignViews(client, files) {
+    if (files.length < 2 || files.length > 4) {
+        throw new UsageError(`multiview needs 2–4 images (got ${files.length})`);
+    }
+    const hints = {
+        front: /front|正面|前/i,
+        back: /back|背面|后/i,
+        left: /left|左/i,
+        right: /right|右/i,
+    };
+    const views = {};
+    const unassigned = [];
+    for (const file of files) {
+        const name = basename(file);
+        const hit = Object.entries(hints).find(([view, re]) => !views[view] && re.test(name));
+        if (hit)
+            views[hit[0]] = file;
+        else
+            unassigned.push(file);
+    }
+    const order = ['front', 'left', 'back', 'right'];
+    for (const file of unassigned) {
+        const slot = order.find((v) => !views[v]);
+        if (!slot)
+            throw new UsageError('too many images for 4 view slots');
+        views[slot] = file;
+    }
+    if (!views.front) {
+        throw new UsageError('multiview requires a front view — name one file with "front" or pass it first');
+    }
+    const resolved = {};
+    for (const [view, file] of Object.entries(views)) {
+        resolved[view] = (await resolveInputValue(client, file)).value;
+    }
+    return resolved;
+}

package/dist/pipeline/runner.js

@@ -0,0 +1,73 @@
+/**
+ * Chain runner: execute a validated sequence of processing steps, feeding
+ * each step the previous task id. rig-check gates the rig step (stop early
+ * when the model is not riggable, and adopt the recommended rig_type).
+ */
+import { UsageError } from '../core/errors.js';
+import { log, warn } from '../core/output.js';
+import { buildStepRequest } from '../core/requests.js';
+import { runTask } from '../core/task-service.js';
+import { t } from '../i18n.js';
+import { getStep, validateChain } from '../knowledge/chains.js';
+export async function runChain(options) {
+    const { client, chain } = options;
+    validateChain(chain, options.sourceType);
+    const results = [];
+    let currentTaskId = options.sourceTaskId;
+    let rigTypeRecommendation;
+    for (let i = 0; i < chain.length; i++) {
+        const spec = chain[i];
+        const args = { ...spec.args };
+        if (spec.step === 'rig' && rigTypeRecommendation && args.rig_type === undefined) {
+            args.rig_type = rigTypeRecommendation;
+            log(t({ zh: `采用 rig-check 推荐体型:${rigTypeRecommendation}`, en: `using rig-check recommendation: ${rigTypeRecommendation}` }));
+        }
+        const built = buildStepRequest(spec.step, currentTaskId, args);
+        for (const w of built.warnings)
+            warn(w);
+        const result = await runTask({
+            client,
+            request: built.request,
+            taskType: built.taskType,
+            name: `${options.namePrefix}-${spec.step}`,
+            outDir: options.outDir,
+            notify: false,
+            timeoutMs: options.timeoutMs,
+            // Intermediate steps skip download; final step downloads.
+            noDownload: i < chain.length - 1 && spec.step !== 'rig-check',
+            precheckBalance: false, // checked once by the caller
+        });
+        results.push(result);
+        if (spec.step === 'rig-check') {
+            const verdict = await client.getTask(result.task_id);
+            const output = verdict.output ?? {};
+            const riggable = output.riggable;
+            rigTypeRecommendation = typeof output.rig_type === 'string' ? output.rig_type : undefined;
+            if (riggable === false) {
+                const message = t({
+                    zh: 'rig-check 判定该模型不可绑骨,动画链止损停止(后续步骤未执行,未扣积分)',
+                    en: 'rig-check says this model is not riggable; stopping the chain early (no further credits spent)',
+                });
+                warn(message);
+                return { results, stoppedEarly: message };
+            }
+        }
+        // Gate steps (passthrough) inspect the model; the chain continues from
+        // the same upstream task.
+        if (!getStep(spec.step)?.passthrough) {
+            currentTaskId = result.task_id;
+        }
+    }
+    return { results };
+}
+/** Ensure a source task exists + succeeded before chaining onto it. */
+export async function assertSourceReady(client, taskId) {
+    const task = await client.getTask(taskId);
+    if (task.status !== 'success') {
+        throw new UsageError(`task ${taskId} is ${task.status}; processing steps need a successful upstream task` +
+            (task.status === 'running' || task.status === 'queued'
+                ? ` (wait with "tripo task watch ${taskId}")`
+                : ''));
+    }
+    return task.type;
+}

package/dist/pipeline/stdin.js

@@ -0,0 +1,40 @@
+/**
+ * NDJSON pipe support: downstream commands read the upstream task result from
+ * stdin, enabling `tripo make cat.png | tripo model texture | tripo anim rig`.
+ */
+/** Read piped NDJSON/JSON from stdin; returns undefined on a TTY. */
+export async function readPipedTask() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const raw = await readAll(process.stdin);
+    return parsePipedText(raw);
+}
+/** Parse piped text: JSON object, NDJSON (last task line wins), or a bare task id. */
+export function parsePipedText(raw) {
+    const text = raw.trim();
+    if (!text)
+        return undefined;
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const obj = JSON.parse(lines[i]);
+            if (typeof obj.task_id === 'string') {
+                return { task_id: obj.task_id, type: typeof obj.type === 'string' ? obj.type : undefined };
+            }
+        }
+        catch { }
+    }
+    const last = lines[lines.length - 1];
+    if (/^(task_[A-Za-z0-9_-]+|[0-9a-f-]{36})$/i.test(last))
+        return { task_id: last };
+    return undefined;
+}
+function readAll(stream) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        stream.setEncoding('utf8');
+        stream.on('data', (chunk) => (data += chunk));
+        stream.on('end', () => resolve(data));
+        stream.on('error', reject);
+    });
+}

package/dist/program.js

@@ -0,0 +1,147 @@
+/** Command tree assembly + global flags + the error → exit-code boundary. */
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { registerAccountCommands } from './commands/account.js';
+import { registerAiCommand } from './commands/ai.js';
+import { registerAuthCommands } from './commands/login.js';
+import { registerBatchCommand } from './commands/batch.js';
+import { registerCompletionCommand } from './commands/completion.js';
+import { registerConfigCommands } from './commands/config-cmd.js';
+import { registerDoctorCommand } from './commands/doctor.js';
+import { registerDocsCommand } from './commands/docs.js';
+import { registerGenerateCommands } from './commands/generate.js';
+import { registerHomeAction } from './commands/home.js';
+import { registerMakeCommand } from './commands/make.js';
+import { registerMcpCommand } from './commands/mcp.js';
+import { registerProcessCommands } from './commands/process-groups.js';
+import { registerTaskCommands } from './commands/task.js';
+import { registerTopupCommand } from './commands/topup.js';
+import { registerViewCommands } from './commands/view.js';
+import { loadConfig } from './config/config.js';
+import { RefError } from './config/history.js';
+import { ApiError, CliError, UsageError } from './core/errors.js';
+import { configureOutput, errorLine, isJsonMode } from './core/output.js';
+import { setLocale, t } from './i18n.js';
+import { EXIT } from './knowledge/error-catalog.js';
+import { cliVersion } from './version.js';
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('tripo')
+        .description(t({
+        zh: 'Tripo 3D 智能 CLI — 一句话/一张图,直出可进引擎的 3D 资产\n高频: make(生成) ai(专家规划) view(预览) topup(充值)',
+        en: 'Tripo 3D intelligent CLI — turn a sentence or an image into engine-ready 3D assets\ntop commands: make · ai · view · topup',
+    }))
+        .version(cliVersion(), '-v, --version')
+        .option('--json', 'machine-readable output on stdout (auto-enabled when piped)')
+        .option('--yes', 'skip confirmations (auto-enabled when headless)')
+        .option('--quiet', 'suppress progress logs on stderr')
+        .option('--no-open', 'never auto-open the browser/viewer')
+        .enablePositionalOptions()
+        .showSuggestionAfterError(true);
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        configureOutput({
+            json: resolveGlobalFlag(actionCommand, 'json', false),
+            yes: resolveGlobalFlag(actionCommand, 'yes', false),
+            quiet: resolveGlobalFlag(actionCommand, 'quiet', false),
+            noOpen: !resolveGlobalFlag(actionCommand, 'open', true),
+        });
+        const lang = loadConfig().language;
+        if (lang)
+            setLocale(lang);
+    });
+    registerMakeCommand(program);
+    registerAiCommand(program);
+    registerViewCommands(program);
+    registerAuthCommands(program);
+    registerTopupCommand(program);
+    registerAccountCommands(program);
+    registerGenerateCommands(program);
+    registerProcessCommands(program);
+    registerTaskCommands(program);
+    registerBatchCommand(program);
+    registerConfigCommands(program);
+    registerDoctorCommand(program);
+    registerDocsCommand(program);
+    registerCompletionCommand(program);
+    registerMcpCommand(program);
+    registerHomeAction(program);
+    attachGlobalFlags(program);
+    return program;
+}
+/**
+ * The 4 global flags live on every leaf command so `tripo balance --json`
+ * works the way people type it (prefix `tripo --json balance` works too).
+ */
+function attachGlobalFlags(cmd) {
+    for (const sub of cmd.commands)
+        attachGlobalFlags(sub);
+    if (cmd.commands.length > 0)
+        return;
+    const has = (long) => cmd.options.some((o) => o.long === long);
+    if (!has('--json'))
+        cmd.option('--json', 'machine-readable output on stdout');
+    if (!has('--yes'))
+        cmd.option('--yes', 'skip confirmations');
+    if (!has('--quiet'))
+        cmd.option('--quiet', 'suppress progress logs on stderr');
+    if (!has('--no-open'))
+        cmd.option('--no-open', 'never auto-open the browser/viewer');
+}
+/**
+ * Resolve a flag along the command chain, innermost explicit value first.
+ * (optsWithGlobals can't do this: a leaf's *default* would shadow an explicit
+ * `tripo --no-open <cmd>` on the root.)
+ */
+function resolveGlobalFlag(cmd, key, def) {
+    for (let c = cmd; c; c = c.parent) {
+        const source = c.getOptionValueSource(key);
+        if (source !== undefined && source !== 'default')
+            return Boolean(c.getOptionValue(key));
+    }
+    return def;
+}
+/** Run the CLI; converts errors into the stable exit-code contract. */
+export async function runCli(argv) {
+    const program = buildProgram();
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (err) {
+        handleError(err);
+    }
+}
+export function handleError(err) {
+    // History reference misses (@last with empty history etc.) are usage errors.
+    if (err instanceof RefError)
+        err = new UsageError(err.message);
+    if (err instanceof CliError) {
+        if (isJsonMode()) {
+            process.stdout.write(JSON.stringify({
+                error: err.message,
+                exit_code: err.exitCode,
+                ...(err instanceof ApiError
+                    ? { api_code: err.apiCode, request_id: err.requestId, http_status: err.httpStatus }
+                    : {}),
+                ...(err.suggestion ? { suggestion: err.suggestion } : {}),
+            }) + '\n');
+        }
+        errorLine(err.message);
+        if (err.suggestion)
+            process.stderr.write(pc.dim(`  → ${err.suggestion}\n`));
+        if (err instanceof ApiError && err.requestId) {
+            process.stderr.write(pc.dim(`  request_id: ${err.requestId}\n`));
+        }
+        process.exit(err.exitCode);
+    }
+    // commander already printed its own message for help/version pseudo-errors
+    if (typeof err === 'object' && err !== null && 'code' in err) {
+        const code = err.code ?? '';
+        if (code.startsWith('commander.')) {
+            process.exit(code === 'commander.help' || code === 'commander.version' || code === 'commander.helpDisplayed' ? 0 : EXIT.USAGE);
+        }
+    }
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    errorLine(message);
+    process.exit(EXIT.FATAL);
+}