badgr-cli 1.0.47 → 1.1.0

package/src/commands/batch.js

@@ -13,16 +13,18 @@
  * eval) — a thin wrapper over the same /v1/run + monitorBatchJob primitives
  * `badgr train`/`transcribe`/`embed` already use, not a new execution path.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync, statSync, readdirSync } from 'fs';
 import { join, resolve } from 'path';
 import os from 'os';
 
 import { requireApiKey, CONFIG_DIR } from '../config.js';
 import { parseWorkloadYaml } from '../workloadSpec.js';
-import { addReceipt, updateReceipt, generateReceiptId, loadStore } from '../store.js';
+import { addReceipt, updateReceipt, generateReceiptId, loadStore, selectedComputeFromDeployment } from '../store.js';
 import { normalizeTier, callWithFallback } from '../fallback.js';
 import { monitorBatchJob, fmtRuntime } from '../batch.js';
+import { runFanOut, DEFAULT_CONCURRENCY } from '../fanout.js';
 import { uploadBlob } from '../api.js';
+import { downloadAndExtractArtifact } from '../artifactDownload.js';
 import { logsCommand } from './logs.js';
 
 // Server-side watchdog / batch.js reason strings, mapped to the vocabulary
@@ -61,10 +63,21 @@ async function apiRequest(config, path, opts = {}) {
 // inputs archive (tar.gz, member paths = container path minus leading '/')
 // ---------------------------------------------------------------------------
 
+let _archiveTmpFileCounter = 0;
+
+// Date.now() alone collides when --fan-out builds multiple archives
+// concurrently (millisecond resolution, sub-millisecond call spacing) — a
+// monotonic counter makes every call's tmp path unique regardless of
+// timing. Exported as a pure function so the uniqueness guarantee is
+// directly unit-testable without exercising the real filesystem/archiver.
+export function nextArchiveTmpFile() {
+  return join(os.tmpdir(), `badgr-batch-inputs-${Date.now()}-${++_archiveTmpFileCounter}.tar.gz`);
+}
+
 async function _buildInputsArchive(inputs, chalk) {
   const { default: archiver } = await import('archiver');
   const { createWriteStream } = await import('fs');
-  const tmpFile = join(os.tmpdir(), `badgr-batch-inputs-${Date.now()}.tar.gz`);
+  const tmpFile = nextArchiveTmpFile();
 
   await new Promise((res, rej) => {
     const output = createWriteStream(tmpFile);
@@ -137,29 +150,17 @@ async function _fetchArtifactMetadata(config, runId) {
 }
 
 async function downloadAndExtractArtifacts(config, runId) {
-  const meta = await _fetchArtifactMetadata(config, runId);
+  await _fetchArtifactMetadata(config, runId); // 404/410 raise their own clear messages before we even try downloading
   const destDir = artifactsDir(runId);
-  mkdirSync(destDir, { recursive: true });
-
-  const res = await fetch(meta.download_url, {
-    headers: { Authorization: `Bearer ${config.apiKey}` },
-  });
-  if (!res.ok) {
+  try {
+    await downloadAndExtractArtifact(config, runId, destDir);
+  } catch (err) {
     throw new Error(
-      `Artifact download failed for run ${runId}: ${res.status} ${res.statusText}. ` +
+      `Artifact download failed for run ${runId}: ${err.httpStatus ?? ''} ${err.statusText ?? err.message}. ` +
       `The upload succeeded (metadata exists) but the file itself couldn't be fetched — retry, ` +
       `or check backend storage (BADGR_STORAGE_DIR) if this persists.`,
     );
   }
-  const buf = Buffer.from(await res.arrayBuffer());
-  const tmpFile = join(os.tmpdir(), `badgr-batch-artifacts-${runId}.tar.gz`);
-  writeFileSync(tmpFile, buf);
-  try {
-    const tar = await import('tar');
-    await tar.x({ file: tmpFile, cwd: destDir });
-  } finally {
-    unlinkSync(tmpFile);
-  }
   return destDir;
 }
 
@@ -181,6 +182,191 @@ export function readMetricFile(destDir, metricFilePath) {
 // badgr batch run <workload.yml>
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// badgr batch run <workload.yml> --fan-out <dir>
+//
+// "Run one program across many inputs" — the single non-trivial pattern
+// that covers batch inference, rendering frames, Monte Carlo sweeps, robotics
+// scenarios, and dozens of other superficially different verticals. One
+// deployment per file in <dir>, run in parallel, rolled up into one summary.
+// Shares its submit/monitor/summarize loop with `badgr sbatch --array` via
+// ../fanout.js — same "N independent tasks" shape, two entry points.
+// ---------------------------------------------------------------------------
+
+function listFanOutFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(e => e.isFile())
+    .map(e => e.name)
+    .sort();
+}
+
+async function runFanOutSubcommand(config, spec, flags, chalk, yamlPath) {
+  if (spec.inputs.length !== 1) {
+    console.error(chalk.red(
+      `\n  ✗ --fan-out requires workload.yml to declare exactly one inputs: entry ` +
+      `(the file that varies per task) — found ${spec.inputs.length}.\n`,
+    ));
+    process.exitCode = 1;
+    return;
+  }
+  const fanOutDir = resolve(flags.fanOut);
+  if (!existsSync(fanOutDir) || !statSync(fanOutDir).isDirectory()) {
+    console.error(chalk.red(`\n  ✗ --fan-out path is not a directory: ${fanOutDir}\n`));
+    process.exitCode = 1;
+    return;
+  }
+  if (flags.maxConcurrency != null && (!Number.isInteger(flags.maxConcurrency) || flags.maxConcurrency < 1)) {
+    console.error(chalk.red(`\n  ✗ --max-concurrency must be a positive integer, got: ${flags.maxConcurrency}\n`));
+    process.exitCode = 1;
+    return;
+  }
+  let files = listFanOutFiles(fanOutDir);
+  if (files.length === 0) {
+    console.error(chalk.red(`\n  ✗ --fan-out directory has no files: ${fanOutDir}\n`));
+    process.exitCode = 1;
+    return;
+  }
+  if (flags.only?.length) {
+    const onlySet = new Set(flags.only);
+    const missing = flags.only.filter(f => !files.includes(f));
+    if (missing.length) {
+      console.error(chalk.red(`\n  ✗ --only names file(s) not found in ${fanOutDir}: ${missing.join(', ')}\n`));
+      process.exitCode = 1;
+      return;
+    }
+    files = files.filter(f => onlySet.has(f));
+  }
+
+  const [{ containerPath }] = spec.inputs;
+  const effectiveTier = normalizeTier(flags.tier);
+  const concurrency = flags.maxConcurrency ?? DEFAULT_CONCURRENCY;
+
+  console.log(chalk.bold(`\n📦 Batch fan-out: ${spec.name}\n`));
+  console.log(`  ${chalk.bold('Image:')}        ${spec.image}`);
+  console.log(`  ${chalk.bold('Command:')}      ${spec.command.join(' ')}`);
+  console.log(`  ${chalk.bold('Inputs dir:')}   ${fanOutDir} (${files.length} task(s), max ${Math.min(concurrency, files.length)} concurrent)`);
+  console.log(`  ${chalk.bold('Max cost:')}     $${spec.maxCost.toFixed(2)} per task`);
+  console.log(`  ${chalk.bold('Max runtime:')}  ${spec.maxRuntimeMinutes}min per task`);
+  console.log();
+
+  if (flags.dryRun) {
+    console.log(chalk.bold(`⚡ Dry run — no GPU will be provisioned (${files.length} task(s) would be submitted)\n`));
+    return;
+  }
+
+  const { results, allSucceeded, submittedCount, failedSubmitCount } = await runFanOut({
+    tasks: files,
+    concurrency,
+    onSubmitError: (file, err) => {
+      if (err.isPaymentRequired) console.error(chalk.yellow(err.message));
+      else console.error(chalk.red(`  ✗ ${file} failed to submit: ${err.message}`));
+    },
+    submitTask: async (file) => {
+      process.stdout.write(chalk.dim(`  Submitting ${file}...\n`));
+      const localPath = join(fanOutDir, file);
+      const inputsArchiveUrl = await _uploadInputsArchive(config, [{ localPath, containerPath }], chalk);
+
+      const envObj = { ...spec.env, BADGR_INPUTS_ARCHIVE_URL: inputsArchiveUrl, BADGR_FANOUT_INPUT: file };
+      if (spec.outputs.length > 0) envObj.BADGR_OUTPUT_PATHS_JSON = JSON.stringify(spec.outputs);
+
+      const body = {
+        image: spec.image,
+        command: spec.command,
+        custom_image: true,
+        gpu: flags.gpu ? flags.gpu.toUpperCase().replace(/-/g, '_') : 'AUTO',
+        gpu_count: 1,
+        ...(flags.region ? { region: flags.region.toUpperCase() } : {}),
+        tier: effectiveTier,
+        env: envObj,
+        name: `${spec.name}-${file.replace(/[^\w.-]/g, '_')}`,
+        max_cost_usd: spec.maxCost,
+        max_runtime_seconds: spec.maxRuntimeMinutes * 60,
+      };
+      const dep = await callWithFallback(
+        '/run',
+        { apiKey: config.apiKey, baseUrl: config.baseUrl },
+        () => body,
+        effectiveTier,
+        chalk,
+        { thing: `fan-out task (${file})`, cmd: 'badgr batch run --fan-out' },
+      );
+      const rcptId = dep.receipt_id || generateReceiptId();
+      addReceipt({
+        receiptId: rcptId,
+        action: 'badgr batch run --fan-out',
+        deploymentId: dep.deployment_id,
+        workloadName: body.name,
+        workloadImage: spec.image,
+        outputsDeclared: spec.outputs,
+        gpu: dep.gpu_type,
+        providerRoute: dep.provider ?? null,
+        tier: dep.tier ?? null,
+        maxCost: spec.maxCost,
+        maxRuntime: spec.maxRuntimeMinutes,
+        status: dep.status,
+        createdAt: new Date().toISOString(),
+        fanOutInput: file,
+        workloadShape: 'fan-out',
+        computeSelected: selectedComputeFromDeployment(dep),
+      });
+      console.log(`  ${chalk.bold('Run ID:')} ${chalk.cyan(dep.deployment_id)}  ${chalk.dim(file)}`);
+      return { deploymentId: dep.deployment_id, receiptId: rcptId, ratePerHour: dep.cost_per_hour || 0 };
+    },
+    monitorTask: async ({ deploymentId, receiptId, ratePerHour }) => {
+      const result = await monitorBatchJob(config, deploymentId, receiptId, {
+        chalk,
+        maxRuntimeMs: spec.maxRuntimeMinutes * 60 * 1000,
+        maxCost: spec.maxCost,
+        ratePerHour,
+      });
+      let dep2 = null;
+      try {
+        dep2 = await apiRequest(config, `/deployments/${deploymentId}`);
+      } catch { /* best-effort */ }
+      updateReceipt(receiptId, {
+        status: dep2?.status ?? result.status,
+        failureReason: dep2?.failure_reason ?? null,
+        teardownOk: dep2?.teardown_ok ?? null,
+        runtimeSeconds: dep2?.runtime_seconds ?? Math.round(result.runtimeMs / 1000),
+        finalCost: dep2?.accrued_cost_usd ?? (ratePerHour * (result.runtimeMs / 3_600_000)),
+      });
+      const status = dep2?.status ?? result.status;
+      return { status, succeeded: ['succeeded', 'completed'].includes(status), runtimeMs: result.runtimeMs };
+    },
+  });
+
+  if (submittedCount === 0) {
+    console.error(chalk.red('\n  ✗ No fan-out tasks were submitted\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.bold(`\n📦 Fan-out summary: ${spec.name}\n`));
+  for (const r of results) {
+    if (r.error) {
+      console.log(`  ${chalk.red('✗')} ${r.task}  ${chalk.dim('never submitted')}`);
+      continue;
+    }
+    const icon = r.succeeded ? chalk.green('✓') : chalk.red('✗');
+    console.log(`  ${icon} ${r.task}  ${r.deploymentId}  ${r.status}  ${fmtRuntime(r.runtimeMs)}`);
+  }
+  if (failedSubmitCount) console.log(chalk.red(`  ${failedSubmitCount} task(s) never submitted`));
+
+  console.log();
+  if (allSucceeded) {
+    console.log(chalk.green(`  ✓ Fan-out complete (${files.length}/${files.length} task(s) succeeded)\n`));
+  } else {
+    const okCount = results.filter(r => r.succeeded).length;
+    const failedFiles = results.filter(r => r.error || !r.succeeded).map(r => r.task);
+    console.error(chalk.red(`  ✗ Fan-out incomplete (${okCount}/${files.length} task(s) succeeded)\n`));
+    if (failedFiles.length) {
+      console.log(chalk.dim('  Rerun only the failed task(s):'));
+      console.log(chalk.cyan(`    badgr batch run ${yamlPath} --fan-out ${fanOutDir} --only ${failedFiles.join(',')}\n`));
+    }
+    process.exitCode = 1;
+  }
+}
+
 async function runSubcommand(config, args, chalk) {
   const flags = {};
   const positional = [];
@@ -188,6 +374,10 @@ async function runSubcommand(config, args, chalk) {
     if (args[i] === '--tier')   { flags.tier = args[++i]; continue; }
     if (args[i] === '--region') { flags.region = args[++i]; continue; }
     if (args[i] === '--gpu')    { flags.gpu = args[++i]; continue; }
+    if (args[i] === '--fan-out') { flags.fanOut = args[++i]; continue; }
+    if (args[i] === '--max-concurrency') { flags.maxConcurrency = parseInt(args[++i], 10); continue; }
+    if (args[i] === '--only') { flags.only = args[++i].split(',').map(s => s.trim()).filter(Boolean); continue; }
+    if (args[i] === '--dry-run') { flags.dryRun = true; continue; }
     positional.push(args[i]);
   }
   const yamlPath = positional[0];
@@ -208,6 +398,10 @@ async function runSubcommand(config, args, chalk) {
     return;
   }
 
+  if (flags.fanOut) {
+    return runFanOutSubcommand(config, spec, flags, chalk, yamlPath);
+  }
+
   console.log(chalk.bold(`\n📦 Batch: ${spec.name}\n`));
   console.log(`  ${chalk.bold('Image:')}        ${spec.image}`);
   console.log(`  ${chalk.bold('Command:')}      ${spec.command.join(' ')}`);
@@ -217,6 +411,11 @@ async function runSubcommand(config, args, chalk) {
   if (spec.outputs.length) console.log(`  ${chalk.bold('Outputs:')}      ${spec.outputs.join(', ')}`);
   console.log();
 
+  if (flags.dryRun) {
+    console.log(chalk.bold('⚡ Dry run — no GPU will be provisioned\n'));
+    return;
+  }
+
   let inputsArchiveUrl = null;
   if (spec.inputs.length > 0) {
     try {
@@ -288,6 +487,8 @@ async function runSubcommand(config, args, chalk) {
     maxRuntime: spec.maxRuntimeMinutes,
     status: dep.status,
     createdAt: new Date().toISOString(),
+    workloadShape: 'container-batch',
+    computeSelected: selectedComputeFromDeployment(dep),
   });
 
   const rate = dep.cost_per_hour || 0;

package/src/commands/billing.js

@@ -1,6 +1,6 @@
-import { execSync } from 'child_process';
 import { requireApiKey } from '../config.js';
 import { callApi } from '../api.js';
+import { openBrowser } from '../browser.js';
 
 const BILLING_HELP = `
 badgr billing — manage your AI Badgr balance
@@ -16,17 +16,6 @@ EXAMPLES
   badgr billing add 50
 `;
 
-function openBrowser(url) {
-  const platform = process.platform;
-  try {
-    if (platform === 'darwin') execSync(`open "${url}"`);
-    else if (platform === 'win32') execSync(`start "" "${url}"`);
-    else execSync(`xdg-open "${url}"`);
-  } catch {
-    // Silently ignore — we print the URL anyway
-  }
-}
-
 async function billingStatus(config, chalk) {
   requireApiKey(config);
   try {

package/src/commands/capacity.js

@@ -21,7 +21,9 @@ export async function capacityCommand(config, args, chalk) {
   const flags = parseCapacityArgs(args);
   requireApiKey(config);
 
-  const maxPrice = flags.maxPrice ?? 10;
+  // No --max-price: no cap. Availability browsing shouldn't silently hide
+  // real capacity behind an unrequested price ceiling.
+  const maxPrice = flags.maxPrice;
 
   // No --gpu: show cheapest runnable GPU across all types
   if (!flags.gpu) {
@@ -30,7 +32,8 @@ export async function capacityCommand(config, args, chalk) {
 
     let data;
     try {
-      const params = new URLSearchParams({ max_price: String(maxPrice) });
+      const params = new URLSearchParams();
+      if (maxPrice !== undefined) params.set('max_price', String(maxPrice));
       if (flags.region) params.set('region', flags.region.toUpperCase());
       data = await callApi(`/capacity/auto?${params}`, {
         apiKey: config.apiKey,
@@ -60,7 +63,8 @@ export async function capacityCommand(config, args, chalk) {
 
   // --gpu specified: show availability for that type
   const gpu = flags.gpu.toUpperCase().replace('-', '_');
-  const params = new URLSearchParams({ gpu, max_price: String(maxPrice) });
+  const params = new URLSearchParams({ gpu });
+  if (maxPrice !== undefined) params.set('max_price', String(maxPrice));
   if (flags.region) params.set('region', flags.region.toUpperCase());
 
   console.log(chalk.bold(`\nCapacity: ${gpu}\n`));
@@ -90,7 +94,8 @@ export async function capacityCommand(config, args, chalk) {
     console.log();
   } else {
     const regionLabel = flags.region ? ` in ${flags.region.toUpperCase()}` : '';
-    console.log(chalk.dim(`\n  No ${gpu} available right now under $${maxPrice.toFixed(2)}/hr${regionLabel}.\n`));
+    const priceLabel = maxPrice !== undefined ? ` under $${maxPrice.toFixed(2)}/hr` : '';
+    console.log(chalk.dim(`\n  No ${gpu} available right now${priceLabel}${regionLabel}.\n`));
 
     const alternatives = data.alternatives ?? [];
     if (alternatives.length > 0) {

package/src/commands/comfyui.js

@@ -6,7 +6,7 @@
  * can queue it at startup.
  */
 import { readFileSync, existsSync } from 'fs';
-import { requireApiKey } from '../config.js';
+import { ensureBadgrReady } from '../onboarding.js';
 import { callApi, listDeployments } from '../api.js';
 import { addDeployment, addReceipt, updateReceipt, generateReceiptId } from '../store.js';
 import { normalizeTier, callWithFallback } from '../fallback.js';
@@ -192,7 +192,7 @@ export async function comfyBatchCommand(config, args, chalk) {
     return;
   }
 
-  requireApiKey(config);
+  config = await ensureBadgrReady(config, chalk);
 
   if (prompts.length === 0) {
     console.error(chalk.red('\n  ✗ No prompts provided. Use --prompts file.txt or --prompt "text"\n'));
@@ -282,7 +282,7 @@ export async function comfyuiCommand(config, args, chalk) {
     return;
   }
 
-  requireApiKey(config);
+  config = await ensureBadgrReady(config, chalk);
 
   if (!flags.maxCost && !flags.persistent) {
     console.error(chalk.red('\n  ✗ ComfyUI endpoints bill continuously. Specify a spending limit:\n'));

package/src/commands/connect.js

@@ -0,0 +1,83 @@
+import {
+  KNOWN_PROVIDERS,
+  getCredential,
+  setCredential,
+  removeCredential,
+  listCredentials,
+  CREDENTIALS_FILE,
+} from '../credentials.js';
+
+/**
+ * badgr connect <provider> [--key <value>] [--remove]
+ * badgr connect            (lists what's already connected)
+ *
+ * One-time credential storage so `badgr launch claude "..."` doesn't need
+ * an explicit --env ANTHROPIC_API_KEY=... on every invocation. Stored in
+ * ~/.badgr/credentials.json, chmod 600 — a local file, not the real OS
+ * keychain (see credentials.js for why).
+ */
+export async function connectCommand(args, chalk, deps = {}) {
+  const provider = args[0];
+
+  if (!provider || provider === 'list' || provider === 'ls') {
+    const connected = listCredentials();
+    if (connected.length === 0) {
+      console.log(chalk.dim('\n  No providers connected yet.'));
+      console.log(chalk.dim(`  Run: badgr connect anthropic\n`));
+    } else {
+      console.log(chalk.bold('\nConnected providers:'));
+      for (const p of connected) console.log(`  ✓ ${p}`);
+      console.log();
+    }
+    return;
+  }
+
+  if (!KNOWN_PROVIDERS.includes(provider)) {
+    console.error(chalk.red(`\n  ✗ Unknown provider: ${provider}`));
+    console.error(chalk.dim(`  Supported: ${KNOWN_PROVIDERS.join(', ')}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--key') { flags.key = args[++i]; continue; }
+    if (args[i] === '--remove') { flags.remove = true; continue; }
+  }
+
+  if (flags.remove) {
+    const removed = removeCredential(provider);
+    console.log(removed
+      ? chalk.green(`\n  ✓ Removed stored credential for ${provider}\n`)
+      : chalk.dim(`\n  No credential stored for ${provider}\n`));
+    return;
+  }
+
+  let key = flags.key;
+  if (!key) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      console.error(chalk.red(`\n  ✗ --key <value> is required in non-interactive mode.\n`));
+      console.error(chalk.dim(`  Example: badgr connect ${provider} --key sk-...\n`));
+      process.exitCode = 1;
+      return;
+    }
+    const { password } = deps.prompts || await import('@inquirer/prompts');
+    key = await password({
+      message: `Enter your ${provider} API key:`,
+      validate: v => v.trim() ? true : 'API key is required',
+    });
+  }
+
+  key = key.trim();
+  if (!key) {
+    console.error(chalk.red('\n  ✗ API key is required.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const alreadyConnected = Boolean(getCredential(provider));
+  setCredential(provider, key);
+  console.log(chalk.green(`\n  ✓ ${alreadyConnected ? 'Updated' : 'Connected'} ${provider}`));
+  console.log(chalk.dim(`  Stored in ${CREDENTIALS_FILE} (owner-only file permissions)`));
+  console.log(chalk.dim(`  Used automatically by: badgr launch ${provider === 'anthropic' ? 'claude' : provider === 'openai' ? 'codex' : provider} "<task>"\n`));
+}

package/src/commands/doctor.js

@@ -0,0 +1,127 @@
+import { runGpuDoctor } from '../gpuDoctor/doctor.js';
+
+/**
+ * badgr doctor [--model <id>] [--serve] [--workflow <path>] [--logs <path>]
+ *              [--url <url>] [--gpu <name>] [--vram-gb <n>] [--json]
+ *
+ * Read-only diagnosis. Never provisions, restarts, or mutates anything.
+ */
+export function parseDoctorArgs(args) {
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '--model')     { flags.model = args[++i]; i++; continue; }
+    if (a === '--serve')     { flags.serve = true; i++; continue; }
+    if (a === '--workflow')  { flags.workflowPath = args[++i]; i++; continue; }
+    if (a === '--logs')      { flags.logsPath = args[++i]; i++; continue; }
+    if (a === '--url')       { flags.url = args[++i]; i++; continue; }
+    if (a === '--gpu')       { flags.gpu = args[++i]; i++; continue; }
+    if (a === '--gpu-count') { flags.gpuCount = parseInt(args[++i], 10); i++; continue; }
+    if (a === '--vram-gb')   { flags.vramGb = parseFloat(args[++i]); i++; continue; }
+    if (a === '--context-len') { flags.contextLen = parseInt(args[++i], 10); i++; continue; }
+    if (a === '--json')      { flags.json = true; i++; continue; }
+    if (a === '--no-cache')  { flags.noCache = true; i++; continue; }
+    i++;
+  }
+  return flags;
+}
+
+function printText(report, chalk) {
+  console.log();
+  console.log(`${chalk.bold('Verdict:')} ${report.verdict}`);
+  console.log();
+  console.log(chalk.bold('Likely cause:'));
+  console.log(report.likelyCause);
+
+  if (report.evidence.length) {
+    console.log();
+    console.log(chalk.bold('Evidence:'));
+    for (const line of report.evidence) console.log(`- ${line}`);
+  }
+
+  if (report.suggestedFixes.length) {
+    console.log();
+    console.log(chalk.bold('Suggested fix:'));
+    for (const fix of report.suggestedFixes) console.log(`- ${fix}`);
+  }
+
+  if (report.badgrCommand) {
+    console.log();
+    console.log(chalk.bold('Badgr route:'));
+    console.log(chalk.cyan(report.badgrCommand));
+  }
+  console.log();
+}
+
+function printJson(report) {
+  console.log(JSON.stringify({
+    verdict: report.verdictSlug,
+    verdict_label: report.verdict,
+    category: report.category,
+    likely_cause: report.likelyCause,
+    evidence: report.evidence,
+    suggested_fixes: report.suggestedFixes,
+    badgr_command: report.badgrCommand,
+  }, null, 2));
+}
+
+const DOCTOR_HELP = `
+Diagnose why a GPU workload is likely failing — read-only, no login needed.
+
+Usage:
+  badgr doctor
+  badgr doctor --model <id> [--serve]
+  badgr doctor --logs <path>
+  badgr doctor --workflow <path>
+  badgr doctor --url <url>
+  badgr doctor --json
+
+Flags:
+  --model <id>           Model to evaluate against available VRAM, e.g. Qwen/Qwen2.5-7B-Instruct
+  --serve                Mark the model check as a serving workload (only with --model)
+  --workflow <path>      Path to a ComfyUI workflow JSON to diagnose
+  --logs <path>          Path to a vLLM/GPU workload log file to classify
+  --url <url>            Endpoint URL to health-check, e.g. http://localhost:8000/v1/models
+  --gpu <name>           Named GPU to size against, e.g. RTX4090, A100, L40S
+  --gpu-count <n>        Number of GPUs for a tensor-parallel estimate (default: 1)
+  --vram-gb <n>          Override available VRAM in GB directly
+  --context-len <n>      Context length used in the model VRAM estimate (default: 8192)
+  --json                 Machine-readable JSON output
+  --no-cache             Force fresh nvidia-smi/torch probes instead of a cached result (<=10s old)
+
+Priority when multiple sources are given: --logs > --url > --workflow > --model.
+Never mutates the machine: no restarts, no driver/CUDA changes, no installs, no uploads.
+
+Full reference: docs/gpu-doctor.md`;
+
+export async function doctorCommand(config, args, chalk) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(DOCTOR_HELP);
+    return;
+  }
+
+  const flags = parseDoctorArgs(args);
+
+  if (flags.serve && !flags.model) {
+    console.log(chalk.yellow('\n  Note: --serve only applies together with --model; ignoring --serve.\n'));
+    flags.serve = false;
+  }
+
+  let report;
+  try {
+    report = await runGpuDoctor(flags, { noCache: flags.noCache });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ ${err.message}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) {
+    printJson(report);
+  } else {
+    printText(report, chalk);
+  }
+  // Diagnosis outcomes (including "likely fail") are never tool errors —
+  // exit 0 unless we hit an actual runtime problem above.
+}