distil-cli

Distil CLI

Environment

Windows users: The Distil CLI does not support Windows natively. Without WSL, users won't get the full experience — CLI commands won't run. They can fall back to the REST API via references/api-reference.md, or run the CLI inside WSL. Call this out early if the user is on Windows.

Default to Workflows for Training Tasks

If the user wants to train a model end-to-end (any phrasing — "help me train a model", "build me an SLM", "I want to fine-tune for X"), do NOT answer ad hoc from the reference files. Instead:

1. Initialize the run log. If this is a model-building workflow (not a pure lookup / Q&A), create model-building-log-<name>.md at the project root and write the opening entry (<name> = a descriptive slug for this project, which we'll later also use for distil model create). See references/tasks/maintain-run-log.md for format and append triggers. This fires once per project regardless of which workflow branch (dataset vs. traces) the user ends up on — individual workflow Step 0s do not duplicate the init.
2. Ask one disambiguating question: "Do you have a labeled dataset to start from, or production traces from an existing LLM application?"
3. Load the matching workflow:
   • Dataset → workflows/dataset-to-model.md
   • Traces → workflows/traces-to-model.md
4. Follow the workflow step-by-step. The workflow tells you which references to read at each step.

The workflows encode the right sequence, decision points, and checkpoints (e.g., confirming config before kicking off a 6+ hour training job, approving a trace-generated test set). Skipping the workflow and answering Q&A-style usually leads to skipped steps and missing analysis reports.

For specific lookup questions ("what's the API endpoint for X", "what does parameter Y mean", "how do I download predictions"), continue to use the routing table below — those don't need a workflow and don't need a run log.

Intent Detection

Route the user to the right reference file based on their intent. Read the referenced file BEFORE answering.

If multiple intents apply, read multiple files. For data preparation, always read both the overview and the task-specific file.

End-to-End Workflows (Use These First)

Getting Started & Platform

Task & Model Selection

Data Preparation

Always read references/tasks/prepare-data/overview.md first, then the task-specific file.

Pipeline Steps

Configuration & Metrics

Quick Platform Summary

The core flow is: create model → prepare data → upload → teacher evaluation → train → deploy. Teacher evaluation is a feasibility check — if the teacher can solve the task, the student will learn it. Training takes several hours and produces a downloadable model you can deploy locally (llama-cpp, vLLM) or via the platform.

For the longer write-up of what Distil Labs is and why, read references/platform-overview.md. For the list of supported task types, student models, and teacher models — always read references/model-catalog.md before recommending a specific model; availability changes over time.

Quickstart Checklist

Minimum steps to go from zero to a trained model. Read the relevant reference files for details on each step.

# 1. Install / update and authenticate
curl -fsSL https://cli-assets.distillabs.ai/install.sh | sh   # first-time install
distil update                                                  # if already installed — the platform evolves quickly
distil login

# 2. Create a model
distil model create my-model-name
# Note the model ID from the output

# 3. Prepare data files in a directory:
#    - job_description.json  (task objectives)
#    - config.yaml           (task type, student model, teacher model)
#    - train.csv             (20+ labeled examples)
#    - test.csv              (held-out evaluation set)

# 4. Upload data
distil model upload-data <model-id> --data ./my-data-dir

# 5. Run teacher evaluation (feasibility check)
distil model run-teacher-evaluation <model-id>
distil model teacher-evaluation <model-id>  # Check results
# Status values: JOB_NOT_STARTED, JOB_PENDING, JOB_RUNNING, JOB_SUCCESS, JOB_FAILURE, JOB_STOPPED

# 6. Train (long-running; never auto-start: get the user's explicit go-ahead first)
distil model run-training <model-id>
distil model training <model-id>  # Check status

# 7. Download and deploy
distil model download <model-id>
distil model deploy local <model-id>
distil model invoke <model-id>  # Get the curl command to query your model

Alternative: Train from traces — Instead of steps 3-4, prepare a traces.jsonl file with your production logs, a job_description.json, and a config.yaml, then run distil model upload-traces <model-id> --data ./my-traces-dir. See references/tasks/upload-and-process-traces.md for trace formats and task compatibility (note: question-answering-open-book is not supported via traces).

Instructions

Before Answering Any Question

1. Identify the user's intent using the routing table above.
2. Read the referenced file(s). Do not answer from memory alone — the reference files contain exact formats, constraints, and edge cases.
3. If the user's intent spans multiple topics (e.g., "help me prepare classification data and train"), read all relevant files.

Deterministic-First Principle

When helping users, exhaust all mechanical/lookup steps before engaging judgment. Check model compatibility constraints, file format requirements, and parameter defaults from the reference files first. Only then apply judgment for task selection, data quality assessment, or configuration tuning.

Data Preparation Rules

• Always read references/tasks/prepare-data/overview.md before any task-specific data file. The overview contains shared requirements (directory structure, min examples, file formats) that the task files assume you know.
• Ask the user what task type they need before preparing data. If unclear, read references/task-selection-guide.md and help them decide.
• Ask what student and teacher models they want. If unsure, read references/model-catalog.md. Default recommendation: Llama-3.2-1B-Instruct as student, openai.gpt-oss-120b as teacher.
• Before writing job_description.json, read references/job-description-guide.md for what makes each field good and which fields apply to which task type. Note in particular that input_description is only used by question-answering — including it for other task types has no effect.

In Claude Code

• Run CLI commands directly. Do not just tell the user what to run.
• Exception: never auto-start training. Do NOT run distil model run-training or distil model retune on your own initiative, not even when teacher evaluation clears the PROCEED threshold. Both start multi-hour, credit-burning jobs whose credits are hard to refund. Present the teacher-evaluation results and the final config, then wait for the user's explicit go-ahead (the workflows' "Confirm Before Training" step owns this gate; honor it even when the user asked you to "run the commands" generally). When in doubt, ask.
• After running distil model create, capture the model ID and use it in subsequent commands.
• Check status commands (upload-status, teacher-evaluation, training) to monitor progress.
• When training or evaluation is running, tell the user approximately how long it takes and suggest checking back.
• Polling long-running jobs: Copy the canonical polling loop from references/tasks/polling-jobs.md verbatim. Do not write your own grep loop or sleep N && command chain — the former picks the wrong status pattern half the time and the latter is blocked by Claude Code. Use while ...; do ...; sleep 60; done with the sleep inside the loop body.
• Status checks always use --output json | jq — never grep human-readable output. The default text output also omits some metrics (notably LLM-as-a-Judge), so for analysis always use --output json too.

In Claude.ai (Browser)

• Provide complete, copy-pasteable file contents (job_description.json, config.yaml, train.csv, test.csv).
• List the CLI commands the user should run in order, with their model ID placeholder.
• Explain what each command does and what to look for in the output.

When the User Wants to Improve a Model

Read workflows/improving-a-model.md. It covers both iteration cases — teacher eval below thresholds, and training results that don't pass the DEPLOY bar — and consolidates the levers (job description, data, synthgen/mutations, student/teacher choice, tuning parameters, retune).

It also owns the iteration-N/ directory convention (one directory per attempt, reports written unsuffixed inside it) and the token-burn awareness rule for iteration #3+ (each iteration costs re-upload + teacher-eval credits + Claude analysis tokens — confirm the plan before racing into another attempt).

Command Aliases

distil model = distil models = distil m — all three work identically.