CLI Reference

KladML includes a command-line interface for common tasks.

Hierarchy Overview

KladML organizes work in a 4-level hierarchy:

Workspace > Projects > Family > Experiment > Run

Project: Top-level container (e.g., sentinella)
Family: Groups related experiments (e.g., glucose_forecasting)
Experiment: A specific model/approach (e.g., gluformer_v4)
Run: Single training execution with specific params

Global Commands

`kladml ui`

Launch the interactive Terminal User Interface (TUI). This provides a visual workspace to explore: - Projects, Families, and Experiments (Tree View) - Datasets (List and details) - Configs (File viewer) - Run Details (Parameters and Metrics)

kladml ui

`kladml version`

Show the installed version.

kladml version

`kladml --help`

Show all available commands.

Project Commands

`kladml project create`

Create a new project.

kladml project create <name> [--description TEXT]

`kladml project list`

List all projects.

kladml project list

`kladml project show`

Show project details.

kladml project show <name>

`kladml project delete`

Delete a project.

kladml project delete <name> [--force]

Family Commands

Families group related experiments within a project.

`kladml family create`

Create a new family under a project.

kladml family create -p <project> -n <name> [-d DESCRIPTION]

Example:

kladml family create -p sentinella -n glucose_forecasting -d "Blood glucose prediction models"

`kladml family list`

List families in a project.

kladml family list -p <project>

`kladml family delete`

Delete a family.

kladml family delete <name> -p <project> [--force]

Experiment Commands

`kladml experiment create`

Create a new experiment under a family.

kladml experiment create -p <project> -f <family> -n <name>

Example:

kladml experiment create -p sentinella -f glucose_forecasting -n gluformer_v4

`kladml experiment list`

List experiments (grouped by family).

kladml experiment list -p <project> [-f <family>]

`kladml experiment runs`

List runs in an experiment.

kladml experiment runs <experiment-name> [--max N]

Run Commands

`kladml run native`

Run a training script using your local Python environment.

kladml run native <script> [OPTIONS]

Options:

Option	Default	Description
`--experiment`, `-e`	`default`	Experiment name for tracking

Example:

kladml run native train.py --experiment baseline

`kladml run local`

Run a training script inside a Docker/Podman container.

kladml run local <script> [OPTIONS]

Arguments:

Argument	Description
`script`	Path to the Python script to run

Options:

Option	Default	Description
`--experiment`, `-e`	`default`	Experiment name for tracking

Example:

kladml run native train.py --experiment baseline

Training Commands

`kladml train quick`

Recommended - Quick training without database setup.

kladml train quick [OPTIONS]

Options:

Option	Required	Description
`--config`, `-c`	Yes	Path to YAML config file
`--train`, `-t`	Yes	Path to training data (`.pkl` or `.h5`)
`--val`, `-v`	No	Path to validation data
`--model`, `-m`	No	Model name (default: `gluformer`)
`--device`, `-d`	No	Device: `auto`, `cpu`, `cuda`, `mps`
`--resume`, `-r`	No	Resume from latest checkpoint

Examples:

# Basic training
kladml train quick -c data/configs/my_config.yaml -t train.pkl -v val.pkl

# Resume interrupted training
kladml train quick -c data/configs/my_config.yaml -t train.pkl --resume

`kladml train single`

Full training with project and experiment tracking (requires database setup).

kladml train single [OPTIONS]

Options:

Option	Required	Description
`--model`, `-m`	Yes	Model architecture name (e.g., `gluformer`)
`--data`, `-d`	Yes	Path to training data
`--val`	No	Path to validation data
`--project`, `-p`	Yes	Project name
`--family`, `-f`	No	Family name (default: `default`)
`--experiment`, `-e`	Yes	Experiment name
`--config`, `-c`	No	Path to YAML config file

Example:

kladml train single --model gluformer --data train.h5 --project sentinella --experiment v1

`kladml train grid`

Run a grid search over hyperparameters.

kladml train grid [OPTIONS]

The configuration file must define lists of values for grid search.

Example:

kladml train grid --model gluformer --config grid.yaml --project sentinella --experiment tuning

Evaluation Commands

`kladml eval run`

Evaluate a trained model on test data.

kladml eval run [OPTIONS]

Options:

Option	Required	Description
`--checkpoint`	Yes	Path to model checkpoint (`.pt` file)
`--data`	Yes	Path to test data
`--model`	No	Model type (default: auto-detect)
`--output`	No	Output directory for results
`--device`	No	Device: `auto`, `cpu`, `cuda`

Example:

kladml eval run --checkpoint best_model_jit.pt --data test.pkl --output eval_results/

Output includes: - Metrics (MAE, RMSE, MAPE, Coverage) - Plots (predictions, error distribution, scatter) - JSON metrics file and markdown report

`kladml eval info`

Show available evaluators for each model type.

kladml eval info

Data Commands

`kladml data inspect`

Analyze a .pkl dataset file.

kladml data inspect <path>

`kladml data convert`

Convert a dataset to efficient formats (Parquet, HDF5).

kladml data convert [OPTIONS]

Options:

Option	Required	Description
`--input`, `-i`	Yes	Input `.pkl` file path
`--output`, `-o`	Yes	Output file path (`.parquet` or `.h5`)
`--format`, `-f`	No	Format: `parquet`, `hdf5` (default: `hdf5`)
`--compression`	No	Compression (gzip, zstd). Default: gzip/zstd

Example:

kladml data convert -i train.pkl -o train.parquet --format parquet

Configuration Management

`kladml config create`

Generate a 'smart' configuration file for a model using dataset heuristics.

kladml config create [OPTIONS]

Options:

Option	Required	Description
`--model`, `-m`	Yes	Model name (e.g. `gluformer`)
`--data`, `-d`	No	Path to training data for auto-tuning
`--output`, `-o`	No	Output path (default: `config.yaml`)

Example:

# Generate config tailored to your dataset
kladml config create --model gluformer --data data/train.parquet

Environment Variables

KladML respects these environment variables:

Variable	Description
`KLADML_TRAINING_DEVICE`	Override default device (`cpu`, `cuda`, `mps`)
`KLADML_STORAGE_ARTIFACTS_DIR`	Directory for saving artifacts
`KLADML_EXPERIMENT`	Default experiment name

Hyperparameter Tuning

`kladml tune`

Run automated hyperparameter tuning using Optuna.

kladml tune [OPTIONS]

Options:

Option	Required	Description
`--config`, `-c`	Yes	Path to YAML config file
`--n-trials`, `-n`	No	Number of trials (default: 50)
`--timeout`	No	Maximum tuning time in seconds
`--pruner`	No	Pruning strategy: `median`, `hyperband` (default: `median`)
`--study-name`	No	Name for the Optuna study
`--storage`	No	Database URL for distributed tuning

Examples:

# Basic tuning
kladml tune --config config.yaml --n-trials 50

# With timeout
kladml tune --config config.yaml --n-trials 100 --timeout 3600

# Distributed tuning with shared database
kladml tune --config config.yaml --storage sqlite:///optuna.db --study-name my-study

Output: - Best configuration saved to best_config.yaml - Optimization history plot - Parameter importance plot

Run Comparison

`kladml compare`

Compare multiple training runs visually.

kladml compare --runs <run_ids> [OPTIONS]

Options:

Option	Required	Description
`--runs`, `-r`	Yes	Comma-separated list of run IDs
`--metric`, `-m`	No	Metric to compare (default: `val_loss`)
`--output`, `-o`	No	Output directory for comparison plots

Examples:

# Compare two runs
kladml compare --runs run_001,run_002 --metric val_loss

# Compare multiple runs
kladml compare --runs run_001,run_002,run_003 --metric accuracy --output comparisons/

Output: - Tabular comparison of Metrics (all logged metrics) - Tabular comparison of Parameters (hyperparameters, config) - Side-by-side view for direct analysis

Component Registration

`kladml registry add`

Register custom components (architectures, preprocessors, evaluators).

kladml registry add [OPTIONS]

Component Types:

Type	Description
`model`	Custom model architecture
`preprocessor`	Custom data preprocessor
`evaluator`	Custom evaluator

Options:

Option	Required	Description
`--name`, `-n`	Yes	Name for the component
`--path`, `-p`	Yes	Path to artifact file/dir
`--type`, `-t`	Yes	Type (model, preprocessor, etc.)
`--tag`	No	Tags to attach

Examples:

# Register a custom architecture
kladml registry add --name MyTransformer --path src/models/my_transformer.py --type model --tag experimental

# Register a custom preprocessor
kladml registry add --name MyScaler --path src/data/scaler.pkl --type preprocessor

`kladml registry list`

List registered artifacts.

kladml registry list [OPTIONS]

Examples:

kladml registry list --type model
kladml registry list --tag production

`kladml registry show`

Show details of a registered artifact.

kladml registry show <name>