badgr-cli 1.1.0 → 1.1.1

package/README.md

@@ -36,6 +36,76 @@ badgr receipts
 
 ---
 
+## Coding & testing agents: `badgr launch`
+
+Run a coding agent or a test suite on a CPU VM with one command — no image, source, or `--max-cost` required for the four built-in workloads. Three separate things are going on here, worth keeping straight: **which agent CLI** runs (`cline`, `claude`, `codex`, `playwright`), **who pays for model usage** (Badgr, or your own Anthropic/OpenAI account), and **who provisions the VM and runs the command** (always Badgr).
+
+```bash
+badgr launch cline "Fix the checkout bug"       # Badgr provides model access — no account to connect
+badgr launch claude "Fix the checkout bug"      # runs Claude Code — connect your Anthropic account
+badgr launch codex "Write tests"                # runs the Codex CLI — connect your OpenAI account
+badgr launch playwright "Test the checkout flow" # no model account involved at all
+```
+
+**Authentication model:**
+
+| Workload | CLI that runs | Who pays for model usage |
+|----------|---------------|---------------------------|
+| `cline` | Cline | Badgr provides and pays for model access |
+| `claude` | Claude Code | Your Anthropic account — Badgr only provides the VM |
+| `codex` | Codex CLI | Your OpenAI/ChatGPT account — Badgr only provides the VM |
+| `playwright` | Playwright | No model account required |
+
+Installing/running the `claude` or `codex` CLI doesn't by itself give a disposable Badgr VM model access — the CLI still needs to authenticate, and a VM's sign-in doesn't inherit from your laptop. `badgr launch claude`/`badgr launch codex` prompt inline the first time to connect your account and store it for next time; `cline` and `playwright` need nothing. Each workload picks its own VM size automatically (`small`, or `browser` for playwright's preinstalled Chromium) — override with `--size small|medium|browser`. A $2 default `--max-cost` applies unless you pass your own.
+
+Today, "connect your account" means securely storing an API key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) — both Claude Code and the Codex CLI also support signing in via a Claude.ai/ChatGPT account, and a future version of `badgr connect` may add that OAuth flow instead of a pasted key; the one-time-connection UX is the same either way.
+
+```bash
+badgr connect anthropic --key sk-ant-...   # connect your Anthropic account ahead of time (optional — badgr launch prompts inline if missing)
+badgr connect                              # list what's already connected
+badgr connect anthropic --remove           # disconnect
+```
+
+Retrieve results after a run finishes:
+
+```bash
+badgr pull <deployment-id>          # pull a code-editing agent's patch as a local git diff/branch
+badgr artifacts <deployment-id>     # download everything else — test reports, screenshots, traces
+```
+
+### Advanced escape hatch — any other command
+
+For anything beyond the four built-in workloads, run an arbitrary command on a CPU VM the same way `badgr run` does for GPU jobs:
+
+```bash
+badgr launch . --max-cost 1 -- npm test
+badgr launch https://github.com/user/repo --max-cost 1 -- python narrgo.py
+```
+
+Everything before `--` is a `badgr launch` flag; everything after `--` is passed to your command verbatim, including anything that looks like a flag (`badgr launch . -- claude --max-cost 1` sends `--max-cost 1` to `claude`, not to Badgr). The default runner image has no Node.js/npm — use `--image <image>` for anything that needs it.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--cmd "<command>"` | — | Quoted command form, equivalent to `-- <command>` |
+| `--image <image>` | CPU runtime default | Custom image instead of the default |
+| `--detach` / `--no-detach` | detach | `launch` detaches by default; `--no-detach` streams logs and waits |
+| `--env KEY=VALUE` | — | Environment variable (repeatable) — Badgr warns if a value looks like a secret |
+| `--artifacts <path>` | — | Extra path to capture and upload (repeatable), e.g. `--artifacts playwright-report`. Retrieve with `badgr artifacts <id>` |
+| `--max-cost <$>` | `$2` | Auto-stop when spend reaches this amount |
+| `--max-runtime <min>` | 60 | Auto-stop after N minutes |
+| `--region US\|EU\|AU` | — | Region preference |
+| `--size small\|medium\|browser` | per-workload default | VM class override |
+
+### `badgr task` — a labeled launch
+
+```bash
+badgr task "Run the Chromium tests and tell me what failed" --max-cost 1 -- npm run test:chromium
+```
+
+A thin wrapper over `badgr launch . -- <command>` — the description is printed for the human and otherwise discarded; the receipt and `badgr status` still key off the deployment ID like any other launch.
+
+---
+
 ## Also try: image generation
 
 ```bash
@@ -86,11 +156,16 @@ Run `badgr doctor --help` for the full flag list. Details in
 
 ```text
 login
+connect
 doctor
 run
+launch
+task
 serve
 status
 logs
+pull
+artifacts
 down
 receipts
 test
@@ -99,16 +174,21 @@ 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 doctor` | Diagnose a GPU workload failure — read-only, no login needed |
 | `badgr run <command>` | Run a one-off GPU job (any container command) |
+| `badgr launch cline\|claude\|codex\|playwright "<task>"` | Run a coding/testing agent on a CPU VM — image + command auto-selected |
+| `badgr task "<desc>" -- <command>` | Label + launch — thin wrapper over `badgr launch . -- <command>` |
 | `badgr serve <model>` | Start a persistent OpenAI-compatible endpoint |
 | `badgr status` | Show what's running and what's billing |
 | `badgr logs <id>` | Fetch log output from a deployment |
+| `badgr pull <id>` | Pull a code-editing agent's patch as a local git diff/branch |
+| `badgr artifacts <id>` | Download non-patch outputs (test reports, screenshots, traces) |
 | `badgr down <id>` | Terminate a deployment — stops billing immediately |
 | `badgr receipts [n]` | Cost, route, and retry receipts (default 10) |
 | `badgr test` | Run an end-to-end test (provision → run → teardown) |
 
-More commands below, under [Advanced](#advanced): `comfyui`, `train`, `transcribe`, `embed`, `workload`, `workspace`, `capacity`, `billing`.
+More commands below, under [Advanced](#advanced): `comfyui`, `train`, `transcribe`, `embed`, `workload`, `workspace`, `batch`, `sbatch`, `capacity`, `billing`.
 
 `badgr serve` — for anything that needs a persistent endpoint: LLM serving, embeddings, image generation APIs, transcription APIs.
 
@@ -407,6 +487,51 @@ badgr workspace list
 badgr workspace delete my-project
 ```
 
+### `badgr batch` — generic containerized batch jobs
+
+```bash
+badgr batch run workload.yml
+badgr batch status dep-abc123
+badgr batch artifacts dep-abc123
+badgr batch receipt dep-abc123
+badgr batch compare dep-abc123 dep-def456
+```
+
+For CV/video/scientific batch, simulation, and physical-AI eval workloads — runs a container from a `workload.yml` spec and captures output artifacts automatically.
+
+**Fan-out** — run the same program once per file in a directory, one deployment per input, in parallel:
+
+```bash
+badgr batch run workload.yml --fan-out ./scenarios
+badgr batch run workload.yml --fan-out ./scenarios --max-concurrency 10
+badgr batch run workload.yml --fan-out ./scenarios --only failed1.json,failed2.json
+```
+
+`workload.yml` must declare exactly one `inputs:` entry (the path that varies per task).
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fan-out <dir>` | — | Run once per file in this directory instead of a single job |
+| `--max-concurrency <n>` | 5 | Cap in-flight fan-out deployments |
+| `--only <f1,f2>` | — | Rerun just the named input files |
+| `--dry-run` | — | Preview the batch/fan-out plan without provisioning |
+
+### `badgr sbatch` — existing Slurm scripts
+
+```bash
+badgr sbatch job.slurm
+badgr sbatch job.slurm --dry-run
+badgr sbatch array_job.slurm              # #SBATCH --array=1-100 fans out into one deployment per task
+badgr sbatch array_job.slurm --max-concurrency 10
+```
+
+Translates `--cpus-per-task`/`--mem`/`--gres`/`--time`/`--export` from a real `.slurm` file. `#SBATCH --array=...` directives fan out into bounded-concurrency deployments the same way `batch run --fan-out` does; unsupported directives (`--partition`, `--qos`, `--account`) print a visible warning but don't block translation of the rest.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-concurrency <n>` | 5 | Cap in-flight array tasks |
+| `--dry-run` | — | Preview the translated job without provisioning |
+
 ### Other commands
 
 - `badgr capacity [--gpu <type>]` — check available GPU capacity right now

package/package.json

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