# Command Reference [← Back to the Soup README](../README.md) > The full `soup` command list. ## All Commands ``` soup init [--template chat|code|...|audio] Create config soup init --template hipaa|soc2|eu-ai-act|sr-11-7 Compliance-shaped starting config + the commands for that regime (v0.71.35) soup autopilot --model --data d.jsonl --goal Zero-configsoup train --config soup.yaml Start training soup train --config soup.yaml --tensorboard Train with TensorBoard logging soup train --config soup.yaml --replay old.jsonl --replay-ratio 0.1 Continual-learning rehearsal: interleave old data so the new task doesn't erase it (sft/pretrain) soup train --config soup.yaml --fsdp full_shard Train with FSDP2 soup train --config soup.yaml --deepspeed zero++ DeepSpeed ZeRO++ (quantized comms) soup train --config soup.yaml --gpus auto|N Multi-GPU launch hint soup train --config soup.yaml --gate evals/gate.yaml Eval-gated training soup train --config soup.yaml --push-as user/repo Auto-push each checkpoint to HF as branch soup train --config soup.yaml --push-as user/repo --hf-resume Resume from latest HF checkpoint branch soup train --config soup.yaml --find-lr LR range finder: write recommended LR JSON soup train --config soup.yaml --cloud modal --gpu a100 Render a Modal.com app for serverless GPU training (plan-only; --cloud-submit submits live) soup infer --model ./output --input p.jsonl Batch inference soup infer --task asr --model --input a.jsonl --output o.jsonl [--audio-dir d --asr-language en --asr-task transcribe|translate] Whisper transcription + WER/CER soup chat --model ./output Interactive chat soup push --model ./output --repo user/name Upload to HuggingFace soup push --model ./output --repo user/name --collection user/coll-abc123 Add to HF Collection soup merge --adapter ./output Merge LoRA with base model soup merge-sharded-fsdp-weights ./shards -o merged.safetensors Consolidate FSDP shards into one safetensors (v0.71.14; --plan-only previews) soup delinearize-llama4 ./src --target ./out [--num-experts N] [--plan-only] Live Llama-4 fused-expert reshape [E*din,dout] -> [E,din,dout] + sidecar copy (v0.71.21) soup spectrum scan --model --top-percent 50 [--modules mlp,attn] [-o patch.yaml] Spectrum SNR scan (no model load) -> training.unfrozen_parameters YAML patch (v0.71.23) soup train --config sft.yaml # training.lisa_enabled: true [lisa_num_layers lisa_interval_steps] LISA layerwise importance sampling β€” full-FT quality at LoRA-like memory (sft/transformers/text/quantization=none) (v0.71.34) soup train --config sft.yaml # training.stream_layers: true [stream_source stream_buffers] BETA layer streaming β€” the frozen base streams from CPU RAM one decoder layer at a time, so peak VRAM is bounded by ONE layer (sft/transformers/text/quantization=none, batch 1) (v0.72.0) soup export --model ./output --format gguf Export to GGUF (Ollama) soup export --model ./output --deploy ollama Export GGUF + auto-deploy to Ollama soup export --model ./output --format onnx Export to ONNX soup export --model ./output --format tensorrt Export to TensorRT-LLM soup export --model ./output --format awq Export to AWQ (4-bit) soup export --model ./output --format gptq Export to GPTQ (4-bit) soup deploy ollama --model m.gguf --name x Deploy GGUF to Ollama soup deploy ollama --list List Soup-deployed models soup deploy ollama --remove Remove model from Ollama soup deploy hf-space --model user/m --space user/s --template gradio-chat|streamlit-chat Create HF Space soup deploy autopilot --target mac-m3|rtx-4090-24gb|... Pick PEFT+quant+spec-decoding for a hardware target soup deploy autopilot --list List all 10 deploy profiles soup agent synth --spec api.yaml -o ds.jsonl Parse OpenAPI/MCP/GraphQL spec into a tool-calling SFT dataset soup agent train --spec api.yaml --base model One-shot synth + planned soup train invocation soup agent eval --spec api.yaml --predictions p.jsonl Score predicted tool-calls vs spec catalog soup agent eval --spec api.yaml --predictions p.jsonl --sandbox Execute each tool-call in the RLVR sandbox: ok/tool_error/timeout/arg_error soup eval benchmark --model ./output Evaluate on standard benchmarks soup eval custom --tasks eval.jsonl Custom eval tasks from JSONL soup eval judge --target resp.jsonl LLM-as-a-judge evaluation soup eval auto --config soup.yaml Auto-eval from config soup eval compare Compare eval results soup eval leaderboard Local model leaderboard soup eval human --input p.jsonl Human A/B evaluation soup eval gate --suite gate.yaml Run eval-gate suite standalonesoup eval quant-check --before X --after Y --tasks t.jsonl Before/after quantsoup serve --model ./output --port 8000 OpenAI-compatible API server soup serve --model ./output --backend vllm vLLM backend (2-4x throughput) soup serve --model ./output --backend sglang SGLang backend soup serve --model ./output --backend mii DeepSpeed-MII backend (live) soup serve --model ./output --speculative-decoding draft-model Speculative decoding soup serve --model --auto-spec Auto-pair draft model for speculative decoding soup serve --model --backend vllm --prefix-cache vLLM prefix caching (RAG/agent) soup serve --model --structured-output json --json-schema s.json Constrained output soup serve --model --structured-output regex --regex-pattern '...' Regex-constrained output soup serve --model --dashboard Live dashboard + /metrics endpoint soup serve --model --trace --trace-endpoint http://localhost:4317 OpenTelemetry tracing soup serve --model --trace-log ./serve.jsonl Per-request JSONL log + rotation + secret redaction soup serve --model --record-thumbs ./rl.db Capture πŸ‘/πŸ‘Ž feedback into local-RL SQLite + POST /v1/thumbs (transformers) soup serve --model --kv-cache-type bf16|f16|q8_0|fp8 KV-cache type (transformers; q8_0 needs hqq; fp8 = vLLM+Hopper only) (v0.71.14) POST /v1/adapters/activate/ Hot-swap active LoRA adapter soup sweep --config soup.yaml --param lr=... Hyperparameter search soup diff --model-a ./a --model-b ./b Compare two models soup data inspect View dataset stats soup data validate Check format (auto-detect) soup data doctor --model Chat-template compat report: 8 checks, OK/MINOR/MAJOR soup data doctor --model --show-mask N Per-token trained/masked colouring via the real collator soup data lint Preference-data linter: length bias, near-dups, chosen==rejected soup data convert --to chatml Convert between formats soup data merge data1.jsonl data2.jsonl Combine datasets soup data dedup --threshold 0.8 Remove duplicates (MinHash) soup data dedup --semantic Dedup by embedding cosine β€” catches rewordings MinHash misses ([train]) soup data topics [--clusters N|auto] Cluster + c-TF-IDF labels + coverage table + thin-topic warnings ([train]) soup data canary insert -o --manifest Insert K secrets to later prove memorization (manifest = SECRET) soup data canary check --manifest --base Rank each secret's loss vs never-inserted controls; exit 2 = leak soup data stats Extended statistics soup data generate --prompt "..." --count 100 Generate synthetic data soup data generate ... --provider ollama Use local Ollama instance soup data generate ... --provider anthropic Use Claude API soup data generate ... --provider vllm Use local vLLM server soup data generate ... --template code Domain templates (code/conversation/qa/preference/reasoning) soup data generate ... --quality-pipeline Auto validate + filter + dedup soup data augment --strategy rephrase|translate|style [--provider ollama|vllm --model --base-url ] LLM-driven augmentation soup data from-traces --logs l.jsonl --format langchain --signal thumbs_up --output p.jsonl Preference pairs from traces soup data from-traces ... --judge --min-confidence 0.7 LLM-judge confidence filter soup data review prefs.jsonl --sample 10 Preview preference pairs soup data filter --coherence 0.3 Quality filter (perplexity/coherence) soup data sample --n 1000 Random sample subset soup data sample --n 1000 --strategy diverse Cluster-based diverse sampling soup data sample --n 1000 --strategy hard Sample hardest examples soup data sample --pct 10 Sample by percentage soup data split --val 10 --test 10 Split into train/val/test soup data split --val 500 --absolute Split with absolute counts soup data split --val 10 --stratify category Stratified by field soup data search "code instructions" Search HuggingFace Hub for datasets soup data search --sort likes --limit 10 Sort and paginate search results soup data preview teknium/OpenHermes-2.5 Preview remote dataset metadata soup data download user/dataset -o data.jsonl Download HF dataset as JSONL soup data download user/ds --samples 1000 Stream first 1000 samples soup data register --name my-ds --path d.jsonl --format alpaca Register dataset soup data unregister --name my-ds Remove from registry soup data push --input d.jsonl --hf-dataset user/name Upload local JSONL as HF dataset soup data push --input d.jsonl --hf-dataset u/n --hub modelscope|modelers Upload to an alternative hub soup data registry List all registered datasets soup data demo List bundled demo JSONL fixtures soup data demo alpaca_demo --output ./d.jsonl Copy a bundled demo JSONL fixture soup data forge --docs ./docs --task sft --target-rows 1000 Synthetic data pipeline + provenance soup data forge --docs ./docs --hub modelscope --teacher owner/name Pre-fetch the teacher from an alternative hub soup data score --input rows.jsonl Composite quality scorecard (PII + toxicity + lang + edu) soup data decontaminate --input rows.jsonl --benchmarks mmlu,gsm8k Drop benchmark-overlap rows soup data toxicity --input rows.jsonl -o tox.jsonl Flag toxic rows (keyword baseline) soup data langdetect --input rows.jsonl -o tagged.jsonl Tag each row with language code soup data pii --input rows.jsonl -o pii.jsonl Flag rows containing email/phone/SSN/credit-card soup data educational --input rows.jsonl -o scored.jsonl Score educational value per row soup train --config soup.yaml --tracker mlflow MLflow / SwanLab / Trackio integration soup profile --config soup.yaml Estimate memory/speed before training soup profile --config soup.yaml --gpu a100 Estimate for specific GPU soup profile --config soup.yaml --json Machine-readable output soup cost --config soup.yaml Estimate training cost in USD across providers soup cost --config soup.yaml --gpu H100 Estimate training cost for specific GPU soup adapters list ./output/ Scan for LoRA adapters soup adapters info ./output/checkpoint-500/ Show adapter metadata soup adapters compare adapter1/ adapter2/ Compare two adapters soup loop init --eval --baseline [--pre-wired] Create .soup/loop.yaml (data flywheel; --pre-wired = real stages) soup loop status Counters + status + pre_wired flag soup loop watch [--detach] [--max-iter N] [--pre-wired] [--pack-cans] Harvest β†’ train β†’ gate β†’ deploy daemon (pre-wired stages + Soup Can packing) soup loop pause / soup loop resume Atomic status flip soup loop canary --traffic 5% Promote canary + auto-rollback on MAJOR soup loop replay [] [--extract ] Replay / unpack a recorded iteration manifest soup serve --model m --adapters chat=./c code=./d Multi-adapter serving soup migrate --from llamafactory config.yaml Import config from LLaMA-Factory soup migrate --from axolotl config.yml Import config from Axolotl soup migrate --from unsloth notebook.ipynb Import config from Unsloth notebook soup migrate --from llamafactory c.yaml --dry-run Preview without writing soup recipes list List all 142 ready-made recipes soup recipes show llama3.1-8b-sft Print recipe YAML soup recipes use llama3.1-8b-sft Copy recipe to soup.yaml soup recipes search "reasoning" Search by keyword/task/size soup registry push --run-id --name n --tag v1 Register runsoup registry list [--name n] [--tag v1] List registry entriessoup registry show Entry details + artifacts + ancestors soup registry diff Side-by-side config + eval delta soup registry search "medical" Search name/base/task/notes soup registry promote --tag prod Tag an entry (e.g. promote to prod) soup registry delete --yes Remove entry (cascades) soup history Lineage DAG tree for a namesoup can pack --entry-id --out r.can Pack registry entry as .cansoup can inspect r.can Preview manifest without extracting soup can verify r.can Verify schema + config parseability soup can fork r.can --out fork.can --modify training.lr=5e-5 Fork + re-pack soup can run r.can --yes [--deploy] [--env-capture env.txt] Run a .can end-to-end soup can publish r.can --hf-hub user/name Publish .can to HF Hub as dataset soup runs List training runs soup runs show Run details + loss graph + cost soup runs compare Compare two runs soup runs replay Replay summary + loss curve from history (also plots a benchmark-score curve when the metric lives in eval_results) soup why [run_id] Explain training anomalies (heuristic) soup ship --base --adapter --task-eval t.jsonl SHIP / DON'T-SHIP verdict: task win AND no regression on the bundled suite (exit 0=SHIP / 2=DON'T / 3=usage / 1=runtime) (v0.71.25; leg-2 real + usage-off-2 v0.71.38) soup ship --evidence ev.json [--output v.json] Decide offline from pre-computed scores (no model load) soup ship ... --task-mode judge_score --judge-model ollama://llama3.1 Leg-1 via LLM-as-a-judge soup ship ... --task-mode pairwise --judge-model ollama://llama3.1 Leg-1 via swap-debiased judge win-rate (base=0.5) (v0.71.31) soup ship ... # leg-2 default = 7 bundled offline suites (MCQ/arithmetic + tool_call/format_json/safety, extraction scorer, ~40 items each) (v0.71.38) soup ship ... --general-suite mmlu,gsm8k --baseline base.json lm-eval leg-2 override + recorded base scores soup ship ... --emit-evidence ev.json Re-serialise the scores as replayable --evidence input (output-is-input, #312) (v0.71.39) soup ship ... --config soup.yaml Read eval.ship gate defaults; --evidence GATES on provenance, --emit-evidence STAMPS it (v0.71.39) soup ship ... --push owner/repo#N Post the verdict as a GitHub PR comment (best-effort; never flips the exit code) (v0.71.39) soup card -o MODELCARD.md HF model card from a registry entry: training config, evals, hashes, lineage, artifacts (v0.71.35) soup push --model ./out --repo you/m --card Upload that registry-driven card as the README (HF only) (v0.71.35) soup ci init [--data d.jsonl --suite s.yaml --evidence ev.json] [--config soup.yaml] [--branch main --python 3.11] [--force] Write .github/workflows/soup-gate.yml: data validate -> expect -> ship gate on every PR (v0.71.35); --config binds the gate to a committed config so it refuses stale evidence (v0.71.39) soup mcp serve MCP server over stdio (drive Soup from Claude Code / Cursor / Cline; requires [mcp] extra) (v0.71.28) soup mcp serve --allow-mutating Also expose plan-only train_start / export tools (never execute) (v0.71.28) soup shrink --model --drop-ratio 0.25 --calib c.jsonl -o shrunk Depth-prune least-important layer block + SHIP/DON'T-SHIP ppl verdict (exit 0/2/1) (v0.71.29) soup shrink ... --drop-layers N --heal h.jsonl --heal-steps 200 --device cpu Drop N layers + distill-heal (fuse LoRA back to one dense model) soup shrink ... --tolerance 0.10 --plan-only [--attach-to-registry ] Ppl-regression tolerance / print importance table only / registry attach soup draft measure --target --draft --prompts p.jsonl Draft acceptance rate + real plain-vs-assisted tok/s (exit 0/2/1) (v0.71.33) soup draft measure ... --min-acceptance 0.6 -o report.json Exit 2 below the floor (CI gate) / write the JSON report soup draft distill --target --draft-base --data d.jsonl -o draft/ Distil a DENSE speculative-decoding draft + register it (v0.71.33) soup draft distill ... --steps N --device cpu --force --plan-only Training budget / device / overwrite -o / render the config only soup draft list List local drafts that `soup serve --auto-spec` will pick up (v0.71.33) soup reward synth refs.jsonl -o reward.py Synthesize a deterministic reward verifier from gold outputs (v0.71.40) soup reward synth ... --kind numeric|json_schema|regex|tool_call Force a verifier family (default: auto-detect) soup reward synth ... --plan-only Report the induced spec + calibration plan; write nothing soup reward synth ... --output-report r.json --min-discrimination 0.5 Save the calibration JSON / set the refusal threshold (exit 0 emit / 2 refuse / 1 error) soup reward stress reward.py --references golds.jsonl Adversarially probe a verifier for gameability β€” empty/length/repetition/sentinel junk (v0.71.41) soup reward stress verifiable --verifiable-domain math --references golds.jsonl Probe a builtin verifier instead of a .py file soup reward stress ... --attacks empty,length,repetition,sentinel --sentinel GOLD --threshold 0.5 --max-gameable 0.0 Tune the attack set / accept threshold / tolerance soup reward stress ... --output-report r.json Save the per-attack report JSON (exit 0 robust / 2 gameable / 1 error) soup tui Full-screen Textual dashboard (requires [tui] extra) soup train --config soup.yaml --profile Record torch.profiler trace to /profiles/ soup --log-level quiet|normal|verbose|debug Global logging tier (Rich-formatted) soup ui [--port 7860] Web UI (experiments, training, data) soup ui --public [--auth-token T] Phone-scannable Web UI (v0.53.9) soup tokenizer train --input c.jsonl --vocab-size N Train BPE tokenizer (v0.53.9) soup bench --p50 --p95 Bench with tail-latency percentiles (v0.53.9) soup bench --backend auto Auto-detect transformers/mlx backend (v0.53.9) soup serve --reasoning-parser deepseek-r1 Strip blocks from responses (v0.53.9) soup doctor [--nccl] Check environment (optionally check NCCL bandwidth) soup quickstart [--dry-run] Full demo soup adapters scan Spectral backdoor scan (rank-1 dominance + outlier detection) soup adapters sign [--backend unsigned|ed25519] [--key |--generate-key ] Merkle manifest + ed25519 sign soup adapters verify [--strict] [--public-key ] Verify manifest + ed25519 signature soup adapters check-safetensors [--strict] Refuse pickle / PyTorch-classic weights soup adapters merge ... [--license ] [--license-override ] [--allow-unscanned] License + backdoor-scan gates (auto-detect license; scan FAIL refused) soup adapters arithmetic "coder + 0.5*math - toxic" --adapter coder=

--adapter math=

--adapter toxic=

-o [--allow-unscanned --allow-cross-base] Task-vector algebra over LoRA adapters (add/scale/negate; same-rank; scan + same-base gated) (v0.71.34) soup attest emit ... [--sign ed25519 --key ] [-o att.json] in-toto/SLSA-3 attestation (+ .sig sidecar) soup attest verify --signature [--public-key ] Verify ed25519 attestation signature soup airgap-bundle --model --output [--repro-receipt ] Signed tarball for data-diode transfer (embeds repro-receipt) soup train --config soup.yaml --annex-xi EU AI Act Annex XI/XII doc (markdown or PDF; top_domains auto-filled) soup train --config soup.yaml --track-energy [--energy-country USA] codecarbon offline kWh/CO2 β†’ annex-xi (pip install soup-cli[carbon]) soup train --config soup.yaml --track-energy --energy-out persist measurement for `soup bom emit --energy ` soup train --config soup.yaml --repro-receipt SR 11-7 reproducibility receipt soup can pack --entry-id --out r.can --attest Embed in-toto Statements into a v3 can manifest soup audit-log tail / rotate Tail / rotate the per-command HIPAA/SOC2 audit log (~/.soup/audit.jsonl) soup --no-audit-log / SOUP_NO_AUDIT_LOG=1 Opt out of the per-command audit line soup eval unlearning --benchmark tofu|muse|wmdp Forget Quality + Model Utility + PrivLeak verdict soup edit set --base --method rome|memit|alphaedit|grace --subject "..." --target "..." [--output

] [--device cpu] [--governor/--no-governor] [--registry-id ] [--cov-corpus ] Live surgical knowledge edit (GPT-2 Conv1D + Llama; --cov-corpus = covariance-preconditioned ROME, rome-only; --plan-only available) soup edit diff --probes p.jsonl [--before-model --after-model ] Knowledge-injection diff (live before/after generation when both models given) soup train --task unlearn NPO/SimNPO/RMU unlearning from data.forget_set (+ optional data.retain_set) soup train # data.format='raft' Answer-only span-mask RAFT training (golden+distractor docs, [doc-N] citations); generator-stage configs auto-link the latest RA-DIT retriever soup ra-dit --retriever-config --generator-config [--retriever-model ] [--plan-only] One-shot two-stage RA-DIT: train retriever β†’ record pairing β†’ train generator soup eval citation [--style bracket|inline|footnote] [--shuffle-seed N] [--output o.json] Citation precision/recall/F1 over predictions or RAFT rows soup steer train --base --method caa|iti|repe --name --pairs Fit a CAA/ITI/RepE activation-steering vector from {positive, negative} pairs soup steer apply --name --strength Preview a stored steering vector; soup steer list lists them soup serve --steer [--steer-strength ] Apply a steering vector at decode time via a forward hook (transformers backend) soup serve --bank [--bank-strength ] Multi-tenant VeRA/VB-LoRA serving; active user per request via X-User-Id header, ContextVar-isolated (v0.71.12 / v0.71.17) soup serve --mole Serve a trained MoLE: base + N frozen task LoRAs + mole_gate.pt, blended per-token at decode (transformers-only) (v0.71.17) soup ingest --source langfuse|langsmith|helicone|openpipe|otel|openai-stored --logs Universal trace importer (6 SaaS adapters β†’ normalised JSONL) soup prune-prompt --input --output --min-frequency 0.95 Detect + strip shared system-prompt prefix soup prune-prompt ... --tokenizer Tokenizer-aware prefix detection (decodes remaining ids, boundary-safe) soup data active-sample --input --output --budget N Top-N uncertain prod traces for human review soup ab --input --metric latency|judge_score|retry_rate mSPRT sequential A/B (decision: continue / reject_h0 / accept_h0) soup ingest|prune-prompt|ab|data active-sample ... --slack-url | --discord-url Shared SSRF-validated webhook on completion soup drift-alarm --reference --live --threshold 0.2 Rolling-KL drift alarm (exit 3 on drift) soup drift-alarm ... --slack-url | --discord-url Optional SSRF-validated webhook on drift detected soup tunability --list List built-in candidate-base catalogue soup tunability --dataset [--candidates a,b,c] Probe candidate bases + Pareto frontier report soup tunability --dataset --live [--device cpu] LIVE per-candidate LoRA probe (loads each repo) soup plan --config soup.yaml Pre-flight summary + write soup.tfstate soup apply --config soup.yaml [--dry-run] Lock-and-execute; refuses on drift (exit 3) soup env lock | status | check Hermetic env lockfile + ABI drift detection (exit 3) soup env fix [--format uv-pip|requirements] [--output req.txt] Render a reproducible install plan from soup-env.lock (print-only) soup completions bash | zsh | fish Shell completion script (sourceable via eval) soup license-advisor --target b2c|defense|embedded Recommend license-clean base for deploy target soup license-advisor ... --license --mau N Per-license downstream-risk check (exit 3 on block) soup probe sae-diff [--top-k N] SAE feature diff between pre/post-FT activations (v0.66.0) soup probe sae-diff --auto-download Fetch an allowlisted SAE into ~/.soup/sae-cache (v0.71.8) soup probe sleeper [--evidence ev.json] [--weights w.npz] [--output o.json] Sleeper-agent defection probe; --weights = real calibrated probe (v0.66.0; v0.71.8) soup probe truth [--evidence ev.json] [--weights w.npz] [--output o.json] TruthfulQA-style honesty probe (v0.71.8) soup probe harm [--evidence ev.json] [--weights w.npz] [--output o.json] HarmBench-style misuse probe (v0.71.8) soup probe interference [--output o.json] Pairwise NΓ—N adapter interference matrix (exit 2 on MAJOR; v0.66.0) soup probe interference --measure --base-model --adapter name=path ... [--device cpu] Auto-measure live interference (v0.71.8) soup probe pack [--output o.json] Per-base calibrated probe pack manifest (v0.66.0; +truth/harm v0.71.8) soup probe pack --list List bundled probe-pack bases (v0.66.0) soup train --capture-activations --capture-prompts Post-train SAE-diff-ready per-token activation snapshot (v0.71.8) soup adapters blame ... --top-k 50 Live DataInf-style influence runner (v0.66.0, closes #171) soup adapters merge ... --strategy cmaes --eval --budget 1h CMA-ES evolutionary merge β€” live loop (v0.67.0 schema / v0.71.4 live) soup adapters merge ... --canary [--strict-verdict] Live OK/MINOR/MAJOR canary verdict, exit 2 on MAJOR (v0.71.4) soup adapters pr --base-sha <hex> --adapter <path> GitHub-shaped adapter PR Markdown / JSON (v0.67.0) soup adapters pr <title> ... --push owner/repo#N Post the PR as a GitHub comment via gh api (v0.71.4) soup adapters branch <name> --from-registry <id> | --attach-to-registry <id> Branch ↔ Registry lineage (v0.71.4) soup adapters bisect <ckpt>... --eval-command "..." Binary search over training history (v0.67.0) soup lock write --base-sha <h> --dataset-sha <h> --env-hash <h> Write soup.lock (v0.67.0) soup lock write --base-sha <h> --dataset-sha <h> --env-lock soup-env.lock Auto-derive --env-hash from soup-env.lock (v0.71.1) soup lock show / soup lock check Show + drift-check (exit 3 on drift) soup compile <program.py> --eval <suite> [--optimizer mipro|gepa|textgrad|copro|bootstrap_fewshot] [--plan-only] DSPy / GEPA / TextGrad prompt-program compiler β€” live (v0.71.13; pip install "soup-cli[compile]") soup distill-prompt --traces <jsonl> --teacher <m> --student <m> --strategy sft|preference|kl [--provider ollama|anthropic|vllm] [--base-url <url>] [--temperature F] [--max-rows N] Distill prompt-heavy traces via a live teacher (v0.71.13) soup compile-tools <spec.json|yaml> --eval <jsonl> [--optimizer textgrad|gepa] [--plan-only] TextGrad / GEPA tool-schema optimiser β€” live (v0.71.13; pip install "soup-cli[compile]") soup apple-adapter <source-dir> --direction hf-to-mlx|mlx-to-hf|hf-to-apple|mlx-to-apple --output <dir> [--sign] [--plan-only] PEFT LoRA <-> mlx-lm adapter conversion β€” live (v0.71.21; *-to-apple upstream-gated exit 3) soup local-rl init --db <path> Create personal-LLM flywheel SQLite schema (v0.68.0) soup local-rl status --db <path> Print interactions / thumbs-up / thumbs-down counters soup local-rl record --db <path> --prompt <q> --response <r> --thumb up|down Append thumbs record soup local-rl harvest --db <path> -o <pairs.jsonl> Harvest DPO pairs from thumbs into JSONL soup local-rl train --db <path> --model <id> --once [--train-method dpo|kto|orpo] [--min-pairs N] [-o <dir>] Ad-hoc DPO/KTO/ORPO train from harvested thumbs β€” live (v0.71.13) soup local-rl train --db <path> --model <id> [--scheduler-dir <dir>] [--hour H] [--minute M] Render a systemd/launchd nightly-train scaffold (no --once) (v0.71.13) soup build <manifest.yaml> [--dry-run] [--output-dir <dir>] dbt-for-SFT DAG: validate + plan + live materialise (v0.69.0; live v0.71.6) soup expect <data.jsonl> <suite.yaml> Expectations suite: PII / token-length / refusal / judge (v0.69.0) soup data gen-magpie --base <m> --provider ollama|vllm --target N --output <jsonl> [--base-url <url>] [--quality-filter] Magpie synthetic generator β€” live (v0.69.0; live v0.71.6) soup data best-of-n --base <m> --prompts <jsonl> --n 8 --judge <url> -o <sft.jsonl> [--emit-pairs <dpo.jsonl>] Best-of-N rejection sampling: sample N locally, judge picks winner -> SFT (+ DPO) rows (v0.71.31) soup data evolve --input <seeds.jsonl> --provider ollama|vllm --model <m> --strategy depth|breadth --rounds N -o <jsonl> Evol-Instruct (WizardLM) instruction evolution (v0.71.31) soup data persona-mix --prompts <jsonl> --n N --output <jsonl> Persona-Hub diversity sampler (v0.69.0) soup data brain-rot <data.jsonl> [--strict] Brain-rot detector β€” arXiv 2510.13928 (v0.69.0) soup iterative-dpo --base-model <m> --reward-model <rm> --prompts <p.jsonl> --output-dir <out> --rounds N --pairs-per-round N [--plan-only] Iterative DPO loop driver β€” LIVE sampleβ†’scoreβ†’pairβ†’train (v0.70.0; live v0.71.11) soup train --reward-hack-detector info_rm|rm_ensemble [--reward-hack-halt] Reward-hacking detector for GRPO β€” LIVE callback (v0.70.0; live v0.71.11) soup train --reward-hack-mitigation off|log_only|kl_control|pid_lagrangian Closed-loop reward-hacking auto-mitigation (detect β†’ raise KL/Ξ² β†’ rollback β†’ early-stop); GRPO/PPO, requires --reward-hack-detector; PPO BETA (v0.71.26) soup train --uld-strategy wasserstein|topk_align [--uld-top-k N] Cross-tokenizer ULD on task='distill' β€” LIVE W1/topk loss (v0.70.0; live v0.71.11) soup train --minillm-enabled [--minillm-teacher-mix-ratio 0.3] MiniLLM reverse-KL distillation β€” LIVE (v0.70.0; live v0.71.11) soup train --rl-checkpoint-save-every-steps N [--rl-checkpoint-keep-last N] Mid-epoch checkpoint for GRPO/PPO β€” LIVE (v0.70.0; live v0.71.11) soup train --echo-trap-enabled [--echo-trap-threshold 0.6 --echo-trap-halt] RAGEN echo-trap detector for GRPO β€” LIVE callback (v0.70.0; live v0.71.11) soup train # task='moe_lora_routing' + mole_task_adapters MoLE per-token gate over N frozen task LoRAs (gate-only train) β€” LIVE (v0.71.12) soup train # task='distill' + distill_mode=token|sequence Token logit-KL or sequence-level teacher-continuation KD β€” LIVE (v0.71.12) soup train # task=classifier|reranker|cross_encoder + lora LoRA-adapter classifier (frozen encoder) β€” LIVE (v0.71.12) soup train # use_mod | expand_layers | use_longlora Mixture-of-Depths / LLaMA Pro / LongLoRA SΒ² (Llama/Qwen/Mistral[/Phi]) β€” LIVE (v0.71.12) soup train # task='tts' + tts_family + modality='audio_out' TTS fine-tune via SFT CE over pre-encoded codec tokens; emotion templating; live-codec hw-gated β€” LIVE (v0.71.20) soup train # task in {sft,pretrain,dpo} + moe_expert_quant=nf4|int8_rowwise [+moe_lora] bnb per-expert quant of fused-MoE experts (CUDA) β€” LIVE (v0.71.20) soup train # train_router_only=true [+moe_lora] Freeze MoE experts, train only the gating router β€” LIVE (v0.71.20) soup train # quantization='bitnet_1.58' (sft/pretrain/dpo) BitNet 1.58 SFT (requires onebitllms) β€” LIVE-gated (v0.71.20) soup export --model ./output --format bitnet|tq1_0 BitNet 1.58 TQ1_0 ternary GGUF via llama.cpp β€” LIVE (v0.71.20) soup version [--full] [--json] Show version (--full: system info, --json: JSON output) soup --verbose <command> Full traceback on errors ``` ## Fine-tune from your coding agent (MCP) `soup mcp serve` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over **stdio**, so any MCP client β€” Claude Code, Cursor, Cline, Continue β€” can drive Soup conversationally. Install the extra first: ```bash pip install "soup-cli[mcp]" ``` Register it with your client. For **Claude Code** (`.mcp.json` in the repo) or the **Claude Desktop** config (`claude_desktop_config.json`): ```json { "mcpServers": { "soup": { "command": "soup", "args": ["mcp", "serve"] } } } ``` The server exposes 14 read-only tools β€” `advise`, `data_inspect`, `data_validate`, `data_score`, `data_doctor`, `recipes_search`, `recipes_show`, `runs_list`, `runs_show`, `registry_list`, `registry_show`, `profile`, `diagnose_evidence`, `ship_evidence` β€” each returning JSON. Two **plan-only** mutating tools (`train_start`, `export`) are gated behind `--allow-mutating` (`"args": ["mcp", "serve", "--allow-mutating"]`); even then they only render the exact command that would run β€” they never execute training or export. **Security:** stdio only (no network listener); every path argument stays under the working directory and rejects symlinks; tool output is control-char sanitized; error messages never leak filesystem paths.