badgr-cli 1.0.0

package/src/commands/up.js

@@ -0,0 +1,134 @@
+import { parseSpec, validateSpec, specLines } from '../spec.js';
+import { getRoutePlan } from '../router.js';
+import { requireApiKey } from '../config.js';
+import { generateDeploymentId, generateReceiptId, addDeployment, addReceipt } from '../store.js';
+import { createDeployment } from '../api.js';
+
+const OVERHEAD_PCT = 0.25;
+
+function printRoutePlan(plan, chalk) {
+  const { lane1, lane2, cheapestRate, costWithOverhead, canonical } = plan;
+
+  console.log(chalk.bold('  Lane 1 — Own GPU Hosts'));
+  console.log(`  ${'─'.repeat(40)}`);
+  console.log(chalk.dim(`  ${lane1.description}`));
+  console.log();
+
+  console.log(chalk.bold('  Lane 2 — Overflow Providers  (cheapest-first)'));
+  console.log(`  ${'─'.repeat(40)}`);
+  if (lane2.length === 0) {
+    console.log(chalk.yellow(`  No pricing data for ${canonical}`));
+  } else {
+    lane2.forEach((p, i) => {
+      const arrow = i === 0 ? chalk.green(' ← primary') : '';
+      console.log(
+        `  ${String(i + 1)}. ${p.provider.padEnd(12)} ${canonical.padEnd(10)}` +
+        `  $${p.ratePerHour.toFixed(2)}/hr` +
+        `  reliability: ${Math.round(p.reliability * 100)}%${arrow}`
+      );
+    });
+    console.log();
+    console.log(`  Estimated range: $${cheapestRate.toFixed(2)}–$${lane2[lane2.length - 1].ratePerHour.toFixed(2)}/hr`);
+    console.log(chalk.dim(`  With 25% overhead (startup risk + badgr margin): ~$${costWithOverhead.toFixed(2)}/hr`));
+  }
+  console.log();
+  console.log(chalk.dim('  Remove --dry-run to provision.'));
+  console.log();
+}
+
+export async function upCommand(config, args, chalk) {
+  const spec = parseSpec(args);
+  const errors = validateSpec(spec);
+
+  if (errors.length > 0) {
+    errors.forEach(e => console.error(chalk.red(`  ✗ ${e}`)));
+    return;
+  }
+
+  // ── Dry-run: show route plan and exit ─────────────────────────────────────
+  if (spec.dryRun) {
+    console.log(chalk.bold('\n🔍 Dry Run — Route Plan\n'));
+    console.log(chalk.bold('  Spec'));
+    console.log(`  ${'─'.repeat(40)}`);
+    specLines(spec).forEach(l => console.log(`  ${l}`));
+    console.log();
+    const plan = getRoutePlan(spec.gpu, spec.count);
+    printRoutePlan(plan, chalk);
+    return;
+  }
+
+  // ── Provision via backend API ─────────────────────────────────────────────
+  requireApiKey(config);
+
+  console.log(chalk.bold('\n🚀 Provisioning\n'));
+  console.log(chalk.bold('  Spec'));
+  console.log(`  ${'─'.repeat(40)}`);
+  specLines(spec).forEach(l => console.log(`  ${l}`));
+  console.log();
+  console.log(chalk.dim('  Routing through GPU.AI gateway (lane 1 → lane 2 → lane 3)...'));
+
+  let dep;
+  try {
+    dep = await createDeployment(config, {
+      workload_type: spec.type,
+      model:         spec.model,
+      image:         spec.image,
+      gpu_type:      spec.gpu,
+      gpu_count:     spec.count,
+      region:        spec.region,
+      max_price_per_hour: spec.maxPrice ?? undefined,
+      name:          spec.name ?? undefined,
+    });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Provisioning failed: ${err.message}\n`));
+    return;
+  }
+
+  // Mirror to local store so gpu status/logs/receipts work offline
+  const localDep = {
+    id:           dep.deployment_id,
+    name:         dep.name,
+    type:         dep.workload_type,
+    model:        dep.model,
+    image:        dep.image,
+    gpu:          dep.gpu_type,
+    count:        dep.gpu_count,
+    region:       dep.region,
+    status:       dep.status,
+    provider:     dep.provider,
+    endpointUrl:  dep.endpoint_url || config.baseUrl,
+    receiptId:    dep.receipt_id,
+    createdAt:    new Date(dep.created_at * 1000).toISOString(),
+    costPerHour:  dep.cost_per_hour || 0,
+  };
+  addDeployment(localDep);
+  addReceipt({
+    receiptId:    dep.receipt_id,
+    action:       'badgr up',
+    deploymentId: dep.deployment_id,
+    spec:         { type: dep.workload_type, model: dep.model, gpu: dep.gpu_type, count: dep.gpu_count },
+    route:        { lane: 2, provider: dep.provider, ratePerHour: dep.cost_per_hour },
+    retries:      0,
+    status:       dep.status,
+    createdAt:    new Date().toISOString(),
+  });
+
+  console.log(chalk.green('\n✓ Provisioned\n'));
+  console.log(`  ${chalk.bold('Deployment:')}  ${chalk.cyan(dep.deployment_id)}`);
+  console.log(`  ${chalk.bold('Name:')}        ${dep.name}`);
+  console.log(`  ${chalk.bold('Type:')}        ${dep.workload_type}`);
+  if (dep.model) console.log(`  ${chalk.bold('Model:')}       ${dep.model}`);
+  console.log(`  ${chalk.bold('GPU:')}         ${dep.gpu_type} × ${dep.gpu_count}`);
+  console.log(`  ${chalk.bold('Provider:')}    ${dep.provider}`);
+  console.log(`  ${chalk.bold('Endpoint:')}    ${chalk.cyan(dep.endpoint_url || config.baseUrl)}`);
+  if (dep.cost_per_hour > 0) console.log(`  ${chalk.bold('Rate:')}        $${dep.cost_per_hour.toFixed(2)}/hr`);
+  console.log(`\n  ${chalk.bold('Receipt ID:')}  ${chalk.dim(dep.receipt_id)}`);
+
+  if (dep.workload_type === 'endpoint') {
+    console.log(`\n  ${chalk.bold('Use with OpenAI client:')}`);
+    const url = dep.endpoint_url || config.baseUrl;
+    console.log(chalk.dim(`    client = OpenAI(api_key="sk-...", base_url="${url}")`));
+    console.log(chalk.dim(`    # model: "${dep.model || 'meta-llama/Llama-3.1-8B-Instruct'}"`));
+  }
+  console.log();
+}

package/src/config.js

@@ -0,0 +1,33 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+
+export const CONFIG_DIR = join(homedir(), '.badgr');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export const DEFAULTS = {
+  baseUrl: 'https://api.badgr.ai/v1',
+  defaultModel: 'meta-llama/Llama-3.1-8B-Instruct',
+};
+
+export function loadConfig(configFile = CONFIG_FILE) {
+  if (!existsSync(configFile)) return { ...DEFAULTS };
+  try {
+    return { ...DEFAULTS, ...JSON.parse(readFileSync(configFile, 'utf8')) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function saveConfig(updates, configFile = CONFIG_FILE) {
+  const existing = loadConfig(configFile);
+  const merged = { ...existing, ...updates };
+  mkdirSync(dirname(configFile), { recursive: true });
+  writeFileSync(configFile, JSON.stringify(merged, null, 2));
+  return merged;
+}
+
+export function requireApiKey(config) {
+  if (!config.apiKey) throw new Error('No API key configured. Run: badgr login');
+  return config.apiKey;
+}

package/src/router.js

@@ -0,0 +1,104 @@
+/**
+ * GPU catalog and routing preview.
+ *
+ * Provider pricing mirrors the order in overflow_providers.py:
+ * Vast.ai → RunPod → TensorDock → SaladCloud.
+ * Actual routing happens server-side; this is the dry-run preview.
+ */
+
+export const GPU_CATALOG = [
+  { id: 'rtx-3080',  canonical: 'RTX_3080', name: 'NVIDIA RTX 3080',  vramGb: 10, ratePerHour: 0.35, tags: ['inference', 'dev'] },
+  { id: 'rtx-4090',  canonical: 'RTX_4090', name: 'NVIDIA RTX 4090',  vramGb: 24, ratePerHour: 1.10, tags: ['inference', 'training', 'dev'] },
+  { id: 'l40s',      canonical: 'L40S',     name: 'NVIDIA L40S',      vramGb: 48, ratePerHour: 1.40, tags: ['inference', 'training'] },
+  { id: 'a6000',     canonical: 'A6000',    name: 'NVIDIA RTX A6000', vramGb: 48, ratePerHour: 1.60, tags: ['inference', 'training'] },
+  { id: 'a100-40gb', canonical: 'A100',     name: 'NVIDIA A100 40GB',  vramGb: 40, ratePerHour: 1.80, tags: ['training', 'inference'] },
+  { id: 'a100-80gb', canonical: 'A100',     name: 'NVIDIA A100 80GB',  vramGb: 80, ratePerHour: 2.50, tags: ['training', 'large-model'] },
+  { id: 'h100',      canonical: 'H100',     name: 'NVIDIA H100 80GB',  vramGb: 80, ratePerHour: 3.50, tags: ['training', 'large-model'] },
+];
+
+// Provider-level pricing per canonical GPU type (ordered cheapest-first per provider).
+// Mirrors overflow_providers.py search ordering: Vast → RunPod → TensorDock → Salad.
+export const PROVIDER_CATALOG = {
+  RTX_3080: [
+    { provider: 'vastai',      ratePerHour: 0.28, reliability: 0.93 },
+    { provider: 'runpod',      ratePerHour: 0.35, reliability: 0.96 },
+    { provider: 'tensordock',  ratePerHour: 0.40, reliability: 0.90 },
+  ],
+  RTX_4090: [
+    { provider: 'vastai',      ratePerHour: 0.65, reliability: 0.94 },
+    { provider: 'runpod',      ratePerHour: 0.72, reliability: 0.97 },
+    { provider: 'tensordock',  ratePerHour: 0.81, reliability: 0.91 },
+    { provider: 'salad',       ratePerHour: 0.89, reliability: 0.89 },
+  ],
+  L40S: [
+    { provider: 'vastai',      ratePerHour: 1.10, reliability: 0.94 },
+    { provider: 'runpod',      ratePerHour: 1.25, reliability: 0.97 },
+    { provider: 'salad',       ratePerHour: 1.40, reliability: 0.88 },
+  ],
+  A6000: [
+    { provider: 'vastai',      ratePerHour: 1.05, reliability: 0.93 },
+    { provider: 'runpod',      ratePerHour: 1.20, reliability: 0.97 },
+    { provider: 'salad',       ratePerHour: 1.35, reliability: 0.88 },
+  ],
+  A100: [
+    { provider: 'runpod',      ratePerHour: 1.20, reliability: 0.98 },
+    { provider: 'vastai',      ratePerHour: 1.35, reliability: 0.95 },
+    { provider: 'tensordock',  ratePerHour: 1.50, reliability: 0.92 },
+  ],
+  H100: [
+    { provider: 'runpod',      ratePerHour: 2.80, reliability: 0.99 },
+    { provider: 'vastai',      ratePerHour: 3.10, reliability: 0.96 },
+  ],
+};
+
+export function findById(id) {
+  return GPU_CATALOG.find(g => g.id === id) ?? null;
+}
+
+export function findByCanonical(canonical) {
+  return GPU_CATALOG.find(g => g.canonical === canonical) ?? null;
+}
+
+export function findCheapest(requirements = {}) {
+  const { minVramGb = 0, tag = null } = requirements;
+  const matches = GPU_CATALOG
+    .filter(g => g.vramGb >= minVramGb)
+    .filter(g => !tag || g.tags.includes(tag))
+    .sort((a, b) => a.ratePerHour - b.ratePerHour);
+  return matches[0] ?? null;
+}
+
+export function listAll() {
+  return [...GPU_CATALOG].sort((a, b) => a.ratePerHour - b.ratePerHour);
+}
+
+/**
+ * Build the routing preview shown in --dry-run output.
+ * Mirrors the lane 1→2→3 logic in overflow_dispatch.py.
+ */
+export function getRoutePlan(canonical, count = 1) {
+  const providers = PROVIDER_CATALOG[canonical] ?? [];
+  const sorted = [...providers].sort((a, b) => a.ratePerHour - b.ratePerHour);
+
+  const cheapest = sorted[0];
+  const overhead = 0.25; // ~25% overhead: startup risk + failure buffer + badgr margin
+  const costWithOverhead = cheapest ? cheapest.ratePerHour * (1 + overhead) * count : null;
+
+  return {
+    canonical,
+    gpu: findByCanonical(canonical),
+    lane1: { label: 'Own GPU hosts', description: 'checked at runtime against live worker pool' },
+    lane2: sorted.map((p, i) => ({
+      rank: i + 1,
+      provider: p.provider,
+      ratePerHour: p.ratePerHour * count,
+      reliability: p.reliability,
+    })),
+    cheapestRate: cheapest ? cheapest.ratePerHour * count : null,
+    costWithOverhead,
+  };
+}
+
+export function estimateCost(ratePerHour, durationMinutes) {
+  return (ratePerHour / 60) * durationMinutes;
+}

package/src/spec.js

@@ -0,0 +1,92 @@
+/**
+ * Deployment spec: the single document that describes what `gpu up` should provision.
+ * Mirrors the concepts in overflow_dispatch.py (gpu_type, region, workload type).
+ */
+
+export const WORKLOAD_TYPES = ['endpoint', 'job'];
+export const REGIONS = ['US', 'EU', 'AU'];
+
+// Match canonical GPU IDs used in overflow_providers.py GPU_ALIASES
+export const GPU_TYPE_MAP = {
+  'rtx-4090': 'RTX_4090',  'rtx4090': 'RTX_4090',  '4090': 'RTX_4090',
+  'rtx-3090': 'RTX_3090',  'rtx3090': 'RTX_3090',  '3090': 'RTX_3090',
+  'rtx-4080': 'RTX_4080',  'rtx4080': 'RTX_4080',  '4080': 'RTX_4080',
+  'rtx-3080': 'RTX_3080',  'rtx3080': 'RTX_3080',  '3080': 'RTX_3080',
+  'a6000': 'A6000',
+  'h100': 'H100',
+  'a100': 'A100',           'a100-80gb': 'A100',    'a100-40gb': 'A100',
+  'l40s': 'L40S',
+};
+
+export function normalizeGpuType(input) {
+  if (!input) return 'RTX_4090';
+  const lower = input.toLowerCase().replace(/[_\s]/g, '-');
+  return GPU_TYPE_MAP[lower] ?? input.toUpperCase().replace(/-/g, '_');
+}
+
+export function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (next && !next.startsWith('--')) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+export function parseSpec(args) {
+  const flags = parseFlags(args);
+  const hasModel = Boolean(flags.model);
+  const hasImage = Boolean(flags.image);
+
+  // --endpoint / --job shorthands for --type endpoint|job
+  let type = flags.type
+    ?? (flags.endpoint ? 'endpoint' : null)
+    ?? (flags.job      ? 'job'      : null)
+    ?? (hasImage ? 'job' : 'endpoint');
+
+  return {
+    type,
+    model:    flags.model ?? (type === 'endpoint' ? 'meta-llama/Llama-3.1-8B-Instruct' : null),
+    image:    flags.image ?? (type === 'job' ? 'vllm/vllm-openai:latest' : null),
+    gpu:      normalizeGpuType(flags.gpu),
+    count:    Math.max(1, parseInt(flags.count ?? '1', 10)),
+    region:   (flags.region ?? 'US').toUpperCase(),
+    maxPrice: flags['max-price'] ? parseFloat(flags['max-price']) : null,
+    name:     flags.name ?? null,
+    dryRun:   flags['dry-run'] === true || flags['dry-run'] === 'true',
+  };
+}
+
+export function validateSpec(spec) {
+  const errors = [];
+  if (!WORKLOAD_TYPES.includes(spec.type)) {
+    errors.push(`Invalid --type "${spec.type}". Must be: ${WORKLOAD_TYPES.join(', ')}`);
+  }
+  if (isNaN(spec.count) || spec.count < 1 || spec.count > 8) {
+    errors.push('--count must be 1–8');
+  }
+  if (!REGIONS.includes(spec.region)) {
+    errors.push(`Invalid --region "${spec.region}". Must be: ${REGIONS.join(', ')}`);
+  }
+  return errors;
+}
+
+export function specLines(spec) {
+  return [
+    `type:    ${spec.type}`,
+    spec.model ? `model:   ${spec.model}` : null,
+    spec.image ? `image:   ${spec.image}` : null,
+    `gpu:     ${spec.gpu} × ${spec.count}`,
+    `region:  ${spec.region}`,
+    spec.maxPrice != null ? `max:     $${spec.maxPrice.toFixed(2)}/GPU-hr` : null,
+    spec.name ? `name:    ${spec.name}` : null,
+  ].filter(Boolean);
+}

package/src/store.js

@@ -0,0 +1,88 @@
+/**
+ * Local deployment state — persisted to ~/.gpu/deployments.json.
+ *
+ * Tracks what `gpu up` has provisioned so `gpu down/status/logs/receipts`
+ * have something to work with before a backend deployments API exists.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { CONFIG_DIR } from './config.js';
+import { randomUUID } from 'crypto';
+
+export const STORE_FILE = join(CONFIG_DIR, 'deployments.json');
+
+export function generateDeploymentId() {
+  return `dep-${randomUUID().replace(/-/g, '').slice(0, 8)}`;
+}
+
+export function generateReceiptId() {
+  return `rcpt-${randomUUID().replace(/-/g, '').slice(0, 10)}`;
+}
+
+export function loadStore(storeFile = STORE_FILE) {
+  if (!existsSync(storeFile)) return { deployments: [], receipts: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(storeFile, 'utf8'));
+    return {
+      deployments: parsed.deployments ?? [],
+      receipts: parsed.receipts ?? [],
+    };
+  } catch {
+    return { deployments: [], receipts: [] };
+  }
+}
+
+export function saveStore(store, storeFile = STORE_FILE) {
+  mkdirSync(dirname(storeFile), { recursive: true });
+  writeFileSync(storeFile, JSON.stringify(store, null, 2));
+}
+
+export function addDeployment(dep, storeFile = STORE_FILE) {
+  const store = loadStore(storeFile);
+  store.deployments.push(dep);
+  saveStore(store, storeFile);
+  return dep;
+}
+
+export function updateDeployment(idOrName, updates, storeFile = STORE_FILE) {
+  const store = loadStore(storeFile);
+  const idx = store.deployments.findIndex(
+    d => d.id === idOrName || d.name === idOrName
+  );
+  if (idx === -1) return null;
+  store.deployments[idx] = { ...store.deployments[idx], ...updates };
+  saveStore(store, storeFile);
+  return store.deployments[idx];
+}
+
+export function removeDeployment(idOrName, storeFile = STORE_FILE) {
+  const store = loadStore(storeFile);
+  const idx = store.deployments.findIndex(
+    d => d.id === idOrName || d.name === idOrName
+  );
+  if (idx === -1) return null;
+  const [removed] = store.deployments.splice(idx, 1);
+  saveStore(store, storeFile);
+  return removed;
+}
+
+export function findDeployment(idOrName, storeFile = STORE_FILE) {
+  const { deployments } = loadStore(storeFile);
+  return deployments.find(d => d.id === idOrName || d.name === idOrName) ?? null;
+}
+
+export function listDeployments(storeFile = STORE_FILE) {
+  return loadStore(storeFile).deployments;
+}
+
+export function addReceipt(receipt, storeFile = STORE_FILE) {
+  const store = loadStore(storeFile);
+  store.receipts.unshift(receipt); // newest first
+  if (store.receipts.length > 200) store.receipts.length = 200; // cap
+  saveStore(store, storeFile);
+  return receipt;
+}
+
+export function listReceipts(limit = 20, storeFile = STORE_FILE) {
+  return loadStore(storeFile).receipts.slice(0, limit);
+}

package/tests/api.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { callApi, listModels, chatCompletion, submitJob, getJobStatus, listReceipts, getReceipt, runJob, serveModel } from '../src/api.js';
+
+const mockConfig = { apiKey: 'sk-test', baseUrl: 'https://api.test/v1', defaultModel: 'llama-3' };
+
+function mockFetch(data, ok = true, status = 200) {
+  global.fetch = vi.fn().mockResolvedValue({
+    ok, status,
+    json:  async () => data,
+    text:  async () => JSON.stringify(data),
+  });
+}
+
+describe('callApi', () => {
+  it('includes Authorization header', async () => {
+    mockFetch({ data: [] });
+    await callApi('/models', { apiKey: 'sk-abc', baseUrl: 'https://api.test/v1' });
+    const [, init] = global.fetch.mock.calls[0];
+    expect(init.headers.Authorization).toBe('Bearer sk-abc');
+  });
+
+  it('throws on non-ok response with status code', async () => {
+    mockFetch('Unauthorized', false, 401);
+    await expect(callApi('/models', { apiKey: 'bad', baseUrl: 'https://api.test/v1' })).rejects.toThrow('401');
+  });
+
+  it('sends JSON body for POST', async () => {
+    mockFetch({ id: 'j1' });
+    await callApi('/jobs', { method: 'POST', apiKey: 'sk-x', baseUrl: 'https://api.test/v1', body: { script: 'a.py' } });
+    expect(JSON.parse(global.fetch.mock.calls[0][1].body)).toEqual({ script: 'a.py' });
+  });
+
+  it('omits body for GET', async () => {
+    mockFetch({});
+    await callApi('/models', { apiKey: 'x', baseUrl: 'https://api.test/v1' });
+    expect(global.fetch.mock.calls[0][1].body).toBeUndefined();
+  });
+});
+
+describe('chatCompletion', () => {
+  it('POST /chat/completions with messages', async () => {
+    mockFetch({ choices: [{ message: { content: 'hi' } }] });
+    const msgs = [{ role: 'user', content: 'hello' }];
+    await chatCompletion(mockConfig, msgs);
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toContain('/chat/completions');
+    expect(JSON.parse(init.body).messages).toEqual(msgs);
+  });
+
+  it('uses defaultModel when no model option', async () => {
+    mockFetch({ choices: [] });
+    await chatCompletion(mockConfig, []);
+    expect(JSON.parse(global.fetch.mock.calls[0][1].body).model).toBe('llama-3');
+  });
+
+  it('uses provided model over default', async () => {
+    mockFetch({ choices: [] });
+    await chatCompletion(mockConfig, [], { model: 'gpt-4o' });
+    expect(JSON.parse(global.fetch.mock.calls[0][1].body).model).toBe('gpt-4o');
+  });
+});
+
+describe('listModels', () => {
+  it('calls GET /models', async () => {
+    mockFetch({ data: [{ id: 'llama-3' }] });
+    const result = await listModels(mockConfig);
+    expect(global.fetch).toHaveBeenCalledWith(expect.stringContaining('/models'), expect.any(Object));
+    expect(result.data[0].id).toBe('llama-3');
+  });
+});
+
+describe('submitJob / getJobStatus', () => {
+  it('POST /jobs with job body', async () => {
+    mockFetch({ jobId: 'abc-123' });
+    const result = await submitJob(mockConfig, { script: 'train.py', gpuType: 'rtx-4090' });
+    expect(result.jobId).toBe('abc-123');
+  });
+
+  it('GET /jobs/:id', async () => {
+    mockFetch({ status: 'running' });
+    await getJobStatus(mockConfig, 'job-xyz');
+    expect(global.fetch).toHaveBeenCalledWith(expect.stringContaining('/jobs/job-xyz'), expect.any(Object));
+  });
+});
+
+describe('listReceipts', () => {
+  it('calls GET /receipts', async () => {
+    mockFetch({ object: 'list', data: [] });
+    await listReceipts(mockConfig);
+    const [url] = global.fetch.mock.calls[0];
+    expect(url).toContain('/receipts');
+  });
+
+  it('appends limit query param', async () => {
+    mockFetch({ object: 'list', data: [] });
+    await listReceipts(mockConfig, { limit: 50 });
+    const [url] = global.fetch.mock.calls[0];
+    expect(url).toContain('limit=50');
+  });
+
+  it('appends status filter when provided', async () => {
+    mockFetch({ object: 'list', data: [] });
+    await listReceipts(mockConfig, { status: 'success' });
+    const [url] = global.fetch.mock.calls[0];
+    expect(url).toContain('status=success');
+  });
+});
+
+describe('getReceipt', () => {
+  it('calls GET /receipts/:id', async () => {
+    mockFetch({ request_id: 'req-123', status: 'success' });
+    const result = await getReceipt(mockConfig, 'req-123');
+    expect(global.fetch).toHaveBeenCalledWith(expect.stringContaining('/receipts/req-123'), expect.any(Object));
+    expect(result.request_id).toBe('req-123');
+  });
+});
+
+describe('runJob', () => {
+  it('POST /run with job spec', async () => {
+    mockFetch({ deployment_id: 'dep-abc', status: 'running', provider: 'runpod' });
+    const result = await runJob(mockConfig, { command: ['python', 'train.py'], gpu: 'A100' });
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toContain('/run');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body).gpu).toBe('A100');
+    expect(result.deployment_id).toBe('dep-abc');
+  });
+});
+
+describe('serveModel', () => {
+  it('POST /serve with model spec', async () => {
+    mockFetch({ deployment_id: 'dep-xyz', status: 'running', endpoint_url: 'https://api.badgr.ai/v1' });
+    const result = await serveModel(mockConfig, { model: 'meta-llama/Llama-3.1-8B-Instruct', gpu: 'L40S' });
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toContain('/serve');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body).model).toBe('meta-llama/Llama-3.1-8B-Instruct');
+    expect(result.deployment_id).toBe('dep-xyz');
+  });
+});

package/tests/commands.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { parseRunArgs } from '../src/commands/run.js';
+import { parseServeArgs } from '../src/commands/serve.js';
+
+describe('parseRunArgs', () => {
+  it('parses a plain command', () => {
+    const { flags, positional } = parseRunArgs(['python', 'train.py']);
+    expect(positional).toEqual(['python', 'train.py']);
+    expect(flags.gpu).toBeUndefined();
+  });
+
+  it('parses --gpu flag', () => {
+    const { flags, positional } = parseRunArgs(['python', 'train.py', '--gpu', 'A100']);
+    expect(positional).toEqual(['python', 'train.py']);
+    expect(flags.gpu).toBe('A100');
+  });
+
+  it('parses --image flag', () => {
+    const { flags } = parseRunArgs(['--image', 'my/image:latest', '--gpu', 'L40S']);
+    expect(flags.image).toBe('my/image:latest');
+    expect(flags.gpu).toBe('L40S');
+  });
+
+  it('parses --max-price flag', () => {
+    const { flags } = parseRunArgs(['python', 'run.py', '--max-price', '2.5']);
+    expect(flags.maxPrice).toBe(2.5);
+  });
+
+  it('parses --detach flag', () => {
+    const { flags, positional } = parseRunArgs(['python', 'train.py', '--gpu', 'A100', '--detach']);
+    expect(positional).toEqual(['python', 'train.py']);
+    expect(flags.detach).toBe(true);
+    expect(flags.gpu).toBe('A100');
+  });
+
+  it('detach defaults to falsy when not passed', () => {
+    const { flags } = parseRunArgs(['python', 'train.py']);
+    expect(flags.detach).toBeFalsy();
+  });
+
+  it('returns empty positional and flags for empty args', () => {
+    const { flags, positional } = parseRunArgs([]);
+    expect(positional).toEqual([]);
+    expect(flags.gpu).toBeUndefined();
+  });
+});
+
+describe('parseServeArgs', () => {
+  it('parses model positional arg', () => {
+    const { model, flags } = parseServeArgs(['meta-llama/Llama-3.1-8B-Instruct', '--gpu', 'L40S']);
+    expect(model).toBe('meta-llama/Llama-3.1-8B-Instruct');
+    expect(flags.gpu).toBe('L40S');
+  });
+
+  it('parses --name flag', () => {
+    const { model, flags } = parseServeArgs(['mistralai/Mistral-7B-v0.1', '--name', 'prod-llm']);
+    expect(model).toBe('mistralai/Mistral-7B-v0.1');
+    expect(flags.name).toBe('prod-llm');
+  });
+
+  it('parses --max-price flag', () => {
+    const { flags } = parseServeArgs(['my/model', '--max-price', '3.0']);
+    expect(flags.maxPrice).toBe(3.0);
+  });
+
+  it('parses --no-wait flag', () => {
+    const { model, flags } = parseServeArgs(['my/model', '--gpu', 'L40S', '--no-wait']);
+    expect(model).toBe('my/model');
+    expect(flags.noWait).toBe(true);
+  });
+
+  it('noWait defaults to falsy when not passed', () => {
+    const { flags } = parseServeArgs(['my/model']);
+    expect(flags.noWait).toBeFalsy();
+  });
+
+  it('returns null model when no positional arg', () => {
+    const { model } = parseServeArgs(['--gpu', 'RTX_4090']);
+    expect(model).toBeNull();
+  });
+});