badgr-cli 1.0.40 → 1.0.42

package/README.md

@@ -17,11 +17,15 @@ badgr login
 # 2. Verify the stack end-to-end
 badgr test
 
-# 3. Serve an OpenAI-compatible inference endpoint
-badgr serve meta-llama/Llama-3.1-8B-Instruct
+# 3. Run a project folder on a GPU
+badgr run . --cmd "python train.py" --max-cost 5
 
-# 4. Use the endpoint with any OpenAI SDK client
-#    client = OpenAI(api_key="sk-...", base_url="https://dep-a1b2c3.aibadgr.com/v1")
+# 4. Serve an OpenAI-compatible inference endpoint
+badgr serve meta-llama/Llama-3.1-8B-Instruct --max-cost 10
+
+# 5. Use the endpoint with any OpenAI SDK client
+#    export BADGR_ENDPOINT=<URL printed by badgr serve>
+#    client = OpenAI(api_key=os.environ["BADGR_API_KEY"], base_url=os.environ["BADGR_ENDPOINT"])
 
 # 5. View cost, route, and retry receipts
 badgr receipts
@@ -92,25 +96,36 @@ badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S --region EU
 
 ## `badgr run` options
 
+Three source patterns:
+
 ```bash
-badgr run python train.py --gpu A100 --env HF_TOKEN=$HF_TOKEN --max-runtime 60
+# Flow 1 — local project folder (primary)
+badgr run . --cmd "python train.py" --max-cost 5
+
+# Flow 2 — public GitHub repo
+badgr run https://github.com/user/repo --cmd "python train.py" --max-cost 5
+
+# Flow 3 — custom Docker image (advanced)
+badgr run . --image mycompany/custom:latest --cmd "python train.py" --max-cost 5
 ```
 
+Badgr zips and uploads the folder (Flow 1) or clones the repo (Flow 2), picks a generic runner, installs deps, runs the command, stores outputs for 48 hours, and tears down the GPU. `--max-cost` is required.
+
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--cmd <command>` | — | Command to run inside the uploaded project or cloned repo (required for folder/GitHub flows) |
 | `--gpu <type>` | auto | GPU type override — Badgr Auto selects if omitted |
 | `--min-vram <GB>` | — | Minimum VRAM in GB — optional constraint for Auto routing |
-| `--image <img>` | python:3.11-slim | Docker image |
+| `--image <img>` | — | Custom Docker image — bypasses the runner. Mutually exclusive with workspace auto-detection. |
 | `--env KEY=VALUE` | — | Environment variable (repeatable) |
 | `--tier 1\|2` | 1 | `1` = reliable execution (default); `2` = lower-cost burst capacity |
 | `--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 |
-| `--max-runtime <min>` | — | Auto-stop after N minutes (recommended) |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
+| `--max-runtime <min>` | — | Auto-stop after N minutes |
+| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount (required) |
 | `--detach` | — | Launch and return immediately, don't stream logs |
 | `--save <name>` | — | Save this job as a named workload after it completes |
-| `--workspace <name\|id>` | — | Link this job to a workspace tracker (name or `ws_…` ID) |
 
 ---
 
@@ -216,7 +231,7 @@ A workload is a saved job configuration. Once saved, you can rerun it by name in
 **Save a workload** by adding `--save <name>` to any `badgr run` call:
 
 ```bash
-badgr run python train.py --gpu A100 --env HF_TOKEN=$HF_TOKEN --max-runtime 120 --save my-training-job
+badgr run . --cmd "python train.py" --gpu A100 --env HF_TOKEN=$HF_TOKEN --max-cost 10 --save my-training-job
 ```
 
 **Rerun a saved workload:**
@@ -245,11 +260,11 @@ badgr workload delete my-training-job
 
 ## Workspaces
 
-A workspace tracker groups jobs by a named context — useful for tracking cost and job history across a project or storage path.
+Workspaces are an advanced infrastructure concept — most users never need to manage them directly. When you run `badgr run .`, Badgr handles code upload, dependency caching, and artifact storage automatically. Workspaces are only needed when you want to group jobs under a named context for cost tracking, or link jobs to persistent S3/GCS storage.
 
 ```bash
 badgr workspace create my-project --storage s3://my-bucket/runs --desc "nightly evals"
-badgr run python eval.py --workspace my-project --max-cost 5
+badgr run . --cmd "python eval.py" --workspace my-project --max-cost 5
 badgr workspace info my-project     # jobs, total cost, files
 badgr workspace list
 badgr workspace delete my-project
@@ -298,11 +313,13 @@ Each receipt includes: receipt ID, GPU type, provisioning latency, price/hr, ret
 `badgr serve` provisions a vLLM endpoint that is fully OpenAI-compatible:
 
 ```python
+import os
 from openai import OpenAI
 
+# Export BADGR_ENDPOINT from the URL printed by `badgr serve`
 client = OpenAI(
-    api_key="your-badgr-api-key",
-    base_url="https://dep-a1b2c3.aibadgr.com/v1",  # from badgr serve output
+    api_key=os.environ["BADGR_API_KEY"],
+    base_url=os.environ["BADGR_ENDPOINT"],
 )
 resp = client.chat.completions.create(
     model="meta-llama/Llama-3.1-8B-Instruct",
@@ -314,7 +331,7 @@ resp = client.chat.completions.create(
 import OpenAI from "openai";
 const client = new OpenAI({
   apiKey: process.env.BADGR_API_KEY,
-  baseURL: "https://dep-a1b2c3.aibadgr.com/v1",
+  baseURL: process.env.BADGR_ENDPOINT,  // URL printed by `badgr serve`
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "badgr-cli",
-  "version": "1.0.40",
+  "version": "1.0.42",
   "description": "Badgr — run or serve GPU workloads from one command",
   "type": "module",
   "bin": {
@@ -12,8 +12,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "chalk": "^5.3.0",
-    "@inquirer/prompts": "^8.5.2"
+    "@inquirer/prompts": "^8.5.2",
+    "chalk": "^5.3.0"
   },
   "devDependencies": {
     "vitest": "^4.1.8"

package/src/catalog.js

@@ -40,6 +40,30 @@ export const TEMPLATES = [
       'Pass HF_TOKEN via --env or BADGR_HF_TOKEN env var.',
     ],
   },
+  {
+    name:        'batch-inference',
+    title:       'Batch Inference',
+    description: 'Run a Python script against many inputs on GPU — eval, scoring, embedding, generation',
+    type:        'job',
+    image:       'pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime',
+    gpu:         'RTX_4090',
+    gpu_count:   1,
+    min_vram_gb: 16,
+    env: {
+      HF_TOKEN:         '<your-hf-token>',
+      INPUT_FILE:       'inputs.jsonl',
+      OUTPUT_FILE:      'outputs.jsonl',
+      MODEL:            'meta-llama/Llama-3.1-8B-Instruct',
+      HF_HUB_CACHE:     '/workspace/hf-cache',
+      BADGR_OUTPUT_DIR: '/workspace/outputs',
+    },
+    notes: [
+      'Put your script and inputs.jsonl in the project folder.',
+      'Write outputs to $BADGR_OUTPUT_DIR — they are uploaded as artifacts (48h TTL).',
+      'Download results: `badgr artifacts <job-id>`',
+      'Example: `badgr run . --cmd "python batch.py" --max-cost 5 --save my-batch`',
+    ],
+  },
   {
     name:        'unsloth',
     title:       'Unsloth Fine-Tuning',
@@ -418,6 +442,44 @@ export const TEMPLATES = [
 
 export const TEMPLATE_MAP = Object.fromEntries(TEMPLATES.map(t => [t.name, t]));
 
+// ---------------------------------------------------------------------------
+// Productized runner catalogs
+// ---------------------------------------------------------------------------
+
+/** Blessed vLLM model aliases. `badgr serve qwen-7b` expands to the full model ID. */
+export const BLESSED_VLLM_MODELS = {
+  'qwen-7b': {
+    model_id:    'Qwen/Qwen2.5-7B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Qwen 2.5 7B Instruct — fast, multilingual',
+  },
+  'llama-8b': {
+    model_id:    'meta-llama/Llama-3.1-8B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Llama 3.1 8B Instruct — Meta flagship 8B',
+  },
+  'qwen-coder-7b': {
+    model_id:    'Qwen/Qwen2.5-Coder-7B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Qwen 2.5 Coder 7B — code generation specialist',
+  },
+};
+
+/** Blessed ComfyUI workflows accepted by `POST /v1/jobs` comfy.batch. */
+export const BLESSED_COMFY_WORKFLOWS = {
+  'sdxl-basic': {
+    description: 'SDXL text-to-image with default sampler settings',
+    gpu_type:    'RTX_4090',
+    output_type: 'images',
+  },
+};
+
 /**
  * Build the args array passed to serveCommand / runCommand.
  * Template defaults are applied first; CLI overrides win.

package/src/commands/comfyui.js

@@ -110,11 +110,143 @@ async function validateComfyNodes(endpointUrl, nodeList, chalk) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// badgr comfyui batch — productized batch via POST /v1/jobs comfy.batch
+// ---------------------------------------------------------------------------
+
+export function parseComfyBatchArgs(args) {
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '--workflow')    { flags.workflow = args[++i]; i++; continue; }
+    if (a === '--prompts')     { flags.prompts = args[++i]; i++; continue; }
+    if (a === '--prompt')      { if (!flags.inlinePrompts) flags.inlinePrompts = []; flags.inlinePrompts.push(args[++i]); i++; continue; }
+    if (a === '--max-cost')    { flags.maxCost = parseFloat(args[++i]); i++; continue; }
+    if (a === '--max-runtime') { flags.maxRuntime = parseFloat(args[++i]); i++; continue; }
+    if (a === '--tier')        { flags.tier = args[++i]; i++; continue; }
+    if (a === '--gpu-type')    { flags.gpuType = args[++i]; i++; continue; }
+    i++;
+  }
+  return flags;
+}
+
+export async function comfyBatchCommand(config, args, chalk) {
+  const { readFileSync, existsSync } = await import('fs');
+  const { callApi } = await import('../api.js');
+  const { addReceipt, generateReceiptId } = await import('../store.js');
+  const flags = parseComfyBatchArgs(args);
+
+  if (!flags.workflow) {
+    console.error(chalk.red('\n  Usage: badgr comfyui batch --workflow sdxl-basic --prompts prompts.txt --max-cost 10\n'));
+    console.error(chalk.dim('  Runs a batch of prompts through a blessed ComfyUI workflow and returns image URLs.\n'));
+    console.error(chalk.dim('  Blessed workflows: sdxl-basic\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!flags.maxCost) {
+    console.error(chalk.red('\n  ✗ --max-cost is required.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  requireApiKey(config);
+
+  // Collect prompts from file or --prompt flags
+  let prompts = flags.inlinePrompts || [];
+  if (flags.prompts) {
+    if (!existsSync(flags.prompts)) {
+      console.error(chalk.red(`\n  ✗ Prompts file not found: ${flags.prompts}\n`));
+      process.exitCode = 1;
+      return;
+    }
+    const lines = readFileSync(flags.prompts, 'utf8')
+      .split('\n')
+      .map(l => l.trim())
+      .filter(Boolean);
+    prompts = prompts.concat(lines);
+  }
+
+  if (prompts.length === 0) {
+    console.error(chalk.red('\n  ✗ No prompts provided. Use --prompts file.txt or --prompt "text"\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (prompts.length > 20) {
+    console.error(chalk.red(`\n  ✗ Max 20 prompts per batch (got ${prompts.length})\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const input = { workflow_id: flags.workflow, prompts };
+  if (flags.gpuType) input.gpu_type = flags.gpuType;
+
+  const rcptId = generateReceiptId();
+  const maxRuntime = flags.maxRuntime ?? 60;
+
+  console.log(chalk.bold('\n⚡ Starting ComfyUI batch\n'));
+  console.log(`  ${chalk.bold('Workflow:')}   ${flags.workflow}`);
+  console.log(`  ${chalk.bold('Prompts:')}    ${prompts.length}`);
+  console.log(`  ${chalk.bold('Max cost:')}   $${flags.maxCost}`);
+  console.log(`  ${chalk.bold('Max runtime:')} ${maxRuntime} min\n`);
+
+  let job;
+  try {
+    job = await callApi(config, 'POST', '/v1/jobs', {
+      type: 'comfy.batch',
+      input,
+      policy: { max_cost: flags.maxCost, max_runtime_minutes: maxRuntime, tier: flags.tier },
+    });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Failed to submit job: ${err.message}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  addReceipt({ id: rcptId, type: 'comfy.batch', job_id: job.job_id, started_at: Date.now() });
+  console.log(`  ${chalk.bold('Job ID:')}  ${job.job_id}`);
+  console.log(`  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}`);
+  console.log(chalk.dim('\n  Polling for completion…\n'));
+
+  const startMs = Date.now();
+  const maxMs = maxRuntime * 60 * 1000;
+  while (Date.now() - startMs < maxMs) {
+    await new Promise(r => setTimeout(r, 15_000));
+    let detail;
+    try { detail = await callApi(config, 'GET', `/v1/jobs/${job.job_id}`); } catch { continue; }
+    process.stdout.write(`\r  Status: ${detail.status}  elapsed: ${Math.floor((Date.now() - startMs) / 1000)}s  `);
+    if (detail.status === 'completed') {
+      const out = detail.output || {};
+      console.log(chalk.green('\n\n  ✓ Batch complete\n'));
+      if (out.image_urls && out.image_urls.length > 0) {
+        console.log(`  ${chalk.bold('Images (${out.image_urls.length}):')}`);
+        out.image_urls.forEach((url, i) => console.log(`    ${i + 1}. ${url}`));
+      }
+      console.log(`\n  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}\n`);
+      return;
+    }
+    if (detail.status === 'failed') {
+      console.error(chalk.red(`\n\n  ✗ Batch failed: ${detail.error_code || ''} — ${detail.error_message || ''}\n`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+  console.error(chalk.yellow('\n\n  Batch still running — detached. Check status:\n'));
+  console.error(chalk.dim(`    badgr status\n`));
+}
+
 export async function comfyuiCommand(config, args, chalk) {
+  // Route subcommands
+  const sub = args[0];
+  if (sub === 'batch') return comfyBatchCommand(config, args.slice(1), chalk);
+
   const { workflow, flags } = parseComfyuiArgs(args);
 
   if (!workflow) {
     console.error(chalk.red('\n  Usage: badgr comfyui run workflow.json\n'));
+    console.error(chalk.dim('  Batch mode: badgr comfyui batch --workflow sdxl-basic --prompts prompts.txt --max-cost 10\n'));
     console.error(chalk.dim('  Launches ComfyUI, queues your workflow, and returns the URL.\n'));
     process.exitCode = 1;
     return;

package/src/commands/run.js

@@ -1,3 +1,7 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createWriteStream } from 'fs';
 import { requireApiKey } from '../config.js';
 import { callApi, terminateDeployment } from '../api.js';
 import { addReceipt, updateReceipt, generateReceiptId } from '../store.js';
@@ -6,10 +10,19 @@ import { formatCliError } from '../errors.js';
 import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides } from '../catalog.js';
 
 /**
- * badgr run python train.py                    # gpu=auto, attached
- * badgr run python train.py --gpu A100         # specific GPU
- * badgr run --image my/image:latest --gpu L40S --detach
- * badgr run python train.py --env HF_TOKEN=abc --env DATASET=my/data
+ * Flow 1 — local project (primary):
+ *   badgr run . --cmd "python train.py" --max-cost 5 --save my-training-job
+ *   badgr run ./my-project --cmd "python train.py" --max-cost 5
+ *
+ * Flow 2 — public GitHub repo:
+ *   badgr run https://github.com/user/repo --cmd "python train.py" --max-cost 5
+ *
+ * Flow 3 — custom image (advanced):
+ *   badgr run . --image mycompany/custom:latest --cmd "python train.py" --max-cost 5
+ *
+ * Legacy / direct command:
+ *   badgr run python train.py --gpu A100
+ *   badgr run --image my/image:latest --gpu L40S --detach
  */
 export function parseRunArgs(args) {
   const flags = {};
@@ -41,6 +54,7 @@ export function parseRunArgs(args) {
     if (flagArgs[i] === '--dry-run')         { flags.dryRun = true; i++; continue; }
     if (flagArgs[i] === '--save')            { flags.save = flagArgs[++i]; i++; continue; }
     if (flagArgs[i] === '--workspace')       { flags.workspace = flagArgs[++i]; i++; continue; }
+    if (flagArgs[i] === '--cmd')             { flags.cmd = flagArgs[++i]; i++; continue; }
     if (flagArgs[i] === '--env') {
       const kv = flagArgs[++i]; i++;
       if (!flags.env) flags.env = [];
@@ -342,9 +356,117 @@ const _KNOWN_RUN_FLAGS = new Set([
   '--gpu', '--image', '--count', '--region', '--tier', '--max-price', '--name',
   '--detach', '--fallback', '--no-fallback', '--strict-capacity',
   '--no-expanded-search', '--max-runtime', '--max-cost', '--min-vram', '--env',
-  '--dry-run',
+  '--dry-run', '--cmd', '--save', '--workspace',
 ]);
 
+// Directories and files always excluded from project zip uploads.
+const _ZIP_EXCLUDES = new Set([
+  '.git', 'node_modules', '__pycache__', '.venv', 'venv', '.env',
+  'dist', 'build', '.next', '.nuxt', 'coverage', '.pytest_cache',
+  '.mypy_cache', '.ruff_cache', '.DS_Store',
+]);
+
+function _shouldExclude(name) {
+  return _ZIP_EXCLUDES.has(name) || name.startsWith('.') && name !== '.gitignore';
+}
+
+function _isLocalPath(arg) {
+  // '.' or './' or relative/absolute paths that exist on disk
+  if (arg === '.') return true;
+  if (arg.startsWith('./') || arg.startsWith('../') || arg.startsWith('/')) return true;
+  return false;
+}
+
+function _isGitHubUrl(arg) {
+  return /^https?:\/\/(www\.)?github\.com\//.test(arg);
+}
+
+/**
+ * Zip a local directory into a temp file, returning the temp file path.
+ * Uses Node's built-in APIs — no external zip library required.
+ */
+async function _zipDirectory(dirPath, chalk) {
+  // Use archiver if available, otherwise fall back to a manual approach via
+  // a child process calling `zip` (available on Linux/macOS) or PowerShell on Windows.
+  const absDir = path.resolve(dirPath);
+  if (!fs.existsSync(absDir)) {
+    throw new Error(`Directory not found: ${absDir}`);
+  }
+
+  const tmpFile = path.join(os.tmpdir(), `badgr-upload-${Date.now()}.zip`);
+
+  // Attempt to use archiver (optional peer dep) first; fall back to system zip.
+  try {
+    const { default: archiver } = await import('archiver');
+    await new Promise((resolve, reject) => {
+      const output = createWriteStream(tmpFile);
+      const archive = archiver('zip', { zlib: { level: 6 } });
+      output.on('close', resolve);
+      archive.on('error', reject);
+      archive.pipe(output);
+      archive.glob('**/*', {
+        cwd: absDir,
+        dot: false,
+        ignore: [..._ZIP_EXCLUDES].map(e => `**/${e}/**`).concat([..._ZIP_EXCLUDES].map(e => e)),
+      });
+      archive.finalize();
+    });
+    return tmpFile;
+  } catch {
+    // archiver not installed — fall back to system zip command
+  }
+
+  const { spawn } = await import('child_process');
+  await new Promise((resolve, reject) => {
+    // Build exclude args — zip uses -x patterns
+    const excludeArgs = [];
+    for (const ex of _ZIP_EXCLUDES) {
+      excludeArgs.push('-x', `*/${ex}/*`, '-x', `${ex}/*`, '-x', `${ex}`);
+    }
+    const child = spawn('zip', ['-r', '-q', tmpFile, '.', ...excludeArgs], { cwd: absDir });
+    child.on('close', code => code === 0 ? resolve() : reject(new Error(`zip exited ${code}`)));
+    child.on('error', reject);
+  });
+
+  return tmpFile;
+}
+
+export async function _uploadCodeZip(config, dirPath, chalk) {
+  process.stdout.write(chalk.dim('  Packing project...'));
+  const tmpFile = await _zipDirectory(dirPath, chalk);
+  const stat = fs.statSync(tmpFile);
+  const sizeMb = (stat.size / 1024 / 1024).toFixed(1);
+  process.stdout.write(chalk.dim(` ${sizeMb} MB\n`));
+
+  process.stdout.write(chalk.dim('  Uploading project...'));
+  // POST zip directly to the Badgr backend — no S3, no presigned URLs.
+  // Built-in FormData/Blob/fetch (Node >=18) keep the CLI dependency-free for
+  // multipart uploads; fetch sets the multipart boundary header automatically.
+  const fileData = fs.readFileSync(tmpFile);
+  const form = new FormData();
+  form.append('file', new Blob([fileData], { type: 'application/zip' }), 'project.zip');
+
+  const baseUrl = config.baseUrl.replace(/\/v1\/?$/, '');
+  let uploadResp;
+  try {
+    uploadResp = await fetch(`${baseUrl}/v1/uploads`, {
+      method: 'POST',
+      body: form,
+      headers: { 'Authorization': `Bearer ${config.apiKey}` },
+    });
+  } finally {
+    fs.unlinkSync(tmpFile);
+  }
+
+  if (!uploadResp.ok) {
+    const text = await uploadResp.text().catch(() => '');
+    throw new Error(`Upload failed: ${uploadResp.status} ${uploadResp.statusText}${text ? ` — ${text}` : ''}`);
+  }
+  const { code_uri: codeUri } = await uploadResp.json();
+  process.stdout.write(chalk.dim(' done\n'));
+  return codeUri;
+}
+
 export async function runCommand(config, args, chalk) {
   // `badgr run template <name> [flags]` — expand template defaults then re-dispatch
   if (args[0] === 'template') {
@@ -387,12 +509,37 @@ export async function runCommand(config, args, chalk) {
     return;
   }
 
-  if (positional.length === 0 && commandArgv === null && !flags.image) {
-    console.error(chalk.red('Usage: badgr run --gpu <GPU> --image <image> --max-cost <n> -- <command...>'));
-    console.error(chalk.red('       badgr run --image my/image:latest'));
+  // ── Detect source type ─────────────────────────────────────────────────────
+  // positional[0] may be:  '.'  |  './dir'  |  'https://github.com/...'  |  'python'  |  nothing
+  const firstArg = positional[0] ?? null;
+  const isLocalPath  = firstArg && _isLocalPath(firstArg);
+  const isGitHubUrl  = firstArg && _isGitHubUrl(firstArg);
+  const isCodeSource = isLocalPath || isGitHubUrl;
+
+  if (isCodeSource && !flags.cmd) {
+    console.error(chalk.red(`\n  ✗ --cmd is required when running from a ${isLocalPath ? 'local path' : 'GitHub URL'}.\n`));
+    if (isLocalPath) {
+      console.error(chalk.dim('  Example: badgr run . --cmd "python train.py" --max-cost 5\n'));
+    } else {
+      console.error(chalk.dim('  Example: badgr run https://github.com/user/repo --cmd "python train.py" --max-cost 5\n'));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // Legacy direct-command mode: positional args form the command
+  const isDirectCommand = !isCodeSource && (positional.length > 0 || commandArgv !== null || flags.image);
+
+  if (!isCodeSource && positional.length === 0 && commandArgv === null && !flags.image) {
+    console.error(chalk.red('\nUsage:'));
+    console.error(chalk.dim('  badgr run . --cmd "python train.py" --max-cost 5'));
+    console.error(chalk.dim('  badgr run https://github.com/user/repo --cmd "python train.py" --max-cost 5'));
+    console.error(chalk.dim('  badgr run python train.py --max-cost 5'));
+    console.error(chalk.dim('  badgr run --image my/image:latest --max-cost 5'));
+    console.error('');
     return;
   }
-  if (commandArgv !== null && commandArgv.length === 0 && !flags.image) {
+  if (commandArgv !== null && commandArgv.length === 0 && !flags.image && !isCodeSource) {
     console.error(chalk.red('  ✗ No command after --. Provide a command or --image.'));
     console.error(chalk.dim('  Example: badgr run --gpu RTX_4090 --max-cost 1 -- node script.js'));
     process.exitCode = 1;
@@ -430,13 +577,17 @@ export async function runCommand(config, args, chalk) {
   }
 
   // commandArgv is set when -- separator was used; fall back to positional for legacy syntax.
-  const command = commandArgv !== null
-    ? (commandArgv.length > 0 ? commandArgv : undefined)
-    : (positional.length > 0 ? positional : undefined);
-  const cmdStr = command ? command.join(' ') : '';
-  const isSmoke = cmdStr.length < 80 && /print\s*\(|['"]hello/i.test(cmdStr);
-  const inferredImage = isSmoke ? 'python:3.11-alpine' : 'python:3.11-slim';
-  const image = flags.image || (command ? inferredImage : undefined);
+  // For code-source flows (local path / GitHub), the "command" field is empty — the runner
+  // receives it via BADGR_CMD env var instead.
+  const command = isCodeSource
+    ? undefined
+    : (commandArgv !== null
+        ? (commandArgv.length > 0 ? commandArgv : undefined)
+        : (positional.length > 0 ? positional : undefined));
+  const cmdStr = isCodeSource ? (flags.cmd || '') : (command ? command.join(' ') : '');
+  const isSmoke = !isCodeSource && cmdStr.length < 80 && /print\s*\(|['"]hello/i.test(cmdStr);
+  const inferredImage = isSmoke ? 'python:3.11-alpine' : undefined; // code-source flows use runner image
+  const image = flags.image || (command && !isCodeSource ? (isSmoke ? 'python:3.11-alpine' : undefined) : undefined);
   const detach       = flags.detach || false;
 
   // Default max-runtime of 60 minutes — always applied unless overridden.
@@ -453,6 +604,9 @@ export async function runCommand(config, args, chalk) {
 
   if (flags.dryRun) {
     console.log(chalk.bold('\n⚡ Dry run — no GPU will be provisioned\n'));
+    if (isLocalPath)      console.log(`  ${chalk.bold('Source:')}       ${path.resolve(firstArg)} (local project)`);
+    if (isGitHubUrl)      console.log(`  ${chalk.bold('Source:')}       ${firstArg} (GitHub)`);
+    if (flags.cmd)        console.log(`  ${chalk.bold('Command:')}      ${flags.cmd}`);
     if (command)          console.log(`  ${chalk.bold('Command:')}      ${command.join(' ')}`);
     if (image)            console.log(`  ${chalk.bold('Image:')}        ${image}`);
     console.log(`  ${chalk.bold('GPU:')}          ${gpu || chalk.dim('auto')}`);
@@ -465,10 +619,13 @@ export async function runCommand(config, args, chalk) {
   }
 
   console.log(chalk.bold('\n⚡ Running GPU job\n'));
-  if (command) console.log(`  ${chalk.bold('Command:')}  ${command.join(' ')}`);
-  if (image)   console.log(`  ${chalk.bold('Image:')}    ${image}`);
-  if (gpu)     console.log(`  ${chalk.bold('GPU:')}      ${gpu}`);
-  else         console.log(`  ${chalk.bold('GPU:')}      ${chalk.dim('auto')}`);
+  if (isLocalPath)  console.log(`  ${chalk.bold('Source:')}   ${path.resolve(firstArg)}`);
+  if (isGitHubUrl)  console.log(`  ${chalk.bold('Source:')}   ${firstArg}`);
+  if (flags.cmd)    console.log(`  ${chalk.bold('Command:')}  ${flags.cmd}`);
+  if (command)      console.log(`  ${chalk.bold('Command:')}  ${command.join(' ')}`);
+  if (image)        console.log(`  ${chalk.bold('Image:')}    ${image}`);
+  if (gpu)          console.log(`  ${chalk.bold('GPU:')}      ${gpu}`);
+  else              console.log(`  ${chalk.bold('GPU:')}      ${chalk.dim('auto')}`);
   if (flags.minVram)  console.log(`  ${chalk.bold('Min VRAM:')}   ${flags.minVram} GB`);
   const runtimeLabel = isDefaultRuntime
     ? `${effectiveMaxRuntime}min ${chalk.dim('(default — use --max-runtime N to override)')}`
@@ -498,6 +655,18 @@ export async function runCommand(config, args, chalk) {
     }
   }
 
+  // ── Upload local project zip (Flow 1) ─────────────────────────────────────
+  let codeUri = null;
+  if (isLocalPath) {
+    try {
+      codeUri = await _uploadCodeZip(config, firstArg, chalk);
+    } catch (err) {
+      console.error(chalk.red(`\n  ✗ Failed to upload project: ${err.message}\n`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   console.log(chalk.dim('  Finding suitable capacity...'));
   if (process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true') {
     console.log(chalk.dim(`  API: ${config.baseUrl}`));
@@ -506,8 +675,8 @@ export async function runCommand(config, args, chalk) {
   function buildBody(gpuOverride, tierOverride) {
     const effectiveRegion = flags.region ? flags.region.toUpperCase() : undefined;
     return {
-      command,
-      image,
+      ...(command ? { command } : {}),
+      ...(image ? { image } : {}),
       gpu: gpuOverride || gpu || 'auto',
       ...(flags.minVram ? { min_vram: flags.minVram } : {}),
       gpu_count: flags.count || 1,
@@ -519,6 +688,10 @@ export async function runCommand(config, args, chalk) {
       max_runtime_seconds: effectiveMaxRuntime * 60,
       ...(maxCost ? { max_cost_usd: maxCost } : {}),
       ...(resolvedWorkspaceId ? { workspace_id: resolvedWorkspaceId } : {}),
+      // Code-source fields
+      ...(codeUri ? { code_uri: codeUri } : {}),
+      ...(isGitHubUrl ? { github_url: firstArg } : {}),
+      ...(flags.cmd ? { cmd: flags.cmd } : {}),
     };
   }
 
@@ -720,8 +893,12 @@ export async function runCommand(config, args, chalk) {
             name: flags.save,
             job_type: 'custom.run',
             config: {
-              command: command || [],
-              image: image || 'python:3.11-slim',
+              ...(command ? { command } : {}),
+              ...(image ? { image } : {}),
+              ...(flags.cmd ? { cmd: flags.cmd } : {}),
+              // For local-path workloads, code_uri is a snapshot — user can re-upload on next run.
+              // GitHub URL is stable and stored directly.
+              ...(isGitHubUrl ? { github_url: firstArg } : {}),
               gpu: gpu || 'auto',
               ...(flags.minVram ? { min_vram: flags.minVram } : {}),
               gpu_count: flags.count || 1,