badgr-cli 1.0.48 → 1.1.0

package/README.md

@@ -46,10 +46,47 @@ Runs a blessed ComfyUI workflow, no setup, and prints image URLs when done. No m
 
 ---
 
+## Something not working? `badgr doctor`
+
+Read-only diagnosis for GPU workload failures — checks your GPU, drivers,
+CUDA, PyTorch, and disk, then tells you what's likely wrong and what to try
+next. No login, no setup, never mutates your machine.
+
+```bash
+badgr doctor
+```
+
+```bash
+# A model won't fit / you're not sure it'll fit before you try
+badgr doctor --model meta-llama/Llama-3.1-8B-Instruct
+
+# You have an error from a crashed job — save it to a file first
+badgr doctor --logs error.log
+
+# A ComfyUI workflow is failing or referencing something missing
+badgr doctor --workflow my-workflow.json
+
+# You started a server and it's not responding (ComfyUI, llama.cpp, and
+# generic health formats are recognized too, not just OpenAI-style)
+badgr doctor --url http://localhost:8000/v1/models
+
+# Splitting a big model across multiple GPUs (tensor parallel)
+badgr doctor --model meta-llama/Llama-3.1-70B-Instruct-AWQ --serve --gpu-count 2
+
+# Machine-readable output for scripts/CI
+badgr doctor --json
+```
+
+Run `badgr doctor --help` for the full flag list. Details in
+[`docs/gpu-doctor.md`](../../docs/gpu-doctor.md).
+
+---
+
 ## Commands
 
 ```text
 login
+doctor
 run
 serve
 status
@@ -62,6 +99,7 @@ test
 | Command | What it does |
 |---------|-------------|
 | `badgr login` | Save API key to `~/.badgr/config.json` |
+| `badgr doctor` | Diagnose a GPU workload failure — read-only, no login needed |
 | `badgr run <command>` | Run a one-off GPU job (any container command) |
 | `badgr serve <model>` | Start a persistent OpenAI-compatible endpoint |
 | `badgr status` | Show what's running and what's billing |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "badgr-cli",
-  "version": "1.0.48",
+  "version": "1.1.0",
   "description": "Badgr — run or serve GPU workloads from one command",
   "type": "module",
   "bin": {

package/src/api.js

@@ -135,7 +135,21 @@ export function runJob(config, body) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body,
-    timeoutMs: 130_000,
+    timeoutMs: 220_000, // must stay above backend's ~200s provision deadline — see fallback.js's callWithFallback
+  });
+}
+
+// Preview the VM class + Badgr rate for a CPU launch before provisioning
+// anything (see backend run_serve_routes.py's POST /v1/run/quote). Callers
+// should treat a failure here as non-fatal — this is a best-effort preview,
+// never a precondition for launching.
+export function quoteRun(config, body) {
+  return callApi('/run/quote', {
+    method: 'POST',
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    body,
+    timeoutMs: 5_000,
   });
 }
 
@@ -145,7 +159,7 @@ export function serveModel(config, body) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body,
-    timeoutMs: 130_000,
+    timeoutMs: 220_000, // must stay above backend's ~200s provision deadline — see fallback.js's callWithFallback
   });
 }
 

package/src/artifactDownload.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * Resolves the /v1/deployments/{id}/artifacts/download URL from a
+ * configured baseUrl, whether or not it already ends in /v1.
+ */
+export function artifactDownloadUrl(baseUrl, deploymentId) {
+  const base = String(baseUrl || '').replace(/\/v1\/?$/, '').replace(/\/+$/, '');
+  return `${base}/v1/deployments/${deploymentId}/artifacts/download`;
+}
+
+/**
+ * Downloads a deployment's artifact tar.gz and extracts it into destDir
+ * (created if needed). Shared by `badgr pull`, `badgr artifacts`, and
+ * `badgr batch artifacts` — the only thing that differs between them is
+ * how each wraps a non-OK response into a user-facing message.
+ *
+ * On a non-OK response, throws an Error with `.httpStatus`/`.statusText`/
+ * `.bodyText` set so callers can build their own message; the thrown
+ * Error's own `.message` is a reasonable generic fallback. A network-level
+ * failure (DNS, connection refused, etc.) propagates as whatever `fetch`
+ * itself throws, with no `.httpStatus` — callers can use that distinction
+ * to tell "couldn't reach Badgr" apart from "Badgr said no".
+ */
+export async function downloadAndExtractArtifact(config, deploymentId, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const res = await fetch(artifactDownloadUrl(config.baseUrl, deploymentId), {
+    headers: { Authorization: `Bearer ${config.apiKey}` },
+  });
+  if (!res.ok) {
+    const bodyText = await res.text().catch(() => '');
+    const err = new Error(`artifact download failed: ${res.status} ${res.statusText}${bodyText ? ` — ${bodyText}` : ''}`);
+    err.httpStatus = res.status;
+    err.statusText = res.statusText;
+    err.bodyText = bodyText;
+    throw err;
+  }
+
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const tmpFile = path.join(os.tmpdir(), `badgr-artifact-${deploymentId}-${Date.now()}.tar.gz`);
+  fs.writeFileSync(tmpFile, bytes);
+  try {
+    // node-tar (v7) has no default export — only named exports (x, c, ...).
+    // Destructuring `default` here always resolved to undefined, crashing
+    // every real extraction with "Cannot read properties of undefined
+    // (reading 'x')" — found via a live badgr artifacts/pull download.
+    const { x } = await import('tar');
+    await x({ file: tmpFile, cwd: destDir });
+  } finally {
+    fs.rmSync(tmpFile, { force: true });
+  }
+}

package/src/badgr.js

@@ -8,6 +8,9 @@ import { statusCommand }     from './commands/status.js';
 import { logsCommand }       from './commands/logs.js';
 import { receiptsCommand }   from './commands/receipts.js';
 import { runCommand }        from './commands/run.js';
+import { launchCommand }     from './commands/launch.js';
+import { taskCommand }       from './commands/task.js';
+import { artifactsCommand }  from './commands/artifacts.js';
 import { serveCommand }      from './commands/serve.js';
 import { modelsCommand }     from './commands/models.js';
 import { capacityCommand }   from './commands/capacity.js';
@@ -20,23 +23,34 @@ import { embedCommand }      from './commands/embed.js';
 import { templateCommand }   from './commands/template.js';
 import { workloadCommand }   from './commands/workload.js';
 import { batchCommand }      from './commands/batch.js';
+import { sbatchCommand }     from './commands/sbatch.js';
 import { workspaceCommand }  from './commands/workspace.js';
 import { detectCommand }     from './commands/detect.js';
 import { restartCommand }    from './commands/restart.js';
 import { rerunCommand }      from './commands/rerun.js';
 import { heartbeatCommand }  from './commands/heartbeat.js';
+import { pullCommand }       from './commands/pull.js';
+import { doctorCommand }     from './commands/doctor.js';
+import { connectCommand }    from './commands/connect.js';
 
 const HELP = `
 ${chalk.bold('badgr')} — run or serve GPU workloads from one command
 
 ${chalk.bold('COMMANDS')}
   ${chalk.cyan('badgr login')}               Authenticate with your API key
+  ${chalk.cyan('badgr connect <provider>')}  Credential setup (badgr connect anthropic/openai) — also prompted inline by badgr launch if missing
   ${chalk.cyan('badgr detect <path>')}       Inspect a project and report the GPU job Badgr would run
   ${chalk.cyan('badgr run <command>')}       Run a one-off GPU job
+  ${chalk.cyan('badgr launch cline|claude|codex|playwright "<task>"')}  Run a coding/testing workload on a CPU VM — image + command auto-selected
+  ${chalk.cyan('badgr launch <source> -- <command>')}  Advanced escape hatch: run any other command on a CPU VM
+  ${chalk.cyan('badgr task "<desc>" -- <command>')}    Label + launch — thin wrapper over badgr launch . -- <command>
   ${chalk.cyan('badgr serve <model>')}       Serve a model with an OpenAI-compatible endpoint
   ${chalk.cyan('badgr serve openwebui')}     Serve Open WebUI — chat UI, connects to a model endpoint
+  ${chalk.cyan('badgr doctor')}              Diagnose why a GPU workload is likely failing (read-only, no login needed)
   ${chalk.cyan('badgr status')}              Show what's running and what's billing
   ${chalk.cyan('badgr logs <id>')}           Stream logs for a running job or endpoint
+  ${chalk.cyan('badgr pull <id>')}           Safely pull cloud-agent patch artifacts
+  ${chalk.cyan('badgr artifacts <id>')}      Download non-patch outputs (test reports, screenshots, traces)
   ${chalk.cyan('badgr down <id>')}           Stop a deployment and end billing
   ${chalk.cyan('badgr restart <id>')}        Relaunch an endpoint with the same config and API key
   ${chalk.cyan('badgr rerun <id>')}          Replay a past job or endpoint with its exact original spec
@@ -50,10 +64,12 @@ ${chalk.bold('COMMANDS')}
   ${chalk.cyan('badgr workspace list')}      List workspace trackers (job history + cost per named context)
   ${chalk.cyan('badgr workspace create')}    Create a workspace tracker (link jobs to a named storage path)
   ${chalk.cyan('badgr batch run <workload.yml>')}   Run a generic containerized batch job with artifact capture
+  ${chalk.cyan('badgr batch run <yml> --fan-out <dir>')}  Run the same program once per file in <dir> — one deployment per input, in parallel
   ${chalk.cyan('badgr batch status <run_id>')}      Show status, failure reason, cost, teardown
   ${chalk.cyan('badgr batch artifacts <run_id>')}   Download and extract output artifacts
   ${chalk.cyan('badgr batch receipt <run_id>')}     Show the full batch receipt
   ${chalk.cyan('badgr batch compare <a> <b>')}      Compare success_metric between two runs
+  ${chalk.cyan('badgr sbatch <job.slurm>')}         Run an existing Slurm batch script (cpus/mem/gres/array/time translated)
 
 ${chalk.bold('SHORTCUTS')}  ${chalk.dim('(wrappers around run / serve for common workloads)')}
   ${chalk.cyan('badgr comfyui run <workflow.json>')}   Launch ComfyUI, return endpoint URL
@@ -68,6 +84,40 @@ ${chalk.bold('SHORTCUTS')}  ${chalk.dim('(wrappers around run / serve for common
   ${chalk.cyan('badgr serve --list-aliases')}          List blessed vLLM model shortcuts (qwen-7b, llama-8b, …)
 
 ${chalk.bold('EXAMPLES')}
+  ${chalk.dim('# Frictionless launch — no source, no --, no image, no --max-cost required')}
+  ${chalk.dim('# (a $2 default cost cap applies automatically; override with --max-cost).')}
+  ${chalk.dim('# cline is Badgr-native (no credential needed); claude/codex prompt inline for a')}
+  ${chalk.dim('# provider key the first time, then remember it; playwright needs no credential.')}
+  ${chalk.dim('# Each workload auto-selects its VM class (small, or "browser" for playwright);')}
+  ${chalk.dim('# override with --size small|medium|browser.')}
+  badgr launch cline "Fix the checkout bug"
+  badgr launch claude "Fix the checkout bug"
+  badgr launch codex "Write tests"
+  badgr launch playwright "Test the checkout flow"
+  badgr launch claude --size medium "Run the complete test suite"
+  badgr pull <id>
+  badgr artifacts <id>
+  badgr logs <id>
+  badgr receipts <id>
+
+  ${chalk.dim('# Explicit form — advanced escape hatch for anything not in the four workloads above.')}
+  ${chalk.dim('# Badgr flags go BEFORE --; everything after -- is passed to your command unchanged.')}
+  ${chalk.dim('# The default runner image is Python-only (no Node.js/npm) — a Node-based command')}
+  ${chalk.dim('# must install what it needs, or use --image with a custom image (see images/badgr-agent-*):')}
+  badgr launch . --max-cost 1 -- npm test
+  badgr launch https://github.com/user/repo --max-cost 1 -- python narrgo.py
+  badgr artifacts <id>
+
+  ${chalk.dim('# badgr task is a thin label wrapper over badgr launch . -- <command>:')}
+  badgr task "Run the Chromium tests and tell me what failed" --max-cost 1 -- npm run test:chromium
+
+  ${chalk.dim('# Diagnose why a GPU workload is likely failing (local, read-only, no login):')}
+  badgr doctor
+  badgr doctor --model Qwen/Qwen2.5-7B-Instruct --serve
+  badgr doctor --logs ./vllm.log
+  badgr doctor --workflow ./workflow.json
+  badgr doctor --url http://localhost:8000/health
+
   ${chalk.dim('# Point Badgr at any project and see what it detects:')}
   badgr detect .
   badgr run . --max-cost 5 --save my-job
@@ -106,12 +156,31 @@ ${chalk.bold('EXAMPLES')}
   badgr batch artifacts dep-abc123
   badgr batch compare dep-abc123 dep-def456
 
+  ${chalk.dim('# Run one program across many inputs — one deployment per file, in parallel:')}
+  ${chalk.dim('# workload.yml must declare exactly one inputs: entry (the path that varies per task).')}
+  ${chalk.dim('# --max-concurrency caps in-flight deployments (default: 5). --only reruns just the named files.')}
+  badgr batch run workload.yml --fan-out ./scenarios
+  badgr batch run workload.yml --fan-out ./scenarios --max-concurrency 10
+  badgr batch run workload.yml --fan-out ./scenarios --only failed1.json,failed2.json
+
+  ${chalk.dim('# Run an existing Slurm batch script — cpus-per-task/mem/gres/array/time translated:')}
+  ${chalk.dim('# --max-concurrency caps in-flight array tasks (default: 5).')}
+  badgr sbatch job.slurm
+  badgr sbatch job.slurm --dry-run
+  badgr sbatch array_job.slurm   ${chalk.dim('# #SBATCH --array=1-100 fans out into one deployment per task')}
+  badgr sbatch array_job.slurm --max-concurrency 10
+
   ${chalk.dim('# Tier 2 — marketplace routing, lower-cost options:')}
   badgr serve meta-llama/Llama-3.1-8B-Instruct --tier 2 --max-cost 10
 
   ${chalk.dim('# Pin a specific GPU:')}
   badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S --max-cost 10
 
+  ${chalk.dim('# Describe basic compute needs instead of a GPU model — Badgr finds a compatible machine:')}
+  badgr run . --cpu 16 --memory 64GB --gpu-memory 24GB --max-cost 5
+  badgr run . --gpu-memory 24GB     ${chalk.dim('# any GPU with at least 24GB VRAM')}
+  badgr run . --gpu A100 --count 4  ${chalk.dim('# exact hardware, for workloads that need it')}
+
   ${chalk.dim('# Manage a running deployment:')}
   badgr status
   badgr logs dep-abc123
@@ -120,6 +189,10 @@ ${chalk.bold('EXAMPLES')}
 
 ${chalk.bold('badgr run OPTIONS')}
   --gpu <type>           GPU type (default: auto — Badgr picks best available)
+  --gpu-memory <size>    Minimum GPU VRAM, e.g. 24GB — Badgr picks any GPU that satisfies it (alias: --min-vram)
+  --cpu <cores>          Minimum CPU cores
+  --memory <size>        Minimum RAM, e.g. 64GB
+  --no-gpu               Run on a CPU-only VM — no GPU is provisioned (conflicts with --gpu/--gpu-memory)
   --tier 1               Managed provider routing (default)
   --tier 2               Marketplace provider routing, lower-cost options
   --image <image>        Docker image (default: python:3.11-slim)
@@ -131,6 +204,30 @@ ${chalk.bold('badgr run OPTIONS')}
   --max-cost <$>         Auto-stop when spend reaches this amount
   --detach               Return immediately, don't stream logs
 
+${chalk.bold('badgr launch OPTIONS')}
+  ${chalk.yellow('All badgr launch flags below must come BEFORE --. Everything after -- is')}
+  ${chalk.yellow('passed to your command verbatim, including anything that looks like a flag —')}
+  ${chalk.yellow('badgr launch . -- claude --max-cost 1  sends --max-cost 1 to claude, not badgr.')}
+  --cmd "<command>"      Quoted command form (equivalent to \`-- <command>\`)
+  --image <image>        Custom image instead of the default CPU runtime image
+  --detach               Keep running after disconnect (default for launch)
+  --no-detach            Stream logs and wait instead of detaching
+  --env KEY=VALUE        Set an environment variable (repeatable). Provider keys (ANTHROPIC_API_KEY,
+                         etc.) passed this way may land in shell history and \`ps\` output — badgr
+                         launch warns when a key looks secret. Dashboard-managed --profile secrets
+                         are planned but not built yet.
+  --artifacts <path>     Extra path to capture and upload as a downloadable artifact (repeatable) —
+                         e.g. --artifacts playwright-report --artifacts test-results. Retrieve with
+                         \`badgr artifacts <id>\`. Relative paths are resolved from the workspace root.
+  --max-cost <$>         Auto-stop when spend reaches this amount
+  --max-runtime <min>    Auto-stop after N minutes (default: 60)
+  --region US|EU|AU      Region preference
+  --size small|medium|browser  VM class override. Defaults per workload: small for cline/claude/
+                         codex/explicit form, browser for playwright (Chromium preinstalled).
+
+${chalk.bold('badgr artifacts OPTIONS')}
+  --output <dir>         Directory to extract into (default: ~/.badgr/artifacts/<id>)
+
 ${chalk.bold('badgr serve OPTIONS')}
   --gpu <type>           GPU type (default: auto — inferred from model size)
   --image <image>        Serve a custom container instead of a HuggingFace model
@@ -169,8 +266,13 @@ async function main() {
 
   switch (cmd) {
     case 'login':    return loginCommand(chalk, saveConfig);
+    case 'connect':  return connectCommand(rest, chalk);
     case 'detect':   return detectCommand(config, rest, chalk);
     case 'run':      return runCommand(config, rest, chalk);
+    case 'launch':   return launchCommand(config, rest, chalk);
+    case 'task':     return taskCommand(config, rest, chalk);
+    case 'artifacts': return artifactsCommand(config, rest, chalk);
+    case 'pull':     return pullCommand(config, rest, chalk);
     case 'serve':    return serveCommand(config, rest, chalk);
     case 'status':   return statusCommand(config, rest, chalk);
     case 'logs':     return logsCommand(config, rest, chalk);
@@ -178,6 +280,7 @@ async function main() {
     case 'restart':   return restartCommand(config, rest, chalk);
     case 'rerun':     return rerunCommand(config, rest, chalk);
     case 'heartbeat': return heartbeatCommand(config, rest, chalk);
+    case 'doctor':    return doctorCommand(config, rest, chalk);
     case 'receipts': return receiptsCommand(config, rest, chalk);
     case 'models':   return modelsCommand(config, chalk);
     case 'capacity': return capacityCommand(config, rest, chalk);
@@ -190,6 +293,7 @@ async function main() {
     case 'template':  return templateCommand(config, rest, chalk);
     case 'workload':   return workloadCommand(config, rest, chalk);
     case 'batch':      return batchCommand(config, rest, chalk);
+    case 'sbatch':     return sbatchCommand(config, rest, chalk);
     case 'workspace':  return workspaceCommand(config, rest, chalk);
     // legacy aliases kept for compatibility
     case 'up':        return upCommand(config, rest, chalk);

package/src/batch.js

@@ -86,16 +86,27 @@ export async function monitorBatchJob(config, depId, rcptId, opts) {
       'interrupted': chalk.yellow('\n  Stopping...'),
     };
     console.log(msgs[reason] ?? chalk.yellow('\n  Stopping...'));
-    try { await terminateDeployment(config, depId); } catch {}
+    // A 200 response only means deletion was requested, not confirmed —
+    // teardown_ok reflects whether the provider resource is actually gone.
+    let teardownConfirmed = false;
+    try {
+      const result = await terminateDeployment(config, depId);
+      teardownConfirmed = result?.teardown_ok === 'ok';
+    } catch {}
     const runtimeMs = Date.now() - attachStart;
     const finalCost = ratePerHour * (runtimeMs / 3_600_000);
     updateReceipt(rcptId, {
       status:         reason,
+      teardownStatus: teardownConfirmed ? 'terminated' : 'failed',
       runtimeSeconds: Math.round(runtimeMs / 1000),
       finalCost,
     });
     console.log(chalk.dim(`  Runtime: ${fmtRuntime(runtimeMs)}  •  Est. cost: $${finalCost.toFixed(4)}`));
-    console.log(chalk.dim('  Stopped. Billing ended.\n'));
+    if (teardownConfirmed) {
+      console.log(chalk.dim('  Stopped. Billing ended.\n'));
+    } else {
+      console.log(chalk.yellow(`  Stop requested but not confirmed — resource may still be billing, check \`badgr status\` and \`badgr down ${depId}\`\n`));
+    }
   }
 
   while (true) {
@@ -135,14 +146,21 @@ export async function monitorBatchJob(config, depId, rcptId, opts) {
       const exitCode  = dep.exit_code ?? null;
       const runtimeMs = Date.now() - attachStart;
       const finalCost = ratePerHour * (runtimeMs / 3_600_000);
-      try { await terminateDeployment(config, depId); } catch {}
+      // A 200 response only means deletion was requested, not confirmed —
+      // teardown_ok reflects whether the provider resource is actually gone.
+      let teardownConfirmed = false;
+      try {
+        const result = await terminateDeployment(config, depId);
+        teardownConfirmed = result?.teardown_ok === 'ok';
+      } catch {}
       updateReceipt(rcptId, {
         status:         dep.status,
         exitCode,
+        teardownStatus: teardownConfirmed ? 'terminated' : 'failed',
         runtimeSeconds: Math.round(runtimeMs / 1000),
         finalCost,
       });
-      return { status: dep.status, exitCode, runtimeMs, reason: 'complete' };
+      return { status: dep.status, exitCode, runtimeMs, teardownConfirmed, reason: 'complete' };
     }
   }
 

package/src/browser.js

@@ -0,0 +1,23 @@
+import { execFileSync } from 'child_process';
+
+/** Best-effort open a URL in the user's default browser. Never throws —
+ * callers should always also print the URL, since headless/CI environments
+ * (or an unrecognized platform) may have nothing to open it with.
+ *
+ * Uses execFileSync (argv array, no shell) rather than execSync (a shell
+ * string) — url is not always a local constant (onboarding.js passes
+ * session.login_url, a backend API response), so building a shell command
+ * via string interpolation would be a real command-injection vector if a
+ * response ever contained shell metacharacters. execFileSync passes url as
+ * one literal argv element to the opener command directly; no shell parses
+ * it at all. */
+export function openBrowser(url) {
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') execFileSync('open', [url]);
+    else if (platform === 'win32') execFileSync('cmd', ['/c', 'start', '', url]);
+    else execFileSync('xdg-open', [url]);
+  } catch {
+    // Silently ignore — the caller prints the URL as a fallback.
+  }
+}

package/src/commands/artifacts.js

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+import { requireApiKey, CONFIG_DIR } from '../config.js';
+import { downloadAndExtractArtifact } from '../artifactDownload.js';
+
+/**
+ * badgr artifacts <id> [--output <dir>]
+ *
+ * Generic artifact retrieval for `badgr launch`/`badgr run` output paths
+ * (e.g. --artifacts playwright-report --artifacts test-results) — anything
+ * captured that isn't a git patch. `badgr pull` is for code changes;
+ * `badgr artifacts` is for everything else a command produced.
+ */
+
+function defaultDestDir(deploymentId) {
+  return path.join(CONFIG_DIR, 'artifacts', deploymentId);
+}
+
+export function parseArtifactsArgs(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--output') { flags.output = args[++i]; continue; }
+    positional.push(args[i]);
+  }
+  return { deploymentId: positional[0], flags };
+}
+
+export function listFilesRecursive(dir, prefix = '') {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFilesRecursive(path.join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out.sort();
+}
+
+export async function artifactsCommand(config, args, chalk) {
+  requireApiKey(config);
+  const { deploymentId, flags } = parseArtifactsArgs(args);
+  if (!deploymentId) {
+    console.error(chalk.red('\n  Usage: badgr artifacts <deployment-id> [--output <dir>]\n'));
+    console.error(chalk.dim('  Example: badgr artifacts dep-abc123\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const destDir = flags.output ? path.resolve(flags.output) : defaultDestDir(deploymentId);
+
+  try {
+    await downloadAndExtractArtifact(config, deploymentId, destDir);
+  } catch (err) {
+    if (err.httpStatus === 404) {
+      console.error(chalk.red(`\n  ✗ No artifact found for ${deploymentId}.\n`));
+      console.error(chalk.dim('  This means either the run had no --artifacts paths declared, it failed before'));
+      console.error(chalk.dim('  producing any of them, or it is still running. Check `badgr logs ' + deploymentId + '`.\n'));
+    } else if (err.httpStatus !== undefined) {
+      console.error(chalk.red(`\n  ✗ Artifact download failed: ${err.httpStatus} ${err.statusText}${err.bodyText ? ` — ${err.bodyText}` : ''}\n`));
+    } else {
+      console.error(chalk.red(`\n  ✗ Could not reach Badgr: ${err.message}\n`));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const files = listFilesRecursive(destDir);
+  console.log(chalk.green(`\n  Downloaded artifacts for ${deploymentId} → ${destDir}\n`));
+  if (files.length === 0) {
+    console.log(chalk.dim('  (artifact was empty)'));
+  } else {
+    for (const f of files) console.log(`  - ${f}`);
+  }
+  console.log();
+}