badgr-cli 1.1.6 → 1.1.8

package/README.md

@@ -167,15 +167,17 @@ secrets, and runs free static checks as part of a Badgr Smoke Test.
 Nothing runs on a GPU without explicit `--approve`.
 
 ```bash
-# badgr diagnose IS the Badgr Smoke Test — free, no login, no GPU.
-# Applicable free structural checks run automatically, every time.
+# Free Badgr Smoke Test — no login required
 badgr diagnose "https://github.com/org/repo/issues/123"
 badgr diagnose ajayrajtp/vllm_gemma412b:latest
 badgr diagnose ./vllm-error.log
 badgr diagnose "https://github.com/org/repo"
 badgr diagnose workflow.json
 
-# Start a real Badgr Run (paid GPU execution) after diagnosis (login required)
+# Free mechanical validation of the produced command — still no GPU, no login
+badgr diagnose "https://github.com/org/repo/issues/123" --smoke
+
+# Approve a capped smoke test after diagnosis (login required)
 badgr diagnose "https://github.com/org/repo/issues/123" --approve
 
 # Resume an existing case, e.g. one shared via a case link
@@ -188,8 +190,8 @@ badgr diagnose "https://github.com/org/repo/issues/123" --json
 
 | Flag | Description |
 |------|-------------|
-| `--approve` | Start a real Badgr Run after diagnosis — actual GPU execution, capped at a hard maximum spend (opens browser sign-in automatically if not logged in) |
-| `--smoke` | Deprecated, no-op. The free mechanical checks this used to gate (syntax, CLI-entrypoint corroboration, referenced-file presence, Docker `ENTRYPOINT`/`CMD` consistency, required env vars, plus a client-side local-file check) now always run as part of plain `badgr diagnose`. Kept only so existing scripts that pass it don't break. Not the same as `badgr run --smoke`, which launches a real, billable GPU job |
+| `--smoke` | Free. Runs real, cheap mechanical validation of the produced command (syntax, CLI-entrypoint corroboration, referenced-file presence, Docker `ENTRYPOINT`/`CMD` consistency, required env vars, plus a client-side check of any local file path you pasted). Never starts a GPU, never requires login. Combine with `--approve` — the smoke checks print first, then the normal approve flow runs. Not the same as `badgr run --smoke`, which launches a real, billable GPU job |
+| `--approve` | Approve the capped smoke test after diagnosis (opens browser sign-in automatically if not logged in) |
 | `--docker <image>` | Force Docker-image intake (override auto-detect) |
 | `--repo <url>` | Force repository intake (override auto-detect) |
 | `--comfyui <path>` | Force ComfyUI workflow intake (override auto-detect) |
@@ -197,13 +199,13 @@ badgr diagnose "https://github.com/org/repo/issues/123" --json
 | `--json` | Machine-readable JSON output |
 
 Every run prints one status: `NEEDS INFO` (fields still missing) →
-`READY` (complete evidence-backed command, no applicable checks to run) →
-`SMOKE CHECKED` (applicable checks ran, all passed or were skipped) /
-`INVALID` (an applicable check actually failed) → `VERIFIED` (reserved for
-an actual successful Badgr Run — never assigned from diagnosis alone).
-`READY`/`SMOKE CHECKED` results also print the canonical `badgr
-run`/`badgr serve` command `--approve` would run, plus a shareable case
-link — pass that case ID or URL back into `badgr diagnose
+`READY` (complete evidence-backed command, no smoke run) → `SMOKE CHECKED`
+(`--smoke` ran, every applicable check passed or was skipped) / `INVALID`
+(`--smoke` ran and a check actually failed) → `VERIFIED` (reserved for an
+actual successful GPU-provisioned run — never assigned from static
+resolution or `--smoke`). `READY`/`SMOKE CHECKED` results also print the
+canonical `badgr run`/`badgr serve` command `--approve` would run, plus a
+shareable case link — pass that case ID or URL back into `badgr diagnose
 <case_id_or_url> --approve` to resume the same case without re-diagnosing.
 
 `badgr run-issue` is an alias for `badgr diagnose`, matching the
@@ -217,6 +219,7 @@ web flow.
 ```text
 login
 connect
+node
 doctor
 diagnose
 run
@@ -238,7 +241,8 @@ test
 | Command | What it does |
 |---------|-------------|
 | `badgr login` | Save API key to `~/.badgr/config.json` |
-| `badgr connect <provider>` | Store a provider credential (`anthropic`, `openai`) for `badgr launch` |
+| `badgr connect <provider>` | Store a provider credential (`anthropic`, `openai`, `openrouter`, `deepseek`, `glm`, `custom`) for `badgr launch` |
+| `badgr node connect\|list\|inspect\|disable\|remove` | BYO GPU — connect your own Linux/NVIDIA or Linux/AMD-ROCm machine and run `run`/`serve` on it (see [BYO GPU](#byo-gpu-badgr-node)) |
 | `badgr doctor` | Diagnose a GPU workload failure — read-only, no login needed |
 | `badgr diagnose "<input>"` | Run a Badgr Smoke Test on a GitHub issue, Docker image, repo, log, or workflow — free, no GPU until `--approve` |
 | `badgr run <command>` | Run a one-off GPU job (any container command) |
@@ -271,6 +275,7 @@ These appear on most commands (`run`, `serve`, `comfyui`, `train`, `transcribe`,
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--gpu <type>` | auto | GPU type override — see [GPU options](#gpu-options) |
+| `--target <node>` | — | Run on one of your own connected machines instead of Badgr's cloud capacity — a node name or `node_…` id from `badgr node list`. See [BYO GPU](#byo-gpu-badgr-node) |
 | `--tier 1\|2` | 1 | `1` = reliable managed routing (default); `2` = lower-cost marketplace routing |
 | `--region US\|EU\|AU` | — | Region preference. If omitted, Badgr chooses best available capacity |
 | `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
@@ -521,6 +526,53 @@ Additional GPU types may be routable depending on current capacity — check wit
 
 ---
 
+## BYO GPU: `badgr node`
+
+Connect a machine you already own (Linux + NVIDIA or AMD/ROCm, Docker required) and run `badgr run`/`badgr serve` workloads on it instead of Badgr's cloud capacity — no separate execution path, just a `--target` on the commands you already use.
+
+```bash
+badgr node connect                    # register this machine and start the badgr-node worker
+badgr node connect --name gpu-box-1   # optional human-readable name
+
+badgr node list                       # your connected nodes, online/offline
+badgr node inspect <node-id>          # full JSON detail for one node
+badgr node disable <node-id>          # stop it from receiving new jobs (keeps the row)
+badgr node remove <node-id>           # disconnect and forget it
+
+badgr run "python train.py" --target gpu-box-1     # run on that node instead of the cloud
+badgr serve meta-llama/Llama-3.1-8B-Instruct --target gpu-box-1
+```
+
+`badgr node connect` detects your GPU(s) via `nvidia-smi` (falling back to `rocm-smi` for AMD/ROCm) and Docker availability, registers the node (`POST /v1/nodes`), and — if a GPU, Docker, and `python3` are all present — spawns the `badgr-node` worker daemon in the background so the node starts accepting jobs immediately. If anything's missing, it prints the exact command to start the worker manually once fixed. The worker itself re-probes vendor locally (`nvidia-smi`/`rocm-smi`) at startup and picks the matching `docker run` GPU flags — `--gpus all` on NVIDIA, or `--device=/dev/kfd --device=/dev/dri --group-add video --group-add render --security-opt seccomp=unconfined` on AMD.
+
+A connected node is **private by default** — it is never marketplace-listed or shared; only you can target it, and only with `--target`. Marketplace listing, payout, and reputation scoring are not built yet (explicit follow-up phases).
+
+### Host-bound dependencies (venvs, patched source, model/cache dirs)
+
+Jobs run inside a Docker container, which starts with none of this machine's filesystem visible except what's explicitly mounted. If your launch command depends on paths that already exist on this host — a Python venv, a patched source checkout (e.g. a custom-built vLLM), a model directory, a pip/HuggingFace cache — those paths will **not** exist inside the container unless you mount them:
+
+```bash
+badgr node connect \
+  --mount /home/you/venvs/vllm:/opt/venv \
+  --mount /home/you/vllm-src:/opt/vllm-src \
+  --mount /sync/Models:/models:ro \
+  --mount /home/you/.cache:/root/.cache
+```
+
+Each `--mount` is `HOST:CONTAINER` or `HOST:CONTAINER:ro` (same shape as `docker run -v`), repeatable, and both sides must be absolute paths. Mounts are configured once per node (not per job) and applied to every job that node runs. If you connected without `--mount` and the worker is already running, stop it and restart with the printed `python3 .../node_worker.py ...` command plus your `--mount` flags — there is no separate command to add a mount to an already-running worker yet.
+
+An exact command that already works when you run it directly on this machine can still fail through `--target` if it references host paths you haven't mounted — that's a mounting gap, not a vendor/architecture/capacity one (see the BYO Preflight vendor/architecture checks above, which catch a different class of mismatch and pass independently of whether paths are mounted).
+
+| Command | What it does |
+|---------|-------------|
+| `badgr node connect [--name <name>] [--mount HOST:CONTAINER[:ro] ...]` | Register this machine and start its worker |
+| `badgr node list` | List your connected nodes |
+| `badgr node inspect <node-id>` | Show one node's full detail as JSON |
+| `badgr node disable <node-id>` | Stop a node from receiving new jobs |
+| `badgr node remove <node-id>` | Disconnect and forget a node |
+
+---
+
 ## Routing
 
 `--tier 1` (default) uses managed provider routing — reliable, consistent performance. `--tier 2` uses marketplace routing for lower-cost options. Most users should stick with the default.

package/package.json

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

package/src/admin.js

@@ -0,0 +1,29 @@
+/**
+ * Internal admin-only operations -- never part of the public CLI export.
+ * Backs `badgr status --admin` / `badgr down <id> --admin`, gated
+ * server-side by an internal admin allowlist. Kept in its own module,
+ * separate from api.js, so it can be excluded by name from
+ * OSS_EXPORTS.md / scripts/publish-oss.sh's forbidden-import scan without
+ * pulling the rest of the (public-safe) HTTP client down with it.
+ */
+import { callApi } from './api.js';
+
+// Every non-terminal deployment across every user (not just the caller's
+// own), each carrying its owner's user_email/username so a stuck or
+// forgotten GPU can be identified without logging into that customer's
+// account. Backs `badgr status --admin`.
+export function listAllActiveDeploymentsAdmin(config) {
+  return callApi('/admin/deployments/active', { apiKey: config.apiKey, baseUrl: config.baseUrl, timeoutMs: 15_000 });
+}
+
+// Force-terminate any deployment regardless of owner -- bypasses the
+// per-user ownership check DELETE /deployments/{id} enforces. Backs
+// `badgr down <id> --admin`.
+export function adminTerminateDeployment(config, deploymentId) {
+  return callApi(`/admin/deployments/${deploymentId}`, {
+    method: 'DELETE',
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: 20_000,
+  });
+}

package/src/api.js

@@ -140,7 +140,7 @@ export function runJob(config, body) {
 }
 
 // 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
+// anything (see the backend's own 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) {
@@ -154,7 +154,7 @@ export function quoteRun(config, body) {
 }
 
 // Live, no-provisioning price/capacity check for a GPU dry-run preview (see
-// backend run_serve_routes.py's GET /v1/capacity/suggestions). Used by every
+// the backend's own GET /v1/capacity/suggestions). Used by every
 // GPU-provisioning command's --dry-run to show a real observed rate instead
 // of just the requested config — callers must treat a failure here as
 // non-fatal (best-effort) and never let it block or delay the dry-run.
@@ -179,6 +179,37 @@ export function serveModel(config, body) {
   });
 }
 
+// ---- BYO GPU nodes (POST/GET/DELETE /v1/nodes/*) ----------------------------
+// Server-side handling. A connected node is always private until its
+// owner explicitly changes that (out of scope for this CLI today).
+
+export function connectNode(config, { name, hardware } = {}) {
+  return callApi('/nodes/connect', {
+    method: 'POST', apiKey: config.apiKey, baseUrl: config.baseUrl,
+    body: { name, hardware },
+  });
+}
+
+export function listNodes(config) {
+  return callApi('/nodes', { apiKey: config.apiKey, baseUrl: config.baseUrl });
+}
+
+export function inspectNode(config, nodeId) {
+  return callApi(`/nodes/${encodeURIComponent(nodeId)}`, { apiKey: config.apiKey, baseUrl: config.baseUrl });
+}
+
+export function disableNode(config, nodeId) {
+  return callApi(`/nodes/${encodeURIComponent(nodeId)}/disable`, {
+    method: 'POST', apiKey: config.apiKey, baseUrl: config.baseUrl,
+  });
+}
+
+export function removeNode(config, nodeId) {
+  return callApi(`/nodes/${encodeURIComponent(nodeId)}`, {
+    method: 'DELETE', apiKey: config.apiKey, baseUrl: config.baseUrl,
+  });
+}
+
 // ---- Deployments (POST/GET/DELETE /v1/deployments) --------------------------
 
 export function createDeployment(config, spec) {
@@ -228,33 +259,8 @@ export async function terminateDeployment(config, deploymentId) {
   throw lastErr;
 }
 
-// ---- Admin (michaelhireitem@gmail.com only) ---------------------------------
-// CLI counterparts to the web admin dashboard's own /admin/api/deployments/*
-// routes (main.py) -- those are gated by a browser session cookie the CLI's
-// Authorization: Bearer <api_key> auth can never satisfy, so
-// deployment_routes.py exposes these two under /v1/admin/deployments/*
-// instead, gated by the same is_admin_email() check via API key. A non-admin
-// caller gets a plain 403 from callApi, same as any other access-denied route.
-
-// Every non-terminal deployment across every user (not just the caller's
-// own), each carrying its owner's user_email/username so a stuck or
-// forgotten GPU can be identified without logging into that customer's
-// account. Backs `badgr status --admin`.
-export function listAllActiveDeploymentsAdmin(config) {
-  return callApi('/admin/deployments/active', { apiKey: config.apiKey, baseUrl: config.baseUrl, timeoutMs: 15_000 });
-}
-
-// Force-terminate any deployment regardless of owner -- bypasses the
-// per-user ownership check DELETE /deployments/{id} enforces. Backs
-// `badgr down <id> --admin`.
-export function adminTerminateDeployment(config, deploymentId) {
-  return callApi(`/admin/deployments/${deploymentId}`, {
-    method: 'DELETE',
-    apiKey: config.apiKey,
-    baseUrl: config.baseUrl,
-    timeoutMs: 20_000,
-  });
-}
+// Admin-only operations (badgr status --admin / badgr down --admin) live in
+// ./admin.js, not here -- see that file's header comment for why.
 
 export function restartDeployment(config, deploymentId) {
   return callApi(`/deployments/${deploymentId}/restart`, {

package/src/badgr.js

@@ -14,6 +14,7 @@ import { artifactsCommand }  from './commands/artifacts.js';
 import { serveCommand }      from './commands/serve.js';
 import { modelsCommand }     from './commands/models.js';
 import { capacityCommand }   from './commands/capacity.js';
+import { nodeCommand }       from './commands/node.js';
 import { testCommand }       from './commands/test-run.js';
 import { billingCommand }    from './commands/billing.js';
 import { comfyuiCommand }    from './commands/comfyui.js';
@@ -31,6 +32,7 @@ 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 { checkCommand }      from './commands/check.js';
 import { diagnoseCommand }   from './commands/diagnose.js';
 import { connectCommand }    from './commands/connect.js';
 
@@ -40,14 +42,15 @@ ${chalk.bold('badgr')} — run or serve GPU workloads from one command
 ${chalk.bold('COMMANDS')}
   ${chalk.cyan('badgr login')}               Open a browser to log in (or: badgr login --key <value>)
   ${chalk.cyan('badgr connect <provider>')}  Credential setup (badgr connect anthropic/openai) — also prompted inline by badgr launch if missing
+  ${chalk.cyan('badgr check [path]')}        Validate a workload (project or workload.yaml) and check it against the local GPU — read-only, no login needed
   ${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 cline|claude|codex|opencode|commandcode|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 job <agent> "<instruction>" --check "<command>"')}  Bounded coding-agent job, tracked at /jobs (POST /v1/jobs, type: agent)
   ${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 diagnose "<input>"')}   Run a free Badgr Smoke Test on any GPU issue — GitHub issue, Docker image, log, repo, or text
+  ${chalk.cyan('badgr diagnose "<input>"')}   Run free Badgr Preflight on any GPU issue — GitHub issue, Docker image, log, repo, or text
   ${chalk.cyan('badgr doctor')}              Local GPU / model-fit diagnosis (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
@@ -95,6 +98,8 @@ ${chalk.bold('EXAMPLES')}
   badgr launch cline "Fix the checkout bug"
   badgr launch claude "Fix the checkout bug"
   badgr launch codex "Write tests"
+  badgr launch opencode "Write tests"
+  badgr launch commandcode "Write tests"
   badgr launch playwright "Test the checkout flow"
   badgr launch claude --size medium "Run the complete test suite"
   badgr pull <id>
@@ -102,7 +107,7 @@ ${chalk.bold('EXAMPLES')}
   badgr logs <id>
   badgr receipts <id>
 
-  ${chalk.dim('# Explicit form — advanced escape hatch for anything not in the four workloads above.')}
+  ${chalk.dim('# Explicit form — advanced escape hatch for anything not in the five 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-*):')}
@@ -113,13 +118,13 @@ ${chalk.bold('EXAMPLES')}
   ${chalk.dim('# badgr job — bounded coding-agent job with a pass/fail check, tracked at /jobs:')}
   badgr job cline "Run the Chromium tests and tell me what failed" --check "npm run test:chromium" --max-cost 1
 
-  ${chalk.dim('# Run a free Badgr Smoke Test on any GPU issue (no login needed):')}
+  ${chalk.dim('# Run free Badgr Preflight on any GPU issue (no login needed):')}
   badgr diagnose "https://github.com/org/repo/issues/123"
   badgr diagnose ./error.log
   badgr diagnose --docker ajayrajtp/vllm_gemma412b:latest
   badgr diagnose --repo https://github.com/org/repo
   badgr diagnose --comfyui workflow.json
-  badgr diagnose "https://github.com/org/repo/issues/123" --approve ${chalk.dim('# start a real Badgr Run')}
+  badgr diagnose "https://github.com/org/repo/issues/123" --approve ${chalk.dim('# approve a capped smoke test')}
 
   ${chalk.dim('# Local model-fit and workload diagnosis (no network):')}
   badgr doctor
@@ -237,7 +242,7 @@ ${chalk.bold('badgr launch OPTIONS')}
   --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).
+                         codex/opencode/commandcode/explicit form, browser for playwright (Chromium preinstalled).
 
 ${chalk.bold('badgr artifacts OPTIONS')}
   --output <dir>         Directory to extract into (default: ~/.badgr/artifacts/<id>)
@@ -257,6 +262,11 @@ ${chalk.bold('badgr serve OPTIONS')}
   --hf-file <file>       GGUF filename within that repo, e.g. model.gguf
   --health-path <path>   Readiness path to poll (auto-detected: comfyui → /system_stats, llama.cpp → /health)
   --no-wait              Skip endpoint health check
+  --vllm-arg <arg>       Extra vLLM CLI arg, passed through verbatim (repeatable). e.g.
+                         --vllm-arg --quantization=nvfp4 --vllm-arg --max-model-len=32768
+  -- <args...>           Same as repeated --vllm-arg — everything after a bare -- is passed
+                         through verbatim, e.g. badgr serve MODEL -- --quantization nvfp4
+                         Only applies to the vLLM launch path (ignored for --runtime llama.cpp).
 
 ${chalk.bold('AFTER SERVING')}
   ${chalk.dim('Point any OpenAI client at the returned URL:')}
@@ -281,6 +291,7 @@ async function main() {
   switch (cmd) {
     case 'login':    return loginCommand(chalk, saveConfig, rest);
     case 'connect':  return connectCommand(rest, chalk);
+    case 'check':    return checkCommand(config, rest, chalk);
     case 'detect':   return detectCommand(config, rest, chalk);
     case 'run':      return runCommand(config, rest, chalk);
     case 'launch':   return launchCommand(config, rest, chalk);
@@ -300,6 +311,7 @@ async function main() {
     case 'receipts': return receiptsCommand(config, rest, chalk);
     case 'models':   return modelsCommand(config, chalk);
     case 'capacity': return capacityCommand(config, rest, chalk);
+    case 'node': return nodeCommand(config, rest, chalk);
     case 'test':     return testCommand(config, rest, chalk);
     case 'billing':    return billingCommand(config, rest, chalk);
     case 'comfyui':   return comfyuiCommand(config, rest, chalk);

package/src/catalog.js

@@ -545,6 +545,9 @@ export function buildTemplateFlags(template, overrides) {
   if (overrides.name)             args.push('--name', overrides.name);
   if (overrides.noWait)           args.push('--no-wait');
   if (overrides.persistent)       args.push('--persistent');
+  if (overrides.vllmArgs?.length) {
+    for (const a of overrides.vllmArgs) args.push('--vllm-arg', a);
+  }
 
   if (template.type === 'endpoint' && template.health_path) {
     args.push('--health-path', template.health_path);
@@ -581,6 +584,15 @@ export function parseTemplateOverrides(args) {
       if (idx > 0) overrides.env[kv.slice(0, idx)] = kv.slice(idx + 1);
       continue;
     }
+    if (a === '--') {
+      if (!overrides.vllmArgs) overrides.vllmArgs = [];
+      overrides.vllmArgs.push(...args.slice(i + 1));
+      break;
+    }
+    if (a === '--vllm-arg') {
+      if (!overrides.vllmArgs) overrides.vllmArgs = [];
+      overrides.vllmArgs.push(args[++i]); i++; continue;
+    }
     i++;
   }
   return overrides;

package/src/commands/capacity.js

@@ -12,11 +12,42 @@ function parseCapacityArgs(args) {
     if (args[i] === '--gpu')       { flags.gpu = args[++i]; i++; continue; }
     if (args[i] === '--region')    { flags.region = args[++i]; i++; continue; }
     if (args[i] === '--max-price') { flags.maxPrice = parseFloat(args[++i]); i++; continue; }
+    if (args[i] === '--count')     { flags.count = parseInt(args[++i], 10); i++; continue; }
+    if (args[i] === '--min-ram')   { flags.minRam = parseFloat(args[++i]); i++; continue; }
+    if (args[i] === '--min-vram')  { flags.minVram = parseFloat(args[++i]); i++; continue; }
     i++;
   }
   return flags;
 }
 
+// Renders the machine-spec line for one match, e.g.:
+//   8x GPU  256GB VRAM/GPU  same host  128 cores  2048GB RAM  25Gbps net
+// Only fields the provider actually reported are shown — no fabricated data.
+function formatSpecLine(m, chalk) {
+  const parts = [];
+  if (m.gpu_count && m.gpu_count > 1) parts.push(`${m.gpu_count}x GPU`);
+  if (m.gpu_vram_gb) parts.push(`${m.gpu_vram_gb}GB VRAM/GPU`);
+  if (m.same_host && m.gpu_count > 1) parts.push('same host');
+  if (m.nvlink) parts.push('NVLink');
+  if (m.cpu_cores) parts.push(`${m.cpu_cores} vCPU`);
+  if (m.system_ram_gb) parts.push(`${m.system_ram_gb}GB RAM`);
+  if (m.local_storage_gb) parts.push(`${m.local_storage_gb}GB storage`);
+  if (m.network_up_gbps || m.network_gbps) parts.push(`${m.network_up_gbps ?? m.network_gbps}Gbps net`);
+  if (m.rdma) parts.push('RDMA');
+  if (m.cuda_version) parts.push(`CUDA ${m.cuda_version}`);
+  if (parts.length === 0) return null;
+  return `      ${chalk.dim(parts.join('  ·  '))}`;
+}
+
+// Client-side filters over fields the API doesn't filter on itself (only
+// applied to a field when the match actually reports it — an offer with
+// unknown RAM is never dropped just because we don't know its RAM).
+function matchesSpecFilters(m, flags) {
+  if (flags.minRam !== undefined && m.system_ram_gb !== undefined && m.system_ram_gb < flags.minRam) return false;
+  if (flags.minVram !== undefined && m.gpu_vram_gb !== undefined && m.gpu_vram_gb < flags.minVram) return false;
+  return true;
+}
+
 export async function capacityCommand(config, args, chalk) {
   const flags = parseCapacityArgs(args);
   config = await ensureLoggedInReady(config, chalk);
@@ -35,6 +66,7 @@ export async function capacityCommand(config, args, chalk) {
       const params = new URLSearchParams();
       if (maxPrice !== undefined) params.set('max_price', String(maxPrice));
       if (flags.region) params.set('region', flags.region.toUpperCase());
+      if (flags.count) params.set('count', String(flags.count));
       data = await callApi(`/capacity/auto?${params}`, {
         apiKey: config.apiKey,
         baseUrl: config.baseUrl,
@@ -51,6 +83,8 @@ export async function capacityCommand(config, args, chalk) {
 
     console.log();
     console.log(`  ${chalk.bold('Cheapest available:')} ${chalk.cyan(data.gpu)} in ${data.region}   ${chalk.green('$' + data.price.toFixed(2) + '/hr')}`);
+    const bestSpecLine = formatSpecLine(data, chalk);
+    if (bestSpecLine) console.log(bestSpecLine);
     console.log();
     console.log(`  ${chalk.bold('Run now:')}`);
     console.log(chalk.cyan(`    badgr run python train.py`));
@@ -66,6 +100,7 @@ export async function capacityCommand(config, args, chalk) {
   const params = new URLSearchParams({ gpu });
   if (maxPrice !== undefined) params.set('max_price', String(maxPrice));
   if (flags.region) params.set('region', flags.region.toUpperCase());
+  if (flags.count) params.set('count', String(flags.count));
 
   console.log(chalk.bold(`\nCapacity: ${gpu}\n`));
   process.stdout.write(chalk.dim('  Checking...\n'));
@@ -81,11 +116,13 @@ export async function capacityCommand(config, args, chalk) {
     process.exit(1);
   }
 
-  const matches = data.matches ?? [];
+  const matches = (data.matches ?? []).filter((m) => matchesSpecFilters(m, flags));
   if (matches.length > 0) {
     console.log(chalk.bold('\n  Available now:\n'));
     for (const m of matches) {
       console.log(`    ${chalk.green('●')} ${m.gpu} in ${m.region}   ${chalk.green('$' + m.price.toFixed(2) + '/hr')}`);
+      const specLine = formatSpecLine(m, chalk);
+      if (specLine) console.log(specLine);
     }
     console.log();
     const regionFlag = flags.region ? ` --region ${flags.region.toUpperCase()}` : '';

package/src/commands/check.js

@@ -0,0 +1,127 @@
+import { existsSync, statSync } from 'fs';
+import { detectWorkload } from '../detect.js';
+import { parseWorkloadYaml, WorkloadSpecError } from '../workloadSpec.js';
+import { runGpuDoctor } from '../gpuDoctor/doctor.js';
+import { renderDetectReport, suggestedCommandLine } from './detect.js';
+
+const CHECK_HELP = `
+Validate a workload before you run it: identify what it is, check it's
+well-formed, and check it against the local GPU/runtime — all read-only,
+no login needed.
+
+Usage:
+  badgr check [path]
+  badgr check workload.yaml
+  badgr check --json
+
+Flags:
+  --json    Machine-readable JSON output
+
+path defaults to "." — a project directory or a batch workload.yml file.
+Never mutates the machine: no restarts, no driver/CUDA changes, no installs.
+
+Full reference: docs/gpu-doctor.md, docs/badgr-batch.md`;
+
+function isWorkloadYaml(target) {
+  return /\.ya?ml$/i.test(target) && existsSync(target) && statSync(target).isFile();
+}
+
+// Routes a check result to the next Badgr command family (run/serve/job/batch),
+// matching the badgr-serve/-run/-agent-jobs/-ai-api conversion paths in
+// docs/OPEN_SOURCE_SPLIT.md's "badgr check" hero demo.
+function nextStep(kind, detectReport) {
+  if (kind === 'workload-yaml') {
+    return 'badgr batch run <workload.yaml>';
+  }
+  if (detectReport?.workloadType === 'endpoint') {
+    return 'badgr serve <model>';
+  }
+  return suggestedCommandLine(detectReport || {});
+}
+
+export async function checkCommand(config, args, chalk) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(CHECK_HELP);
+    return;
+  }
+  const json = args.includes('--json');
+  const target = args.find(a => !a.startsWith('--')) || '.';
+
+  const result = { target, kind: null, workload: null, detect: null, gpu: null, errors: [] };
+
+  if (isWorkloadYaml(target)) {
+    result.kind = 'workload-yaml';
+    try {
+      result.workload = parseWorkloadYaml(target);
+    } catch (err) {
+      const message = err instanceof WorkloadSpecError ? err.message : `Could not parse ${target}: ${err.message}`;
+      result.errors.push(message);
+    }
+  } else {
+    result.kind = 'project';
+    result.detect = detectWorkload(target);
+    if (result.detect.error) result.errors.push(result.detect.error);
+  }
+
+  try {
+    result.gpu = await runGpuDoctor({}, {});
+  } catch (err) {
+    // GPU probing is best-effort here — a missing/unreadable GPU shouldn't
+    // block workload validation, which is the more common local check.
+    result.gpu = null;
+  }
+
+  result.nextCommand = result.errors.length === 0 ? nextStep(result.kind, result.detect) : null;
+
+  if (json) {
+    console.log(JSON.stringify({
+      target: result.target,
+      kind: result.kind,
+      valid: result.errors.length === 0,
+      errors: result.errors,
+      workload: result.workload,
+      detect: result.detect,
+      gpu_verdict: result.gpu?.verdictSlug ?? null,
+      next_command: result.nextCommand,
+    }, null, 2));
+    if (result.errors.length > 0) process.exitCode = 1;
+    return result;
+  }
+
+  console.log();
+  if (result.kind === 'workload-yaml') {
+    if (result.errors.length > 0) {
+      console.log(chalk.red(`✗ ${target} is invalid:`));
+      for (const e of result.errors) console.log(chalk.red(`  - ${e}`));
+    } else {
+      console.log(chalk.green(`✓ ${target} is a valid workload`));
+      console.log(`  name: ${result.workload.name}`);
+      console.log(`  image: ${result.workload.image}`);
+      console.log(`  command: ${result.workload.command.join(' ')}`);
+      console.log(`  max_cost: $${result.workload.maxCost}`);
+      console.log(`  max_runtime_minutes: ${result.workload.maxRuntimeMinutes}`);
+    }
+  } else {
+    if (result.errors.length > 0) {
+      console.log(chalk.red(`✗ ${result.errors[0]}`));
+    } else {
+      console.log(renderDetectReport(result.detect, chalk));
+    }
+  }
+
+  if (result.gpu) {
+    console.log();
+    console.log(chalk.bold('Local GPU/runtime:'));
+    console.log(`  ${result.gpu.verdict}: ${result.gpu.likelyCause}`);
+  }
+
+  if (result.nextCommand) {
+    console.log();
+    console.log(chalk.bold('Next step:'));
+    console.log(`  ${chalk.cyan(result.nextCommand)}`);
+  }
+  console.log();
+
+  if (result.errors.length > 0) process.exitCode = 1;
+  return result;
+}

package/src/commands/connect.js

@@ -80,7 +80,8 @@ export async function connectCommand(args, chalk, deps = {}) {
   console.log(chalk.green(`\n  ✓ ${alreadyConnected ? 'Updated' : 'Connected'} ${provider}`));
   console.log(chalk.dim(`  Stored in ${CREDENTIALS_FILE} (owner-only file permissions)`));
   const usageHint = provider === 'anthropic' ? 'badgr launch claude "<task>"'
-    : provider === 'openai' ? 'badgr launch codex "<task>"'
-    : `badgr launch cline/claude/codex --provider ${provider} --model <model-id> "<task>"`;
+    : provider === 'openai' ? 'badgr launch codex/opencode "<task>"'
+    : provider === 'commandcode' ? 'badgr launch commandcode "<task>"'
+    : `badgr launch cline/claude/codex/opencode --provider ${provider} --model <model-id> "<task>"`;
   console.log(chalk.dim(`  Used automatically by: ${usageHint}\n`));
 }