CLI Reference¶

xaytune installs a xaytune command-line tool for running training, evaluation, export, and component listing from the terminal.

xaytune [command] [options]

Global Options¶

Flag	Description
`--version`	Print xaytune version and exit
`--help`	Show help message

train¶

Run a training recipe from a YAML config file.

xaytune train --config <path> [--override key=value ...] [--resume] [--dry-run]

Option	Required	Description
`--config`	Yes	Path to a YAML config file
`--override`	No	Config override in dot notation (repeatable)
`--resume`	No	Resume training from the last checkpoint
`--dry-run`	No	Validate and print the resolved config as JSON without training

Examples¶

# Basic training run
xaytune train --config configs/examples/lora_finetune.yaml

# Override model and learning rate
xaytune train --config configs/examples/lora_finetune.yaml \
    --override model.name=mistralai/Mistral-7B-v0.3 \
    --override trainer.learning_rate=1e-4

# Validate config without training
xaytune train --config configs/examples/lora_finetune.yaml --dry-run

# Resume from checkpoint
xaytune train --config configs/examples/lora_finetune.yaml --resume

eval¶

Evaluate a model on benchmarks or a custom dataset.

xaytune eval --model <path> [--benchmarks <list>] [--dataset <path>] [--metrics <list>] [--num-fewshot <n>]

Option	Required	Description
`--model`	Yes	Model path or Hugging Face Hub name
`--benchmarks`	No	Comma-separated benchmark names (e.g., `mmlu,gsm8k`)
`--dataset`	No	Path to a JSONL evaluation dataset
`--metrics`	No	Comma-separated metric names (e.g., `loss,perplexity`)
`--num-fewshot`	No	Number of few-shot examples for benchmarks

Note

Provide either --benchmarks or --dataset, not both.

Examples¶

# Benchmark evaluation
xaytune eval --model output/my-finetune --benchmarks mmlu,gsm8k --num-fewshot 5

# Custom dataset evaluation
xaytune eval --model output/my-finetune --dataset data/eval.jsonl --metrics loss,perplexity

export¶

Export and convert models. Has three subcommands: merge, gguf, and push.

export merge¶

Merge LoRA adapters into the base model.

xaytune export merge --checkpoint <path> --output <path>

Option	Required	Description
`--checkpoint`	Yes	Path to a LoRA/QLoRA checkpoint directory
`--output`	Yes	Output directory for the merged model

export gguf¶

Convert a model to GGUF format.

xaytune export gguf --model <path> --output <path> [--quant <type>]

Option	Required	Default	Description
`--model`	Yes	--	Path to model directory
`--output`	Yes	--	Output GGUF file path
`--quant`	No	`Q4_K_M`	Quantization type

export push¶

Push a model to the Hugging Face Hub.

xaytune export push --model <path> --repo <repo>

Option	Required	Description
`--model`	Yes	Path to model directory
`--repo`	Yes	HF Hub repo name (e.g., `username/model-name`)

Examples¶

# Full export pipeline
xaytune export merge --checkpoint output/lora-finetune --output output/merged
xaytune export gguf --model output/merged --output model.gguf --quant Q5_K_M
xaytune export push --model output/merged --repo username/my-model

compare¶

Compare two models side-by-side on the same benchmarks.

xaytune compare <model_a> <model_b> --benchmarks <list> [--num-fewshot <n>]

Option	Required	Description
(positional)	Yes	Exactly two model paths
`--benchmarks`	Yes	Comma-separated benchmark names
`--num-fewshot`	No	Number of few-shot examples

Example¶

xaytune compare output/model-a output/model-b --benchmarks mmlu,gsm8k,hellaswag

Output is a table showing scores for each model across all benchmark metrics.

list¶

List registered components (recipes, data formats, metrics, reward functions).

xaytune list [type]

Argument	Required	Description
`type`	No	Component type: `recipes`, `formats`, `metrics`, `rewards`

If no type is given, all registries are listed.

Examples¶

# List everything
xaytune list

# List only data formats
xaytune list formats

# List only metrics
xaytune list metrics

Experiments on the local daemon¶

submit, attach, status, watch, events, results, actions, cancel, approve and reject work on experiments controlled by a local daemon (python -m xaytune.daemon, see Control-plane concepts). The commands run no controller: each reads the state database or sends the daemon a request, which the daemon carries out.

xaytune submit experiment.yaml --state state.db

Every command takes --state <path>, which defaults to $XAYTUNE_STATE.

Command	What it does
`submit SPEC`	Send an `ExperimentSpec` (YAML or JSON); print the experiment id once the daemon has admitted it and started its first run, then exit
`attach ID`	Ask the daemon to adopt an experiment already in the database
`status ID [--json]`	Where the experiment stands now
`watch ID [--timeout S]`	Print its events until the daemon has nothing left to do for it, then its status
`events ID [--after N] [--follow] [--json]`	Its durable events
`results ID [--no-wait] [--timeout S]`	Wait like `watch`, then print the `ExperimentResult` as JSON
`actions ID [--json]`	Its actions, with status and policy verdict: approvals awaiting a human among them
`cancel ID [--reason R]`	Ask the daemon to cancel it
`approve ACTION_ID --reason R [--approver NAME]`	Approve an action awaiting approval, as a human (default: your user name)
`reject ACTION_ID --reason R [--approver NAME]`	Reject it

The mutating commands (submit, attach, cancel, approve, reject) print request <id> to stderr before sending their request, and take:

Option	Description
`--request-id ID`	Send that request again. After a command was killed, this retries it -- the same request, never carried out twice -- or reports how it ended
`--timeout S`	Stop waiting for the daemon after S seconds. The request stays in the database, for the daemon to carry out

Killing any of these commands is safe: a request is the daemon's once it is sent, and nothing the command is waiting for depends on it. With no daemon running, a request waits in the database until one starts; the command says so.

Exit status: 0 on success, 1 when the daemon refused the request (the error it raised is printed), the wait timed out or the experiment does not exist, 2 for a missing --state.

studio-web¶

Serve the read-only Studio API over a control-plane state database.

xaytune studio-web [--state <path>] [--host 127.0.0.1] [--port 8765]

Option	Required	Description
`--state`	Yes, or `$XAYTUNE_STATE`	The state database. Opened read-only and never migrated
`--host`	No	A loopback address (default `127.0.0.1`). Any other host is refused: the API has no authentication
`--port`	No	Port (default `8765`)

Exits with code 2 for a missing state database, a file that is not one, or a non-loopback host. Requires pip install xaytune[studio-web].

Example Config Files¶

xaytune ships example configs in configs/examples/:

File	Description
`full_finetune.yaml`	Full parameter fine-tuning
`lora_finetune.yaml`	LoRA fine-tuning
`qlora_finetune.yaml`	QLoRA fine-tuning
`pretrain.yaml`	Pre-training
`dpo_align.yaml`	DPO alignment
`grpo_align.yaml`	GRPO alignment
`orpo_align.yaml`	ORPO alignment
`simpo_align.yaml`	SimPO alignment
`ppo_align.yaml`	PPO alignment
`reinforce_align.yaml`	REINFORCE alignment