badgr-cli 1.0.44 → 1.0.46

package/README.md

@@ -2,6 +2,8 @@
 
 Badgr supports many GPU workloads through two commands: `serve` for persistent endpoints, `run` for jobs.
 
+> **Safety promise:** every run has `--max-cost`, live logs, automatic teardown, and a receipt. Run `badgr down <id>` any time to stop billing immediately.
+
 ```bash
 npm install -g badgr-cli
 ```
@@ -23,68 +25,75 @@ badgr run . --cmd "python train.py" --max-cost 5
 # 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. Stop billing
+badgr down <deployment-id>
 
-# 5. View cost, route, and retry receipts
+# 6. View cost, route, and retry receipts
 badgr receipts
+```
 
-# 6. Stop billing
-badgr down <deployment-id>
+`badgr serve` prints a URL you can point any OpenAI SDK client at — see [OpenAI compatibility](#openai-compatibility).
+
+---
+
+## Also try: image generation
+
+```bash
+badgr comfyui batch --workflow sdxl-basic --prompt "a cat on a beach" --max-cost 5
 ```
 
+Runs a blessed ComfyUI workflow, no setup, and prints image URLs when done. No manual teardown needed — it stops itself. Details in [`badgr comfyui batch` options](#badgr-comfyui-batch-options).
+
 ---
 
 ## Commands
 
+```text
+login
+run
+serve
+status
+logs
+down
+receipts
+test
+```
+
 | Command | What it does |
 |---------|-------------|
 | `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 serve <model>` | Start a persistent OpenAI-compatible endpoint |
 | `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 down <id>` | Terminate a deployment — stops billing immediately |
 | `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 workload list` | List saved workloads with run stats |
-| `badgr workload run <name>` | Rerun a saved workload by name or ID |
-| `badgr workload info <name>` | Show stats, route history, and recent jobs for a workload |
-| `badgr workload delete <name>` | Delete a saved workload |
-| `badgr workspace list` | List workspace trackers (job history + cost per context) |
-| `badgr workspace create <name>` | Create a workspace tracker, optionally linked to a storage path |
-| `badgr workspace info <name>` | Show jobs, cost, and files for a workspace |
-| `badgr workspace delete <name>` | Archive a workspace tracker |
+
+More commands below, under [Advanced](#advanced): `comfyui`, `train`, `transcribe`, `embed`, `workload`, `workspace`, `capacity`, `billing`.
 
 `badgr serve` — for anything that needs a persistent endpoint: LLM serving, embeddings, image generation APIs, transcription APIs.
 
 `badgr run` — for anything that starts, runs, and exits: batch inference, fine-tuning, evals, image/video batch jobs, audio processing.
 
-**Shortcuts** — wrappers around `run` / `serve` for common workloads:
-
-| `badgr comfyui run <workflow.json>` | Launch ComfyUI, queue workflow, return endpoint URL |
-| `badgr comfyui batch --workflow ...` | Productized batch image generation — no ComfyUI setup, blessed workflow only |
-| `badgr train <config.yaml>` | LoRA / fine-tuning job, stream logs |
-| `badgr train lora --base-model ...` | Productized LoRA training — preset + dataset, no config file needed |
-| `badgr transcribe <audio>` | Whisper transcription, print transcript |
-| `badgr embed <model> <input>` | Text embeddings, output JSONL |
-
-`badgr serve --list-aliases` lists the tested vLLM model routes (`qwen-7b`, `llama-8b`, `qwen-coder-7b`) that can be used in place of a full model ID.
+---
 
-### Model support levels
+## Common flags
 
-`badgr serve qwen-7b` is the happy path — a tested route with no extra setup. `badgr serve` also accepts any other model ID or a custom container, with the CLI honest (but brief) about what that means:
+These appear on most commands (`run`, `serve`, `comfyui`, `train`, `transcribe`, `embed`) — documented once here instead of repeated in every table below.
 
-| Level | What it means |
-|-------|---------------|
-| **Tested route** (`badgr serve qwen-7b`) | One of the aliases above — tested and officially supported. No extra caveats printed. |
-| **Best-effort Hugging Face model** (`badgr serve <org>/<model>`) | Any other Hugging Face model ID. Badgr will try a compatible route — not a guarantee every model works. |
-| **Custom container** (`badgr serve --image ...`) | You own the server behavior; Badgr manages runtime, logs, spend caps, teardown, and the receipt. |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--gpu <type>` | auto | GPU type override — see [GPU options](#gpu-options) |
+| `--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 |
+| `--count <n>` | 1 | Number of GPUs |
+| `--env KEY=VALUE` | — | Environment variable (repeatable) |
+| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount — **required** for `run`, `comfyui run`, `comfyui batch`, `train lora` |
+| `--detach` | off | Launch and return immediately, don't stream logs (`serve` uses `--no-wait` instead — see below) |
 
-Gated Hugging Face models (e.g. Llama, Gemma) may need `--env HF_TOKEN=$HF_TOKEN`. Badgr doesn't warn about this up front — it only prints the hint if the deployment actually fails to start, so tested and working launches stay short.
+Each command section below lists only its own extra flags.
 
 ---
 
@@ -96,21 +105,26 @@ badgr serve meta-llama/Llama-3.1-8B-Instruct --gpu L40S --region EU
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--gpu <type>` | auto | GPU type override — Badgr Auto selects based on model size if omitted |
 | `--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` = reliable execution (default); `2` = lower-cost burst capacity |
-| `--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 |
-| `--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 |
+| `--no-wait` | off | Skip endpoint health check and return immediately |
 | `--list-aliases` | — | List blessed vLLM model aliases (`qwen-7b`, `llama-8b`, `qwen-coder-7b`) and exit — no provisioning, no API key required |
 
 Blessed aliases expand to a full model ID + preset GPU, e.g. `badgr serve qwen-7b` → `Qwen/Qwen2.5-7B-Instruct` on an RTX 4090. Run `badgr serve --list-aliases` to see the current list.
 
+### Model support levels
+
+`badgr serve qwen-7b` is the happy path — a tested route with no extra setup. `badgr serve` also accepts any other model ID or a custom container:
+
+| Level | What it means |
+|-------|---------------|
+| **Tested route** (`badgr serve qwen-7b`) | One of the aliases above — tested and officially supported. |
+| **Best-effort Hugging Face model** (`badgr serve <org>/<model>`) | Any other Hugging Face model ID. Badgr will try a compatible route — not a guarantee every model works. |
+| **Custom container** (`badgr serve --image ...`) | You own the server behavior; Badgr manages runtime, logs, spend caps, teardown, and the receipt. |
+
+Gated Hugging Face models (e.g. Llama, Gemma) may need `--env HF_TOKEN=$HF_TOKEN`. Badgr only prints that hint if the deployment actually fails to start.
+
 ---
 
 ## `badgr run` options
@@ -133,18 +147,26 @@ Badgr zips and uploads the folder (Flow 1) or clones the repo (Flow 2), picks a
 | 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>` | — | 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 |
+| `--image <img>` | — | Custom Docker image — bypasses the runner |
 | `--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-or-id>` | — | Link this run to a workspace (name or `ws_` ID) |
+| `--output <path>` | — | See "Crash recovery" below |
+| `--checkpoint <path>` | — | See "Crash recovery" below |
+| `--retry-safe` | off | See "Crash recovery" below |
+| `--resume-cmd "<cmd>"` | — | See "Crash recovery" below |
+
+**Crash recovery is a convention, not a feature Badgr runs for you.** Badgr just passes these through into the container as environment variables — *your* script has to read them and actually write the files:
+
+| Flag | Container sees | Your script needs to |
+|------|-----------------|-----------------------|
+| `--output <path>` | `BADGR_OUTPUT_DIR=<path>` | Write outputs it wants preserved to that path |
+| `--checkpoint <path>` | `BADGR_CHECKPOINT_DIR=<path>` | Write/read resumable checkpoints at that path |
+| `--retry-safe` | `BADGR_RETRY_SAFE=1` | Confirm it's safe to re-run from scratch (e.g. it checkpoints/dedupes internally) |
+| `--resume-cmd "<cmd>"` | *(not passed to the container)* | Nothing — Badgr just prints this command back to you on failure, so you have it without digging through shell history |
+
+On failure, `badgr run` / `badgr serve` / `badgr comfyui run` all print a `Class:`/`Next:` pair identifying what went wrong (e.g. `out_of_memory`, `image_pull_failed`, `cuda_unavailable`) and a suggested next step.
 
 ---
 
@@ -159,16 +181,10 @@ Requires either `--max-cost` or `--persistent` to prevent runaway billing.
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--gpu <type>` | auto (16+ GB VRAM) | GPU type override |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
-| `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--tier 1\|2` | 1 | Provider tier |
-| `--region US\|EU\|AU` | — | Region preference |
 | `--check-nodes <n1,n2>` | — | Verify custom nodes are installed after startup |
-| `--no-wait` | — | Skip health check, return immediately |
-| `--persistent` | — | Run until manually stopped (no spending cap) |
-| `--env KEY=VALUE` | — | Environment variable (repeatable) |
-| `--yes` / `-y` | — | Skip duplicate-deployment warning |
+| `--no-wait` | off | Skip health check, return immediately |
+| `--persistent` | off | Run until manually stopped (no spending cap) |
+| `--yes` / `-y` | off | Skip duplicate-deployment warning |
 
 ---
 
@@ -188,253 +204,175 @@ Blessed workflows: `sdxl-basic` (SDXL text-to-image, default sampler settings).
 | `--workflow <name>` | — | Blessed workflow ID (required) — currently `sdxl-basic` |
 | `--prompts <file>` | — | Text file, one prompt per line |
 | `--prompt <text>` | — | Inline prompt (repeatable) — combine with `--prompts` if needed |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount (required unless `--dry-run`) |
 | `--max-runtime <min>` | 60 | Auto-stop after N minutes |
 | `--gpu-type <type>` | workflow default | GPU type override |
-| `--tier 1\|2` | 1 | Provider tier |
 | `--dry-run` | — | Preview the batch (workflow, GPU, prompt count, cost) without provisioning |
 
 Polls until complete and prints image URLs, or detaches with `badgr status` guidance if it outlives `--max-runtime`.
 
 ---
 
-## `badgr train` options
-
-```bash
-badgr train config.yaml --gpu A100 --max-runtime 240 --env HF_TOKEN=$HF_TOKEN
-```
-
-Detects framework (axolotl, unsloth, trl) from config content, but **only Axolotl configs run today** — the container command for `unsloth`/`trl`/unrecognized configs isn't wired up yet, so `badgr train` blocks before provisioning rather than billing a GPU that's guaranteed to fail. Use `--framework axolotl` to force it, or use `badgr train lora` for a config-free productized path. Default max-runtime is 120 min.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--gpu <type>` | auto (40+ GB VRAM preferred) | GPU type override |
-| `--max-runtime <min>` | 120 | Auto-stop after N minutes |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
-| `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--tier 1\|2` | 1 | Provider tier |
-| `--region US\|EU\|AU` | — | Region preference |
-| `--framework <name>` | auto-detect | Force framework: `axolotl`, `unsloth`, `trl` (only `axolotl` currently runs) |
-| `--env KEY=VALUE` | — | Environment variable (repeatable) |
-| `--detach` | — | Launch and return immediately, don't stream logs |
-
----
-
-## `badgr train lora` options
+## Receipts
 
-Productized LoRA training — pass a base model and dataset, no Axolotl config file needed. Badgr generates the config from a preset and returns a downloadable adapter.
+Every `badgr serve` and `badgr run` action generates a receipt:
 
 ```bash
-badgr train lora --base-model mistralai/Mistral-7B-v0.1 --dataset ./train.jsonl --preset small --max-cost 20
-badgr train lora --base-model meta-llama/Llama-3.1-8B-Instruct --dataset https://example.com/data.jsonl --preset medium --max-cost 40
+badgr receipts        # last 10
+badgr receipts 50     # last 50
 ```
 
-Dataset sources: local file (uploaded first), direct URL (`https://`, `s3://`), or `--file-id` from a prior `badgr` upload.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--base-model <id>` | — | HuggingFace model ID (required) — validated to exist before provisioning |
-| `--dataset <path\|url>` | — | Local file, direct URL, or `s3://` URI |
-| `--file-id <id>` | — | Badgr upload ID instead of `--dataset` |
-| `--preset small\|medium` | `small` | Training profile — see below |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount (required unless `--dry-run`) |
-| `--max-runtime <min>` | 240 | Auto-stop after N minutes |
-| `--gpu-type <type>` | preset default | GPU type override |
-| `--tier 1\|2` | 1 | Provider tier |
-| `--dry-run` | — | Preview the job (preset, GPU, rank, epochs, cost) without provisioning |
-
-**Presets:**
+Each receipt includes runtime, estimated/settled cost, status, retries, teardown/billing result, and job/deployment ID.
 
-| Preset | GPU | LoRA rank | Epochs | Best for |
-|--------|-----|-----------|--------|----------|
-| `small` (default) | RTX 4090 | 16 | 3 | Fast, low-cost — good default for most datasets |
-| `medium` | A100 | 32 | 5 | Larger rank/more epochs — bigger datasets or higher quality |
+---
 
-On completion, prints an `adapter_url` — download with `GET /v1/jobs/{job_id}/adapter`, or via `badgr workload info` if saved.
+## OpenAI compatibility
 
----
+`badgr serve` provisions a vLLM endpoint that is fully OpenAI-compatible:
 
-## `badgr transcribe` options
+```python
+import os
+from openai import OpenAI
 
-```bash
-badgr transcribe recording.mp3 --max-cost 2
-badgr transcribe s3://bucket/meeting.mp3 --model large-v3 --language en
+# Export BADGR_ENDPOINT from the URL printed by `badgr serve`
+client = OpenAI(
+    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",
+    messages=[{"role": "user", "content": "Hello"}],
+)
 ```
 
-Accepts a public URL, S3/GCS URI, or a local file under 50 MB. Default max-runtime is 30 min.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--model <name>` | `large-v3` | Whisper model |
-| `--gpu <type>` | auto (8+ GB VRAM) | GPU type override |
-| `--language <code>` | — | Language hint (e.g. `en`, `fr`) |
-| `--output <format>` | — | Output format: `txt`, `srt`, `vtt` |
-| `--max-runtime <min>` | 30 | Auto-stop after N minutes |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
-| `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--tier 1\|2` | 1 | Provider tier |
-| `--region US\|EU\|AU` | — | Region preference |
-| `--env KEY=VALUE` | — | Environment variable (repeatable) |
-| `--detach` | — | Launch and return immediately, don't stream logs |
+```js
+import OpenAI from "openai";
+const client = new OpenAI({
+  apiKey: process.env.BADGR_API_KEY,
+  baseURL: process.env.BADGR_ENDPOINT,  // URL printed by `badgr serve`
+});
+```
 
 ---
 
-## `badgr embed` options
+## GPU options
 
-```bash
-badgr embed BAAI/bge-large-en-v1.5 documents.txt --max-cost 2
-badgr embed BAAI/bge-large-en-v1.5 s3://bucket/corpus.jsonl
-badgr embed documents.txt   # uses default model
-```
+Badgr Auto selects the best eligible GPU for your workload. Add `--gpu <type>` or `--min-vram <GB>` only when you need more control.
 
-Accepts a public URL, S3/GCS URI, or a local text file under 10 MB. Outputs JSONL (`{"text": ..., "embedding": [...]}`). Default max-runtime is 30 min.
+| Flag value | GPU | VRAM | Best for |
+|-----------|-----|------|---------|
+| RTX_3090 | NVIDIA RTX 3090 | 24 GB | Dev, inference |
+| RTX_4090 | NVIDIA RTX 4090 | 24 GB | Inference, training, dev |
+| L40S | NVIDIA L40S | 48 GB | Inference, vLLM, embeddings |
+| A100 | NVIDIA A100 | 40–80 GB | Training, inference |
+| H100 | NVIDIA H100 | 80 GB | Large model training |
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--gpu <type>` | auto (8+ GB VRAM) | GPU type override |
-| `--batch-size <n>` | — | Embedding batch size |
-| `--max-runtime <min>` | 30 | Auto-stop after N minutes |
-| `--max-cost <$>` | — | Auto-stop when total spend reaches this amount |
-| `--max-price <$/hr>` | — | Hard spend cap per GPU-hour |
-| `--tier 1\|2` | 1 | Provider tier |
-| `--region US\|EU\|AU` | — | Region preference |
-| `--env KEY=VALUE` | — | Environment variable (repeatable) |
-| `--detach` | — | Launch and return immediately, don't stream logs |
+Additional GPU types may be routable depending on current capacity — check with `badgr capacity`. Pricing is confirmed before provisioning; use `--dry-run` to see it first. Full GPU support details: see [NOTES.md](../../NOTES.md#gpu-support) in the repo root.
 
 ---
 
-## Workloads
+## Routing
 
-A workload is a saved job configuration. Once saved, you can rerun it by name instead of retyping all the flags. Badgr tracks success rate, average cost, average runtime, and the last known-good route so reruns are faster and cheaper over time.
+`--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.
 
-**Save a workload** by adding `--save <name>` to any `badgr run` call:
+Preview any command before provisioning with `--dry-run`, e.g.:
 
 ```bash
-badgr run . --cmd "python train.py" --gpu A100 --env HF_TOKEN=$HF_TOKEN --max-cost 10 --save my-training-job
+badgr serve meta-llama/Llama-3.1-8B-Instruct --dry-run
 ```
 
-**Rerun a saved workload:**
+---
 
-```bash
-badgr workload run my-training-job
-badgr workload run my-training-job --max-cost 5          # override spend cap
-badgr workload run my-training-job --set HF_TOKEN=newval # override an env var
-```
+## Advanced
+
+Less common commands — training, transcription, embeddings, and the workload/workspace trackers. Same flags as `run`/`serve` unless noted (see [Common flags](#common-flags)).
 
-**Inspect and manage workloads:**
+### `badgr train` / `badgr train lora`
 
 ```bash
-badgr workload list                  # list all saved workloads with stats
-badgr workload info my-training-job  # stats, route history, recent jobs
-badgr workload delete my-training-job
+badgr train config.yaml --gpu A100 --max-runtime 240 --env HF_TOKEN=$HF_TOKEN
 ```
 
-| `badgr workload run` flag | Description |
-|---|---|
-| `--max-cost <$>` | Override the saved spend cap for this run |
-| `--max-runtime <min>` | Override the saved runtime limit for this run |
-| `--set KEY=VALUE` | Override a saved config value for this run (repeatable) |
-
----
-
-## Workspaces
-
-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.
+Detects framework (axolotl, unsloth, trl) from the config file, but **only Axolotl configs run today** — `unsloth`/`trl`/unrecognized configs are blocked before provisioning rather than billing a GPU that's guaranteed to fail. Default max-runtime is 120 min.
 
 ```bash
-badgr workspace create my-project --storage s3://my-bucket/runs --desc "nightly evals"
-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
+badgr train lora --base-model mistralai/Mistral-7B-v0.1 --dataset ./train.jsonl --preset small --max-cost 20
 ```
 
-| `badgr workspace create` flag | Description |
-|---|---|
-| `--storage <path>` | S3/GCS path to associate with this workspace |
-| `--desc <text>` | Optional description |
-
----
-
-## Routing
-
-Badgr Auto selects the best eligible route based on GPU type, VRAM, availability, region, workload requirements, and reliability. Advanced users can optionally choose an execution tier or hardware constraint.
-
-Most users should use the default Badgr Auto route. Tiers are an optional advanced control.
+Productized LoRA training — pass a base model and dataset, no Axolotl config file needed. Badgr generates the config from a preset and returns a downloadable adapter.
 
-**Tier 1** (default) — Reliable execution. Best for production workloads, model serving, and jobs where startup reliability matters most. Uses managed routing, readiness checks, fallback, and teardown controls.
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--framework <name>` | auto-detect | Force framework: `axolotl`, `unsloth`, `trl` (only `axolotl` currently runs) |
+| `--base-model <id>` | — | HuggingFace model ID (required for `train lora`) — validated to exist before provisioning |
+| `--dataset <path\|url>` | — | Local file, direct URL, or `s3://` URI |
+| `--file-id <id>` | — | Badgr upload ID instead of `--dataset` |
+| `--preset small\|medium` | `small` | `small` = RTX 4090, rank 16, 3 epochs. `medium` = A100, rank 32, 5 epochs |
+| `--gpu-type <type>` | preset default | GPU type override for `train lora` |
+| `--dry-run` | — | Preview the job without provisioning |
 
-**Tier 2** — Lower-cost burst execution. An optional advanced control for cost-sensitive workloads. Availability may vary.
+On completion, `train lora` prints an `adapter_url` — download with `GET /v1/jobs/{job_id}/adapter`, or via `badgr workload info` if saved.
 
-Preview before provisioning:
+### `badgr transcribe`
 
 ```bash
-badgr serve meta-llama/Llama-3.1-8B-Instruct --dry-run
+badgr transcribe recording.mp3 --max-cost 2
 ```
 
----
+Whisper transcription. Accepts a public URL, S3/GCS URI, or a local file under 50 MB. Default max-runtime is 30 min.
 
-## Receipts
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model <name>` | `large-v3` | Whisper model |
+| `--language <code>` | — | Language hint (e.g. `en`, `fr`) |
+| `--output <format>` | — | Output format: `txt`, `srt`, `vtt` |
 
-Every `badgr serve` and `badgr run` action generates a receipt:
+### `badgr embed`
 
 ```bash
-badgr receipts        # last 10
-badgr receipts 50     # last 50
+badgr embed BAAI/bge-large-en-v1.5 documents.txt --max-cost 2
 ```
 
-Each receipt includes: receipt ID, GPU type, provisioning latency, price/hr, retry count, and status.
-
----
+Text embeddings via vLLM. Accepts a public URL, S3/GCS URI, or a local text file under 10 MB. Outputs JSONL (`{"text": ..., "embedding": [...]}`). Default max-runtime is 30 min.
 
-## OpenAI compatibility
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--batch-size <n>` | — | Embedding batch size |
 
-`badgr serve` provisions a vLLM endpoint that is fully OpenAI-compatible:
+### Workloads
 
-```python
-import os
-from openai import OpenAI
-
-# Export BADGR_ENDPOINT from the URL printed by `badgr serve`
-client = OpenAI(
-    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",
-    messages=[{"role": "user", "content": "Hello"}],
-)
-```
+A workload is a saved job configuration, created with `--save <name>` on `badgr run`. Rerun by name instead of retyping all the flags; Badgr tracks success rate, average cost, and the last known-good route.
 
-```js
-import OpenAI from "openai";
-const client = new OpenAI({
-  apiKey: process.env.BADGR_API_KEY,
-  baseURL: process.env.BADGR_ENDPOINT,  // URL printed by `badgr serve`
-});
+```bash
+badgr run . --cmd "python train.py" --max-cost 10 --save my-training-job
+badgr workload run my-training-job
+badgr workload list
+badgr workload info my-training-job
+badgr workload delete my-training-job
 ```
 
----
+| Subcommand | Description |
+|------------|-------------|
+| `list [n]` | List saved workloads |
+| `info <name>` | Stats, route history, recent jobs |
+| `run <name>` | Submit a new job using the workload's saved config (`--max-cost`, `--max-runtime`, `--set KEY=VALUE` to override) |
+| `delete <name>` | Delete the workload record |
 
-## GPU options
+### Workspaces
 
-Badgr Auto selects the best eligible GPU for your workload. Add `--gpu <type>` or `--min-vram <GB>` only when you need more control.
-
-Available GPU types may vary by region and current capacity. Run `badgr capacity` or use `--dry-run` to confirm availability before provisioning.
+Most users never need this — `badgr run .` handles upload, caching, and artifact storage automatically. Workspaces are for grouping jobs under a named cost/context bucket, optionally linked to S3/GCS storage.
 
-| Flag value | GPU | VRAM | Best for |
-|-----------|-----|------|---------|
-| RTX_3090 | NVIDIA RTX 3090 | 24 GB | Dev, inference |
-| RTX_4090 | NVIDIA RTX 4090 | 24 GB | Inference, training, dev |
-| L40S | NVIDIA L40S | 48 GB | Inference, vLLM, embeddings |
-| A100 | NVIDIA A100 | 40–80 GB | Training, inference |
-| H100 | NVIDIA H100 | 80 GB | Large model training |
-
-Additional GPU types may be routable depending on current capacity — check with `badgr capacity`.
+```bash
+badgr workspace create my-project --storage s3://my-bucket/runs --desc "nightly evals"
+badgr run . --cmd "python eval.py" --workspace my-project --max-cost 5
+badgr workspace info my-project
+badgr workspace list
+badgr workspace delete my-project
+```
 
-Pricing is confirmed before provisioning. Use `--dry-run` to see pricing before committing.
+### Other commands
 
-Full GPU support details: see [NOTES.md](../../NOTES.md#gpu-support) in the repo root.
+- `badgr capacity [--gpu <type>]` — check available GPU capacity right now
+- `badgr billing status` / `badgr billing add <amount>` — check balance / add funds
 
 ---
 

package/package.json

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

package/src/api.js

@@ -168,6 +168,24 @@ export async function terminateDeployment(config, deploymentId) {
   throw lastErr;
 }
 
+export function restartDeployment(config, deploymentId) {
+  return callApi(`/deployments/${deploymentId}/restart`, {
+    method: 'POST',
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: 30_000,
+  });
+}
+
+export function heartbeatDeployment(config, deploymentId) {
+  return callApi(`/deployments/${deploymentId}/heartbeat`, {
+    method: 'POST',
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: 10_000,
+  });
+}
+
 export function getDeploymentLogs(config, deploymentId) {
   return callApi(`/deployments/${deploymentId}/logs`, {
     apiKey: config.apiKey,