badgr-cli 1.0.31 → 1.0.32

package/HOW_IT_WORKS.md

@@ -11,7 +11,7 @@ npm install -g badgr-cli
 badgr login
 ```
 
-`badgr login` prompts for your API key and base URL, then writes them to `~/.gpu/config.json`. Every subsequent command reads that file — no env vars required.
+`badgr login` prompts for your API key and base URL, then writes them to `~/.badgr/config.json`. Every subsequent command reads that file — no env vars required.
 
 ---
 
@@ -142,7 +142,7 @@ badgr receipts [n]        # default: last 10
 
 Shows two sets of receipts:
 
-1. **CLI action receipts** — every `badgr serve` / `badgr down` recorded locally in `~/.gpu/deployments.json`, with provider, retries, latency, and cost.
+1. **CLI action receipts** — every `badgr serve` / `badgr down` recorded locally in `~/.badgr/deployments.json`, with provider, retries, latency, and cost.
 2. **Inference receipts** — per-request records fetched from `GET /v1/receipts` on the API (requires `badgr login`).
 
 Every action — including failures — generates a receipt. Receipt IDs are printed on every command output so you can look them up later.
@@ -202,10 +202,10 @@ GPU type aliases are normalized automatically: `rtx-4090`, `rtx4090`, `4090`, `R
 
 ## Local State
 
-All CLI state lives in `~/.gpu/`:
+All CLI state lives in `~/.badgr/`:
 
 ```
-~/.gpu/
+~/.badgr/
   config.json          API key + base URL
   deployments.json     Active deployments + receipt log (last 200)
 ```

package/README.md

@@ -14,16 +14,19 @@ npm install -g badgr-cli
 # 1. Authenticate once
 badgr login
 
-# 2. Serve an OpenAI-compatible inference endpoint
-badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S
+# 2. Verify the stack end-to-end
+badgr test
 
-# 3. Use the endpoint with any OpenAI SDK client
-#    client = OpenAI(api_key="sk-...", base_url="https://dep-a1b2c3.api.badgr.ai/v1")
+# 3. Serve an OpenAI-compatible inference endpoint
+badgr serve meta-llama/Llama-3.1-8B-Instruct
 
-# 4. View cost, route, and retry receipts
+# 4. Use the endpoint with any OpenAI SDK client
+#    client = OpenAI(api_key="sk-...", base_url="https://dep-a1b2c3.aibadgr.com/v1")
+
+# 5. View cost, route, and retry receipts
 badgr receipts
 
-# 5. Stop billing
+# 6. Stop billing
 badgr down <deployment-id>
 ```
 
@@ -36,9 +39,13 @@ badgr down <deployment-id>
 | `badgr login` | Save API key to `~/.badgr/config.json` |
 | `badgr serve <model>` | Start a persistent OpenAI-compatible endpoint |
 | `badgr run <command>` | Run a one-off GPU job (any container command) |
+| `badgr status` | Show what's running and what's billing |
 | `badgr down <id>` | Terminate a deployment — stops billing immediately |
 | `badgr logs <id>` | Fetch log output from a deployment |
 | `badgr receipts [n]` | Cost, route, and retry receipts (default 10) |
+| `badgr capacity` | Check available GPU capacity right now |
+| `badgr billing` | Show balance and add funds |
+| `badgr test` | Run an end-to-end test (provision → run → teardown) |
 
 `badgr serve` — for anything that needs a persistent endpoint: LLM serving, embeddings, image generation APIs, transcription APIs.
 
@@ -54,37 +61,49 @@ badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S --region EU
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--gpu <type>` | RTX_4090 | GPU: RTX_4090, L40S, A6000, A100, H100 |
-| `--region <region>` | — | Optional region preference. If omitted, Badgr chooses best available capacity. |
+| `--gpu <type>` | auto | GPU type — Badgr infers from model size if omitted. Options: RTX_4090, L40S, A6000, A100, H100 |
+| `--image <img>` | — | Serve a custom container instead of a HuggingFace model |
+| `--task <task>` | — | vLLM task override, e.g. `embed` for embedding models |
+| `--env KEY=VALUE` | — | Environment variable (repeatable) |
+| `--tier 1\|2` | 1 | `1` = managed provider routing (default); `2` = marketplace routing, lower cost |
 | `--count <n>` | 1 | Number of GPUs (1–8) |
+| `--region US\|EU\|AU` | — | Optional region preference. If omitted, Badgr chooses best available capacity. |
 | `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--dry-run` | — | Preview routing without provisioning |
+| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
+| `--health-path <path>` | auto | Readiness path to poll (auto-detected for ComfyUI → `/system_stats`) |
+| `--no-wait` | — | Skip endpoint health check and return immediately |
 
 ---
 
 ## `badgr run` options
 
 ```bash
-badgr run python train.py --gpu A100 --env HF_TOKEN=$HF_TOKEN
+badgr run python train.py --gpu A100 --env HF_TOKEN=$HF_TOKEN --max-runtime 60
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--gpu <type>` | RTX_4090 | GPU type |
+| `--gpu <type>` | auto | GPU type — Badgr picks best available if omitted |
 | `--image <img>` | python:3.11-slim | Docker image |
 | `--env KEY=VALUE` | — | Environment variable (repeatable) |
-| `--region <region>` | — | Optional region preference. If omitted, Badgr chooses best available capacity. |
+| `--tier 1\|2` | 1 | `1` = managed provider routing (default); `2` = marketplace routing, lower cost |
+| `--count <n>` | 1 | Number of GPUs |
+| `--region US\|EU\|AU` | — | Optional region preference. If omitted, Badgr chooses best available capacity. |
 | `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--detach` | — | Launch and return immediately |
+| `--max-runtime <min>` | — | Auto-stop after N minutes (recommended) |
+| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
+| `--detach` | — | Launch and return immediately, don't stream logs |
 
 ---
 
 ## Routing
 
-Badgr automatically searches available GPU capacity across its verified compute network.
-
 Badgr automatically searches verified GPU capacity and chooses the best eligible route for your GPU type, workload, price cap, and optional region preference.
 
+**Tier 1** (default) — managed provider routing with guaranteed SLAs.
+
+**Tier 2** — marketplace routing for lower-cost options when Tier 1 capacity is constrained.
+
 Preview before provisioning:
 
 ```bash
@@ -115,7 +134,7 @@ from openai import OpenAI
 
 client = OpenAI(
     api_key="your-badgr-api-key",
-    base_url="https://dep-a1b2c3.api.badgr.ai/v1",  # from badgr serve output
+    base_url="https://dep-a1b2c3.aibadgr.com/v1",  # from badgr serve output
 )
 resp = client.chat.completions.create(
     model="meta-llama/Llama-3.1-8B-Instruct",
@@ -127,7 +146,7 @@ resp = client.chat.completions.create(
 import OpenAI from "openai";
 const client = new OpenAI({
   apiKey: process.env.BADGR_API_KEY,
-  baseURL: "https://dep-a1b2c3.api.badgr.ai/v1",
+  baseURL: "https://dep-a1b2c3.aibadgr.com/v1",
 });
 ```
 
@@ -150,4 +169,4 @@ Prices shown are estimated Badgr rates. Final $/GPU-hour is confirmed before pro
 ## Requirements
 
 - Node.js 18+
-- A Badgr account — sign up at [badgr.ai](https://badgr.ai)
+- A Badgr account — sign up at [aibadgr.com](https://aibadgr.com)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "badgr-cli",
-  "version": "1.0.31",
-  "description": "Badgr — run or serve GPU workloads from one command",
+  "version": "1.0.32",
+  "description": "Badgr, run or serve GPU workloads from one command",
   "type": "module",
   "bin": {
-    "badgr": "./src/badgr.js"
+    "badgr": "src/badgr.js"
   },
   "scripts": {
     "start": "node src/badgr.js",
@@ -21,6 +21,14 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "keywords": ["gpu", "cli", "ai", "compute", "modal", "gateway", "openai"],
+  "keywords": [
+    "gpu",
+    "cli",
+    "ai",
+    "compute",
+    "modal",
+    "gateway",
+    "openai"
+  ],
   "license": "MIT"
 }

package/src/api.js

@@ -1,16 +1,98 @@
-export async function callApi(path, { method = 'GET', apiKey, baseUrl, body } = {}) {
+const DEBUG = process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true';
+
+function dbg(...args) {
+  if (DEBUG) console.error('[badgr:debug]', ...args);
+}
+
+// Redact env values so secrets never appear in debug output.
+function redactBody(body) {
+  if (!body || !body.env || typeof body.env !== 'object') return body;
+  return { ...body, env: Object.fromEntries(Object.keys(body.env).map(k => [k, '***'])) };
+}
+
+export async function callApi(path, { method = 'GET', apiKey, baseUrl, body, timeoutMs = 15_000 } = {}) {
   const url = `${baseUrl}${path}`;
-  const res = await fetch(url, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${apiKey}`,
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  const keyPreview = apiKey ? `${apiKey.slice(0, 4)}…` : '(not set)';
+
+  dbg(`${method} ${url}`);
+  dbg(`API key: ${keyPreview}`);
+  if (body !== undefined) dbg('Request body:', JSON.stringify(redactBody(body)));
+
+  let res;
+  const startMs = Date.now();
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (cause) {
+    const elapsed = Date.now() - startMs;
+    dbg(`Fetch threw after ${elapsed}ms:`, cause);
+    const msg = cause?.message ?? String(cause);
+    const code = cause?.cause?.code ?? cause?.code ?? '';
+    const hint =
+      (code === 'ECONNREFUSED' || msg.includes('ECONNREFUSED'))
+        ? `\n  Hint: Connection refused — is the server running at ${baseUrl}?` :
+      (code === 'ENOTFOUND' || msg.includes('ENOTFOUND'))
+        ? `\n  Hint: DNS lookup failed for ${baseUrl}\n  Check your internet or set BADGR_API_URL to the correct host` :
+      (code === 'ETIMEDOUT' || msg.includes('ETIMEDOUT') || cause?.name === 'TimeoutError')
+        ? `\n  Hint: Request timed out — server may be overloaded` :
+      (msg.includes('fetch failed') || msg === 'fetch failed')
+        ? `\n  Hint: Network error reaching ${url}\n  • Check internet connection\n  • Run: badgr config  (verify baseUrl)\n  • Try: BADGR_DEBUG=1 badgr run … for full details\n  • Test: curl -v ${baseUrl}/models` :
+        `\n  Hint: Check your network and that BADGR_API_URL is correct (${baseUrl})`;
+    throw new Error(`Cannot reach ${url} (${msg})${hint}`);
+  }
+
+  const elapsed = Date.now() - startMs;
+  dbg(`Response: HTTP ${res.status} in ${elapsed}ms`);
+
   if (!res.ok) {
-    const text = await res.text().catch(() => '');
-    throw new Error(`${method} ${path} → ${res.status}: ${text}`);
+    let detail = '';
+    let rawBody = '';
+    let errorData = null;
+    try {
+      rawBody = await res.text();
+      dbg('Error response body:', rawBody);
+      const json = JSON.parse(rawBody);
+      errorData = json;
+      detail = json?.detail ?? json?.message ?? json?.error ?? rawBody;
+    } catch {
+      detail = rawBody || res.statusText || '';
+    }
+    const isCapacityError = errorData?.code === 'NO_CAPACITY_MATCH';
+    if (res.status === 402) {
+      const d = errorData?.detail ?? errorData ?? {};
+      const detailObj = typeof d === 'object' ? d : {};
+      const balanceUsd = typeof detailObj.balance_usd === 'number' ? detailObj.balance_usd : null;
+      const requiredUsd = typeof detailObj.required_usd === 'number' ? detailObj.required_usd : null;
+      const topupUrl = detailObj.topup_url || 'https://aibadgr.com/dashboard#billing';
+
+      let msg = '\nPayment required.\n';
+      if (balanceUsd !== null) msg += `Your balance is $${balanceUsd.toFixed(2)}.`;
+      if (requiredUsd !== null) msg += ` This job needs a $${requiredUsd.toFixed(2)} reserve.`;
+      msg += '\n\nAdd balance:\n  ' + topupUrl + '\n';
+      const err = new Error(msg);
+      err.errorData = errorData;
+      err.httpStatus = 402;
+      err.isPaymentRequired = true;
+      throw err;
+    }
+    const hint =
+      res.status === 401 ? '\n  Hint: Invalid or missing API key — run: badgr login' :
+      res.status === 403 ? '\n  Hint: Access denied — check your API key permissions' :
+      res.status === 404 ? `\n  Hint: Endpoint not found — check BADGR_API_URL (currently: ${baseUrl})` :
+      (res.status === 502 || res.status === 503) && !isCapacityError
+        ? '\n  Hint: Server error — no GPU capacity available or backend is down' :
+      '';
+    const err = new Error(`${method} ${path} → HTTP ${res.status}: ${detail}${hint}`);
+    err.errorData = errorData;
+    err.httpStatus = res.status;
+    throw err;
   }
   return res.json();
 }
@@ -23,6 +105,7 @@ export function runJob(config, body) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body,
+    timeoutMs: 30_000,
   });
 }
 
@@ -32,6 +115,7 @@ export function serveModel(config, body) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body,
+    timeoutMs: 30_000,
   });
 }
 
@@ -43,27 +127,53 @@ export function createDeployment(config, spec) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body: spec,
+    timeoutMs: 30_000,
   });
 }
 
 export function listDeployments(config) {
-  return callApi('/deployments', { apiKey: config.apiKey, baseUrl: config.baseUrl });
+  return callApi('/deployments', { apiKey: config.apiKey, baseUrl: config.baseUrl, timeoutMs: 10_000 });
 }
 
 export function getDeployment(config, deploymentId) {
-  return callApi(`/deployments/${deploymentId}`, { apiKey: config.apiKey, baseUrl: config.baseUrl });
-}
-
-export function terminateDeployment(config, deploymentId) {
   return callApi(`/deployments/${deploymentId}`, {
-    method: 'DELETE',
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
   });
 }
 
+/**
+ * Terminate a deployment with up to 3 retries on transient failures.
+ * Throws on final failure so callers can decide whether to continue.
+ */
+export async function terminateDeployment(config, deploymentId) {
+  const MAX_ATTEMPTS = 3;
+  let lastErr;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      return await callApi(`/deployments/${deploymentId}`, {
+        method: 'DELETE',
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        timeoutMs: 20_000,
+      });
+    } catch (err) {
+      lastErr = err;
+      if (attempt < MAX_ATTEMPTS) {
+        await new Promise(r => setTimeout(r, attempt * 1000));
+      }
+    }
+  }
+  throw lastErr;
+}
+
 export function getDeploymentLogs(config, deploymentId) {
-  return callApi(`/deployments/${deploymentId}/logs`, { apiKey: config.apiKey, baseUrl: config.baseUrl });
+  return callApi(`/deployments/${deploymentId}/logs`, {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
+  });
 }
 
 // ---- Receipts ---------------------------------------------------------------
@@ -78,6 +188,7 @@ export function listReceipts(config, { limit = 20, status, fromTs, toTs } = {})
   return callApi(`/receipts${qs ? `?${qs}` : ''}`, {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
   });
 }
 
@@ -85,13 +196,14 @@ export function getReceipt(config, receiptId) {
   return callApi(`/receipts/${receiptId}`, {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
   });
 }
 
 // ---- Inference --------------------------------------------------------------
 
 export function listModels(config) {
-  return callApi('/models', { apiKey: config.apiKey, baseUrl: config.baseUrl });
+  return callApi('/models', { apiKey: config.apiKey, baseUrl: config.baseUrl, timeoutMs: 10_000 });
 }
 
 export function chatCompletion(config, messages, options = {}) {
@@ -101,6 +213,7 @@ export function chatCompletion(config, messages, options = {}) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body: { model: model ?? config.defaultModel, messages, stream },
+    timeoutMs: 30_000,
   });
 }
 
@@ -112,9 +225,14 @@ export function submitJob(config, job) {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     body: job,
+    timeoutMs: 30_000,
   });
 }
 
 export function getJobStatus(config, jobId) {
-  return callApi(`/jobs/${jobId}`, { apiKey: config.apiKey, baseUrl: config.baseUrl });
+  return callApi(`/jobs/${jobId}`, {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
+  });
 }

package/src/badgr.js

@@ -10,53 +10,94 @@ import { receiptsCommand } from './commands/receipts.js';
 import { runCommand }      from './commands/run.js';
 import { serveCommand }    from './commands/serve.js';
 import { modelsCommand }   from './commands/models.js';
+import { capacityCommand } from './commands/capacity.js';
+import { testCommand }     from './commands/test-run.js';
+import { billingCommand }  from './commands/billing.js';
 
 const HELP = `
 ${chalk.bold('badgr')} — run or serve GPU workloads from one command
 
-${chalk.bold('CORE COMMANDS')}
-  ${chalk.cyan('badgr login')}                         Authenticate (save API key to ~/.badgr/config.json)
-  ${chalk.cyan('badgr run <cmd...> --gpu <type>')}     Run a one-off GPU job
-  ${chalk.cyan('badgr serve <model> --gpu <type>')}    Serve a model (OpenAI-compatible endpoint)
-  ${chalk.cyan('badgr status')}                        Show active deployments + endpoint URLs
-  ${chalk.cyan('badgr logs <id>')}                     Stream logs for a deployment
-  ${chalk.cyan('badgr down <id>')}                     Terminate a deployment (stop billing)
-  ${chalk.cyan('badgr receipts [<id>|<n>]')}           Show receipts — pass ID for single, number for list
+${chalk.bold('COMMANDS')}
+  ${chalk.cyan('badgr login')}               Authenticate with your API key
+  ${chalk.cyan('badgr run <command>')}       Run a one-off GPU job
+  ${chalk.cyan('badgr serve <model>')}       Serve a model with an OpenAI-compatible endpoint
+  ${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 down <id>')}           Stop a deployment and end billing
+  ${chalk.cyan('badgr receipts')}            Show cost history
+  ${chalk.cyan('badgr test')}               Run an end-to-end test (provision → run → teardown)
+  ${chalk.cyan('badgr capacity')}            Check what GPU capacity is available right now
+  ${chalk.cyan('badgr billing')}             Show balance and add funds
 
-${chalk.bold('badgr run OPTIONS')}
-  --gpu <type>        GPU: RTX_4090, A100, L40S, H100  (default: RTX_4090)
-  --image <image>     Docker image (default: python:3.11-slim)
-  --count <n>         GPU count (default: 1)
-  --region US|EU|AU   Region preference (default: US)
-  --max-price <$/hr>  Hard spend cap per GPU-hour
-  --name <name>       Job name (auto-generated if omitted)
+${chalk.bold('EXAMPLES')}
+  ${chalk.dim('# Verify the stack works end-to-end:')}
+  badgr test
 
-${chalk.bold('badgr serve OPTIONS')}
-  --gpu <type>        GPU: L40S, A100, H100, RTX_4090  (default: L40S)
-  --count <n>         GPU count (default: 1)
-  --region US|EU|AU   Region preference (default: US)
-  --max-price <$/hr>  Hard spend cap per GPU-hour
-  --name <name>       Deployment name (auto-generated if omitted)
+  ${chalk.dim('# Tier 1 — managed provider routing (default):')}
+  badgr run python train.py
+  badgr serve meta-llama/Llama-3.1-8B-Instruct
 
-${chalk.bold('EXAMPLES')}
-  badgr login
+  ${chalk.dim('# Tier 2 — marketplace routing, lower-cost options:')}
+  badgr run python train.py --tier 2
+  badgr serve meta-llama/Llama-3.1-8B-Instruct --tier 2
+
+  ${chalk.dim('# Pin a specific GPU:')}
   badgr run python train.py --gpu A100
-  badgr run --image my/image:latest --gpu L40S
   badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S
-  badgr serve mistralai/Mistral-7B-v0.1 --gpu RTX_4090
+
+  ${chalk.dim('# Pass environment variables:')}
+  badgr run python train.py --env HF_TOKEN=$HF_TOKEN --env DATASET=my/data
+
+  ${chalk.dim('# Serve an embedding model:')}
+  badgr serve BAAI/bge-large-en-v1.5 --task embed
+
+  ${chalk.dim('# Serve a custom container (Diffusers, Whisper, etc.):')}
+  badgr serve --image ghcr.io/my-org/diffusers-api:latest --gpu L40S --env MODEL_ID=flux
+
+  ${chalk.dim('# Add safety caps:')}
+  badgr run python train.py --max-runtime 60 --max-cost 5
+
+  ${chalk.dim('# Manage a running deployment:')}
   badgr status
-  badgr logs dep_abc123
-  badgr down dep_abc123
-  badgr receipts
-  badgr receipts dep_abc123
-
-${chalk.bold('OPENAI-COMPATIBLE SERVING')}
-  ${chalk.dim('After `badgr serve`, point any OpenAI client at the returned URL:')}
-  ${chalk.dim('  client = OpenAI(api_key="sk-...", base_url="https://api.badgr.ai/v1")')}
-  ${chalk.dim('  client.chat.completions.create(model="dep_xxx", messages=[...])')}
-
-${chalk.bold('ROUTING')}
-  ${chalk.dim('Badgr automatically selects best available GPU capacity for your request.')}
+  badgr logs dep-abc123
+  badgr down dep-abc123
+  badgr receipts dep-abc123
+
+${chalk.bold('badgr run OPTIONS')}
+  --gpu <type>           GPU type (default: auto — Badgr picks best available)
+  --tier 1               Managed provider routing (default)
+  --tier 2               Marketplace provider routing, lower-cost options
+  --image <image>        Docker image (default: python:3.11-slim)
+  --env KEY=VALUE        Set an environment variable (repeatable)
+  --count <n>            Number of GPUs (default: 1)
+  --region US|EU|AU      Region preference
+  --max-price <$/hr>     Hard spend cap per GPU-hour
+  --max-runtime <min>    Auto-stop after N minutes (recommended)
+  --max-cost <$>         Auto-stop when spend reaches this amount
+  --detach               Return immediately, don't stream logs
+
+${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
+  --task <task>          vLLM task override, e.g. embed for embedding models
+  --env KEY=VALUE        Set an environment variable (repeatable)
+  --tier 1               Managed provider routing (default)
+  --tier 2               Marketplace provider routing, lower-cost options
+  --count <n>            Number of GPUs (default: 1)
+  --region US|EU|AU      Region preference
+  --max-price <$/hr>     Hard spend cap per GPU-hour
+  --health-path <path>   Readiness path to poll (auto-detected for comfyui → /system_stats)
+  --no-wait              Skip endpoint health check
+
+${chalk.bold('AFTER SERVING')}
+  ${chalk.dim('Point any OpenAI client at the returned URL:')}
+  ${chalk.dim('  from openai import OpenAI')}
+  ${chalk.dim('  client = OpenAI(base_url="<endpoint url>", api_key="<your key>")')}
+  ${chalk.dim('  client.chat.completions.create(model="<model>", messages=[...])')}
+
+${chalk.bold('DEBUG')}
+  ${chalk.dim('BADGR_DEBUG=1 badgr run python train.py   # full request/response trace')}
+  ${chalk.dim('badgr config                              # show current API config')}
 `;
 
 async function main() {
@@ -77,6 +118,9 @@ async function main() {
     case 'down':     return downCommand(config, rest, chalk);
     case 'receipts': return receiptsCommand(config, rest, chalk);
     case 'models':   return modelsCommand(config, chalk);
+    case 'capacity': return capacityCommand(config, rest, chalk);
+    case 'test':     return testCommand(config, rest, chalk);
+    case 'billing':  return billingCommand(config, rest, chalk);
     // legacy aliases kept for compatibility
     case 'up':       return upCommand(config, rest, chalk);
     case 'config': {

package/src/commands/billing.js

@@ -0,0 +1,93 @@
+import { execSync } from 'child_process';
+import { requireApiKey } from '../config.js';
+import { callApi } from '../api.js';
+
+const BILLING_HELP = `
+badgr billing — manage your AI Badgr balance
+
+COMMANDS
+  badgr billing status         Show current balance
+  badgr billing add <amount>   Open checkout to add balance (minimum $10)
+
+EXAMPLES
+  badgr billing status
+  badgr billing add 10
+  badgr billing add 20
+  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 {
+    const apiUrl = config.baseUrl.replace('/v1', '').replace('/api/v1', '');
+    const data = await callApi('/api/me', {
+      apiKey: config.apiKey,
+      baseUrl: apiUrl,
+    });
+    const credits = data.credits ?? 0;
+    const balanceUsd = (credits / 10000).toFixed(2);
+    console.log();
+    console.log(chalk.bold('  Balance'));
+    console.log(`  ${chalk.bold(chalk.blue(`$${balanceUsd}`))}`);
+    console.log();
+    if (credits === 0) {
+      console.log(chalk.yellow('  Balance is $0.00. Add balance before making API calls or running GPU jobs.'));
+      console.log(chalk.dim('  Add balance: badgr billing add 10'));
+      console.log(chalk.dim('  Or visit:    https://aibadgr.com/billing/top-up'));
+    }
+    console.log();
+  } catch (err) {
+    if (err.isPaymentRequired) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    console.error(chalk.red('  Could not fetch balance: ' + err.message));
+    process.exit(1);
+  }
+}
+
+async function billingAdd(config, amount, chalk) {
+  requireApiKey(config);
+  const amountInt = parseInt(amount, 10);
+  if (!amountInt || amountInt < 10) {
+    console.error(chalk.red('  Minimum top-up is $10. Example: badgr billing add 10'));
+    process.exit(1);
+  }
+
+  const url = `https://aibadgr.com/dashboard#billing`;
+  console.log();
+  console.log(chalk.bold(`  Opening dashboard billing to add $${amountInt}...`));
+  console.log();
+  console.log(`  ${chalk.dim(url)}`);
+  console.log();
+  openBrowser(url);
+  console.log(chalk.dim('  Complete payment in your browser, then rerun your command.'));
+  console.log();
+}
+
+export async function billingCommand(config, args, chalk) {
+  const [sub, ...rest] = args;
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(BILLING_HELP);
+    return;
+  }
+
+  if (sub === 'status') return billingStatus(config, chalk);
+  if (sub === 'add') return billingAdd(config, rest[0], chalk);
+
+  console.error(chalk.red(`  Unknown billing command: ${sub}`));
+  console.log(chalk.dim('  Run: badgr billing --help'));
+  process.exit(1);
+}