Command-Line Interface

Prerequisites

Use Python 3.10–3.13, the matching wheel and example bundle, the declared model extras, and Git for committed projects and guarded holdout history. Run the worked commands from the bundle root.

First YAML Run

1bundle=$(pwd)2limen --version3limen list-templates4mkdir -p results/compiled-project5cp compiled-research/limen.toml results/compiled-project/limen.toml6cp compiled-research/project.yaml results/compiled-project/research.yaml7cp -R "$bundle/inputs" results/compiled-project/inputs8printf 'inputs/\nresults/dev/\n' > results/compiled-project/.gitignore9git init --quiet --bare results/compiled-backup.git10git init --quiet results/compiled-project11cd results/compiled-project12git config user.name "Limen documentation"13git config user.email "docs@example.invalid"14git config commit.gpgsign false15limen init scaffold.yaml --template logreg_binary16limen validate research.yaml17limen profile research.yaml18limen run --dry-run research.yaml19limen commit research.yaml --message "docs: record the research definition"20limen ls21for definition in manifests/committed/*.yaml; do22  identity=$(basename "$definition" .yaml)23done24limen lineage "$identity"25limen fork "$identity" recorded-child26cp "$bundle/compiled-research/project_child.yaml" manifests/recorded-child-production.yaml27limen commit manifests/recorded-child-production.yaml --parent "sha256:$identity" --message "docs: record the child definition"28limen reindex29limen run --no-progress-bar "manifest://sha256:$identity"30limen backup31cd "$bundle"32limen new results/compiled-restored --from "$bundle/results/compiled-backup.git"

The project script preserves its source YAML and uses a local Git remote. Runtime outputs and guarded holdout history have their own preservation requirements; Git backup follows the project's ignore rules. The template scaffold is separate from the recorded experiment.

A multi-file run stops after a signalled interruption and retains the current experiment's checkpoint; later YAML files are not launched.

Fresh runs check for existing run artifacts before copying their YAML declaration. Use --resume when the saved recording policy permits recovery, or choose a new output path. A directory containing only an old YAML copy still accepts a fresh run; an existing file at the declaration's copy destination is replaced.

Sensor and Cohort assessment

limen assess YAML --results DIRECTORY requires the exact declaration retained in that directory. A guarded assessment also requires the supplied reservation to contain the YAML-declared final window. Its assessment block names an explicit validation metric, direction and member count. Optional fold numbers select qualified recorded folds. The command reconstructs and validates each selected Sensor, binds the Cohort and writes assessment.json. predict: true additionally writes predictions.parquet with decision timestamps, unavailable reasons and optional native availability values.

1limen assess compiled-research/research.yaml --results results/dev/compiled-research

Guarded final assessment

limen reserve YAML reserves the YAML's final interval in its Git project before research. It prints the reservation identity to standard output; validation messages use standard error. limen assess YAML --results DIRECTORY --reservation ID freezes the selected Cohort and writes the native guarded final-report.json. Ordinary prediction is unavailable for a declaration with a guarded final assessment.

1git init --quiet compiled-research/final2reservation=$(limen reserve compiled-research/final/holdout.yaml)3limen run --no-progress-bar compiled-research/final/holdout.yaml4limen assess compiled-research/final/holdout.yaml --results results/dev/compiled-holdout --reservation "$reservation"

The event-contract variant declares one selected Sensor and holdout.scenarios: []. The CLI freezes its recorded event policy and round identity, then writes the schema-2 execution report.

Commands

Command Details

limen validate <yaml_file>

Runs YAML parsing plus structural validation. It checks required top-level blocks, schema version, metadata.mode and optional metadata shapes, manifest type, supported output formats, search strategy values, split_dates, parameter lists, and resolvability of limen.* dotted references.

Exit behavior:

• 0 when validation succeeds
• 1 when parsing or validation fails

limen profile <yaml_file>

Validates and compiles the YAML, then reports parameter-space size and complexity. It loads the effective compiled sfd.manifest.data_source and attempts real preparation/model evaluation for a covering array. For a nonempty domain, the attempt count is the largest parameter-list length, independently of uel.n_permutations. Completed-sample timings cover preparation/evaluation and exclude source loading, although profiling may fetch remote data and fit models.

Sampling follows the configured split windows and holdout admission/cutoffs. split_dates supplies fetch limits only where the loader accepts them; file sources may load the whole file, and supported source parameter overrides remain effective. This does not add walk-forward profiling support. No experiment results CSV is written, but holdout research/exposure/failure history may be written. Strict mode is temporarily disabled during sampling and restored afterwards.

Collected ordinary load/sample errors are reported and can exit 0, including with zero completed samples. Validation, compilation, protection and unexpected errors exit 1. YAML still rejects test_data_source; the native Manifest.set_test_data_source API remains available. For data-quality errors, check source coverage, configured split windows and target/preparation settings; row-limit parameters are not universal and can conflict with dated sources.

limen run <yaml_file> [<yaml_file> ...]

Execute one or more YAML declarations sequentially. A failure stops before the next file. Resume accepts one results directory and cannot be combined with YAML targets. Each declaration follows the same execution path:

1. parse the YAML file
2. validate structure and references
3. compile YAML into a manifest-backed SFD
4. build the configured search strategy
5. run UEL
6. write result artifacts

Options:

The normal result directory contains:

limen commit <yaml_file>

Commits a manifest into a project-local content-addressed store. The YAML file must be inside a Limen project root containing limen.toml, and metadata.mode must be production. The command validates the YAML, writes manifests/committed/<hex>.yaml where <hex> is the manifest id without the sha256: prefix, updates manifests/committed/index.json, and then attempts a git commit in the project.

Failure boundaries:

• --parent must be sha256:<64-hex-chars>.
• validation or non-production mode stops before store mutation.
• an existing manifest repairs the store index when needed and may create a repair commit.
• git failure after store write is reported as a warning; the command still returns success because the manifest is stored but not version-controlled.

Options:

limen init <output> [--template <name>]

Copies a bundled YAML template to output and updates metadata.name to the output filename stem. The .yaml extension is optional, and a bare name is resolved into the project's manifests/ directory when run inside a Limen project (a warning is printed otherwise). Without --template, the command lists templates and prompts for one, defaulting to logreg_binary.

limen list-templates

Lists package-data templates under limen/yaml/templates. Use the command's output for the current template inventory; Built-In SFDs describes their model families. tabpfn_binary is listed without importing TabPFN but requires the optional tabpfn extra before execution.

limen ls

Reads manifests/committed/index.json from the current project and prints committed manifest metadata. Run it from inside a Limen project directory.

limen new <project_name>

Creates a new project from the official project template. New projects are initialized on the main branch so they line up with an empty backup remote (which GitHub also defaults to main).

Options:

limen fork <manifest_id> [name]

Copies a committed manifest into manifests/ as a development-mode working file and records the source as lineage.parent_id. When name is omitted, it prompts with an auto-incremented default (e.g. <parent>_v2). On the next limen commit, the parent lineage is preserved automatically.

Before creating the working copy, forking verifies the document actually copied: its canonical content and stored lineage.id must match the full source filename ID. This also applies to Python fork_manifest callers and changes made while the CLI name prompt is open. An integrity failure leaves the destination absent. Formatting and excluded lineage metadata may differ without changing identity; the child's lineage contains only its verified immediate parent_id. This is a content-integrity check, not proof of historical authenticity.

limen lineage <manifest_id>

Walks the parent_id chain from a committed manifest to its root and prints it root-first, with the target manifest marked.

limen reindex

Rebuilds manifests/committed/index.json from the committed manifest files (the source of truth). Use it to repair the index after a bad merge or a pull that left the index out of sync. Only the index is rewritten; committed manifests are never modified.

limen backup

Snapshots the project — stages and commits the current state, honoring .gitignore so development runs under results/dev/ stay local — then pushes to backup_remote from limen.toml. It never force-pushes: on a rejected push it explains the remote has diverged and points to the raw git push command. Restore on another machine with limen new <name> --from <remote_url>.

YAML Run Contract

limen run accepts either a YAML file path or a committed manifest reference — a bare sha256:<hash> (the form limen commit prints) or a full manifest://sha256:<hash> URI. The command resolves the manifest, validates it, compiles all limen.* references, builds the parameter search domain, and then runs UEL.

Committed manifest URIs may use a full manifest://sha256:<64-hex> ID or an unambiguous short prefix. Resolution happens against the current project-local manifest store. A short prefix is expanded to the stored full manifest file name before execution; the result path uses the first eight hex characters, the copied YAML is named manifest.yaml, and metadata.json records the full canonical manifest_id. Use the full URI in external provenance records.

metadata.mode controls the default result path:

Set uel.output_format: parquet to also write results.parquet after successful execution. A successful --resume uses this setting from the saved YAML and writes or refreshes the file in the supplied results directory, including when no new rounds run. Rejected or interrupted resumes leave any existing Parquet file unchanged.

Set uel.output_path to a relative template within the direct run's mode directory; see the output destination contract for containment, relocation and resume behavior. Committed manifest URI runs ignore it and use the hash/timestamp path under the project results directory.

Validation Boundaries

limen validate and the validation step inside limen run check structure and resolvability before execution. They do not prove that custom callables have predictive value, that a remote data source is available at run time, or that a production run is valid for downstream promotion.

Runtime boundaries:

• limen run --resume requires full recording evidence enabled on the initial run, an existing results directory with metadata.json containing yaml_reference, a readable checkpoint, consistent round_data.jsonl.gz through the checkpoint round, and results.csv.
• limen run --dry-run does not test data-source availability beyond compilation needs.
• CLI commands report process success through exit codes; they do not write an external audit record unless the command itself creates project artifacts.
• limen commit mutates git state in the target project; use it only when the manifest store commit is intended.

Read Next

• Experiment Manifest
• Universal Experiment Loop
• Trainer
• Developer Guidelines

Complete argument and option index

These tables come from the current Click declarations. Required values and positional arguments have no declared default. Omitted optional flags use the listed value; automatic help and version options are included. Path constraints are checked before command execution. The command descriptions above explain state changes and exit conditions.

limen options

limen assess options

limen backup options

limen commit options

limen fork options

limen init options

limen lineage options

limen list-templates options

limen ls options

limen new options

limen profile options

limen reindex options

limen reserve options

limen run options

limen validate options