CLI

The CLI module provides a unified configuration system for Twinkle training scripts. It merges multiple configuration sources (environment variables, .env files, YAML configs, and command-line arguments) into a single Args dataclass with typed argument groups.

Resolution Order

Configuration sources are applied in order (later wins):

1. Dataclass defaults — sensible out-of-the-box values

2. .env file — project-local overrides

3. Environment variables — TWINKLE_ prefix or bare keys

4. YAML config file — --config path/to/config.yaml

5. CLI overrides — --key value (highest priority)

All keys are case-insensitive and dash/underscore equivalent.

Quick Start

from twinkle.cli import CLI

args = CLI.from_args()

# Access typed groups
print(args.model.model_id)
print(args.training.max_steps)
print(args.optimizer.learning_rate)

# Or get dictionaries for component construction
model_kwargs = args.get_model_args()
optimizer_kwargs = args.get_optimizer_args()

Argument Groups

Group	Class	Key Parameters
model	ModelArgs	model_id, mixed_precision, strategy, gradient_checkpointing
lora	LoraArgs	use_lora, lora_r, lora_alpha, lora_target_modules
dataset	DatasetArgs	dataset_id, subset_name, split, streaming
template	TemplateArgs	template_cls, max_length, truncation_strategy, enable_thinking
training	TrainingArgs	max_steps, batch_size, micro_batch_size, output_dir, save_steps
optimizer	OptimizerArgs	optimizer_cls, learning_rate, weight_decay, max_grad_norm
scheduler	SchedulerArgs	scheduler_cls, num_warmup_steps, t_max
loss	LossArgs	loss_cls, epsilon, beta, sft_weight
sampler	SamplerArgs	sampler_type, gpu_memory_utilization, tensor_parallel_size
sampling	SamplingArgs	max_tokens, temperature, top_k, top_p, num_samples
infra	InfraArgs	mode, nproc_per_node, model_gpus, sampler_gpus, dp_size
server	ServerArgs	config, host, port, ray_namespace
rl	RLArgs	num_generations, advantage_type, reward_fns
checkpoint	CheckpointArgs	save_optimizer, merge_and_sync, platform

YAML Configuration

# config.yaml
model_id: ms://Qwen/Qwen3.5-4B
mixed_precision: bf16
strategy: accelerate

use_lora: true
lora_r: 16
lora_alpha: 32

dataset_id: ms://swift/self-cognition
max_length: 4096

batch_size: 8
micro_batch_size: 2
max_steps: 200
learning_rate: 1e-5

mode: ray
nproc_per_node: 8
model_gpus: 4
sampler_gpus: 4

Command-Line Usage

# Use with YAML config
python train.py --config config.yaml

# Override specific values
python train.py --config config.yaml --learning_rate 5e-6 --max_steps 500

# Boolean flags
python train.py --use_lora --no_gradient_checkpointing

# Without config file (all from CLI)
python train.py --model_id ms://Qwen/Qwen3.5-4B --batch_size 4

Environment Variables

# TWINKLE_ prefix
export TWINKLE_MODEL_ID=ms://Qwen/Qwen3.5-4B
export TWINKLE_LEARNING_RATE=1e-5

# Or bare keys (when recognized)
export MODEL_ID=ms://Qwen/Qwen3.5-4B

Field Aliases

Some fields support aliases for convenience:

• learning_rate ↔ lr

• nproc_per_node ↔ num_gpus

• max_tokens ↔ max_new_tokens

• use_megatron=true → strategy=native_fsdp

Custom Config Sources

You can extend the CLI with custom configuration sources:

from twinkle.cli.cli import ConfigSource, Args, ConfigResolver

class RemoteConfigSource(ConfigSource):
    def __init__(self, url: str):
        self.url = url

    def load(self) -> dict:
        import requests
        return requests.get(self.url).json()

# Apply custom source
args = Args()
resolver = ConfigResolver(args)
resolver.apply(RemoteConfigSource('http://config-server/my-config').load())