CLI Reference

Core Commands

`soup init`

Create a config file with interactive wizard or template.

bash
soup init [--template <template>] [--output <path>]

`soup train`

Start a training run.

bash
soup train [--config <path>] [--resume auto|<checkpoint>] [--wandb] [--tensorboard] [--deepspeed zero2|zero3|zero2_offload] [--fsdp full_shard|shard_grad|full_offload] [--yes]

`soup chat`

Interactive chat with a trained model.

bash
soup chat [--model <path>] [--base <model>] [--temperature <float>] [--max-tokens <int>]

`soup serve`

Start an OpenAI-compatible inference server.

bash
soup serve [--model <path>] [--backend transformers|vllm|sglang] [--port <int>] [--host <host>] [--tensor-parallel <n>] [--gpu-memory <float>] [--speculative-decoding <draft-model>] [--spec-tokens <n>] [--adapters <name>=<path>]

`soup export`

Export model to deployment format.

bash
soup export [--model <path>] [--format gguf|onnx|tensorrt|awq|gptq] [--quant <type>] [--output <path>]

`soup merge`

Merge LoRA adapter with base model.

bash
soup merge [--adapter <path>] [--base <model>] [--output <path>] [--dtype <type>]

`soup push`

Upload model to HuggingFace Hub.

bash
soup push [--model <path>] [--repo <user/repo>] [--private]

`soup eval`

Comprehensive model evaluation platform.

bash
soup eval benchmark [--model <path>] [--benchmarks <list>]
soup eval custom [--model <path>] [--tasks <path>]
soup eval judge [--model <path>] [--prompts <path>] [--judge <model>]
soup eval auto [--config <path>]
soup eval compare <run1> <run2>
soup eval leaderboard
soup eval human [--model-a <path>] [--model-b <path>] [--prompts <path>]

`soup deploy`

Deploy models to inference runtimes.

bash
soup deploy ollama [--model <path>] [--name <name>] [--system <prompt>] [--template <tpl>] [--parameter <key=val>]
soup deploy ollama --list
soup deploy ollama --remove <name>

`soup infer`

Batch inference on a list of prompts.

bash
soup infer [--model <path>] [--input <path>] [--output <path>] [--max-tokens <int>] [--temperature <float>]

`soup migrate`

Import config from competing tools.

bash
soup migrate --from llamafactory|axolotl|unsloth <input-file> [--output <path>] [--dry-run]

`soup recipes`

Browse and use ready-made training configs.

bash
soup recipes list                          # List all 30 recipes
soup recipes show <name>                   # Print recipe YAML
soup recipes use <name> [--output <path>]  # Copy to soup.yaml
soup recipes search <query>                # Search by model/task/size

Data Commands

bash
soup data inspect <path>                          # View dataset stats
soup data validate <path> [--format <fmt>]        # Check format compliance
soup data convert <path> --to <fmt> --output <f>  # Convert between formats
soup data merge <f1> <f2> --output <f> [--shuffle]  # Combine datasets
soup data dedup <path> [--threshold <float>]      # Remove duplicates
soup data stats <path>                            # Extended statistics
soup data generate --prompt "..." --count <n>     # Generate synthetic data
soup data generate --provider ollama|anthropic|vllm  # Multi-provider support
soup data generate --template code|conversation|qa|preference|reasoning  # Domain templates
soup data generate --quality-pipeline             # Validate + filter + dedup
soup data filter <path> [--coherence <f>] [--perplexity <n>]  # Quality filter
soup data sample <path> --strategy random|diverse|hard --count <n>  # Sample subset
soup data split <path> --ratio 0.8,0.1,0.1                 # Train/val/test split
soup data search <query>                                     # Search HuggingFace Hub
soup data preview <dataset_id>                               # Preview remote dataset
soup data download <dataset_id> [--output <path>] [--samples <n>]  # Download from HF
soup data register <name> --path <path> --format <fmt>       # Register local dataset
soup data unregister <name>                                  # Remove from registry
soup data registry                                           # List registered datasets

Experiment Commands

bash
soup runs                         # List all training runs
soup runs show <run_id>           # Detailed run info + loss curve
soup runs compare <run1> <run2>   # Side-by-side comparison
soup runs delete <run_id>         # Remove from database

Other Commands

bash
soup deploy ollama [--model <p>] [--name <n>]   # Deploy GGUF to Ollama
soup profile [--model <m>] [--task <t>]        # Estimate memory/speed/GPU
soup adapters list [--path <dir>]              # Scan for LoRA adapters
soup adapters info <path>                      # Adapter metadata
soup adapters compare <a> <b>                  # Side-by-side comparison
soup sweep --config <path> --param key=v1,v2   # Hyperparameter search
soup diff --model-a <p> --model-b <p>          # Compare two models
soup doctor                                     # Check system + dependencies
soup quickstart [--dry-run] [--yes]             # One-command demo
soup ui [--port <int>] [--no-browser]           # Launch web UI
soup version [--full]                           # Show version info

Global Flags

bash
soup --verbose <command>   # Full tracebacks instead of friendly errors

> Note: --verbose is a global flag — it must go before the command name, not after.