cli

CLI Reference

llem provides four commands and a version flag.

llem run [CONFIG] [OPTIONS]   # run an experiment or study
llem doctor [OPTIONS]         # check environment health (GPU, engines, energy, Docker, config)
llem report-gaps [OPTIONS]    # propose engine rule set entries from runtime feedback
llem study [SUBCOMMAND]       # write and prepare study files (init, plan)
llem --version                # print version and exit

llem run

Run an LLM efficiency experiment

Arguments:

Argument	Type	Required	Description
config	path	no	Path to the experiment or study YAML config

Options:

Flag	Short	Type	Default	Description
--output	-o	str		Results directory for a fresh run; with --resume, the base directory searched for the study to resume
--dry-run		flag	false	Validate config and estimate VRAM without running
--quiet	-q	flag	false	Suppress progress bars
--verbose	-v	int	0	Increase verbosity (-v=INFO, -vv=DEBUG)
--skip-preflight		flag	false	Skip Docker pre-flight checks (GPU visibility, CUDA/driver compatibility)
--resume		flag	false	Resume most recent interrupted study
--resume-dir		path		Resume a specific study directory
--no-lock		flag	false	Disable GPU lock files (advanced)

llem doctor

Check environment health (GPU, engines, energy, Docker, config, image schema)

Options:

Flag	Short	Type	Default	Description
--check		flag	false	Exit 0=ok, 1=warnings, 2=errors (for CI/scripting). Output is unchanged.
--json		flag	false	Emit the full report as machine-readable JSON.

llem report-gaps

Propose engine rule set entries from runtime observations

Options:

Flag	Short	Type	Default	Description
--source		str	runtime-warnings	Feedback source to scan. Only 'runtime-warnings' is wired in this release.
--study-dir		path		Study directory to scan. Repeat the flag to pass multiple.
--engine		str		Filter: only propose rules for this engine (transformers/vllm/tensorrt).
--out		path		Output path for proposed YAML fragments (one YAML document per gap, separated by '---').
--include-exceptions		flag	false	Also propose rules from runtime exceptions. Disabled by default; when off, exception records are skipped and only warning and log emissions are proposed.
--verbose	-v	int	0	Increase verbosity (-v=INFO, -vv=DEBUG)

llem study

Write and prepare study files (llem run stays the executor).

llem study init

Write a study file for a model, ready to edit and run with llem run.

Without --defaults the tuning fields are present but commented out, each annotated with its type, range, and default - uncomment the ones you want. With --defaults those fields are filled in at their defaults, giving a reproducible baseline you can run as-is. With --bounds every field with a derivable value range becomes an explicit value list under sweep:, forming a maximal grid you prune down to the study you want.

Options:

Flag	Short	Type	Default	Description
--model	-m	str		Model id or HuggingFace path for the study.
--engine	-e	str		Engine to write (transformers, vllm, tensorrt). Omit to write all engines.
--output	-o	path		Where to write the study file (default: study.yaml). Will not overwrite.
--defaults		flag	false	Set every field to its default (a runnable baseline) instead of leaving them commented out.
--bounds		flag	false	Emit every field with a derivable value range as an explicit value list under sweep: - a maximal grid to prune before running.

llem study plan

Preview what llem run <study_file> would execute, without running it.

Prints a read-only funnel - declared grid points, then known-invalid points pruned by engine rules, then duplicate configs merged away, then experiments times cycles equals total runs - plus a wall-clock lower bound from the thermal gaps alone. No experiments run, nothing is written, the GPU is never touched. Exit 0 on a valid plan (even with skips); nonzero when the file is missing, unparseable, or produces no experiments.

Arguments:

Argument	Type	Required	Description
study_file	path	yes	Study YAML file to preview (as llem run would expand it).