Command line reference

Generated by scripts/gen_cli_doc.py from the Typer app in src/lasagna/cli.py. Do not edit by hand: run the script.

Every command is lasagna <command> [options]. lasagna <command> --help prints the same text in your terminal. Commands are grouped by what they work on:

Group	Commands	What it is for
Documents	export, import, init, search, status, upload	Put documents into a session and search them.
Benchmarks	benchmark experiment, benchmark info, benchmark licenses, benchmark list, benchmark run, benchmark synthesize, benchmark validate-data	Run benchmarks and sweeps, and read what they say about your change.
Results	results bundle, results compare, results interaction, results leaderboard, results per-query, results power, results schema, results significance, results validate, results view	Read, compare, test and publish what a run wrote.
Components	component list, component validate	List the components that fill each stage, and check one of yours.
Plugins	plugins list	See which installed packages add components or benchmarks.
Pipelines	pipelines list	See the agentic RAG pipelines you can select.
Skills	skills install, skills list	Install the agent skill that teaches a coding agent to use Lasagna.
Setup and serving	configure, doctor, serve	Set up, configure, diagnose and serve.

Options that apply before any command:

Option	Description
--verbose, -v	Show INFO and DEBUG logs (default: warnings only)
--version	Print the installed version and exit.
--install-completion, --show-completion	Install shell completion, or print it to copy.

Documents

Put documents into a session and search them.

lasagna export

$ lasagna export [OPTIONS]

Export current RAG configuration to JSON.

Options

Option	Type	Default	Description
--output, -o	str	rag-config.json	Output file
--session, -s	str	default	Session ID

lasagna import

$ lasagna import [OPTIONS] INPUT_FILE

Import RAG configuration from JSON.

Arguments

Argument	Required	Description
INPUT_FILE	yes	JSON config file to import

Options

Option	Type	Default	Description
--session, -s	str	default	Session ID

lasagna init

$ lasagna init

Interactive setup wizard for RAG knowledge base.

Asks for a vector backend and a quality profile, writes the backend to ./settings.lasagna.toml and applies the profile to the default session. The profile decides the embedding model. The LLM provider is not asked for: Lasagna picks it from the API key exported in the shell, so init names the provider that key selects, or which variable to export. API keys are not asked for or written anywhere.

lasagna search

$ lasagna search [OPTIONS] QUERY

Search the knowledge base.

Arguments

Argument	Required	Description
QUERY	yes	Search query

Options

Option	Type	Default	Description
--top-k, -k	int	5	Number of results
--session, -s	str	default	Session ID
--context, -c		off	Show formatted LLM context

lasagna status

$ lasagna status [OPTIONS]

Show knowledge base status.

Options

Option	Type	Default	Description
--session, -s	str	default	Session ID

lasagna upload

$ lasagna upload [OPTIONS] FILE_PATHS...

Upload and index documents.

Name several files, a folder, or a glob such as 'docs/*.md', in one command: they go through one client, so the models load once instead of once per file.

Arguments

Argument	Required	Description
FILE_PATHS...	yes	Files to upload: one or more paths, folders (their readable files, subfolders included), or glob patterns such as 'docs/*.md'

Options

Option	Type	Default	Description
--session, -s	str	default	Session ID
--force		off	Upload the file again even when the session already holds the same content.

Benchmarks

Run benchmarks and sweeps, and read what they say about your change.

lasagna benchmark experiment

$ lasagna benchmark experiment [OPTIONS] CONFIG_FILE

Run a multi-benchmark experiment from a config file.

Arguments

Argument	Required	Description
CONFIG_FILE	yes	YAML or TOML config file

Options

Option	Type	Default	Description
--resume		off	Resume from checkpoints
--concurrency, -c	int		Max parallel tasks
--no-cache		off	Call the LLM for every request instead of replaying responses cached by an earlier run (same as llm_cache: false)
--dry-run		off	Print the arms, tasks and models, and estimate tokens, time and cost from a 3-sample probe per benchmark, without running the sweep or writing results
--no-probe		off	With --dry-run, skip the probe, so nothing runs at all

lasagna benchmark info

$ lasagna benchmark info NAME

Show detailed information about a benchmark.

Arguments

Argument	Required	Description
NAME	yes	Benchmark name (e.g. beir/nfcorpus)

lasagna benchmark licenses

$ lasagna benchmark licenses [OPTIONS]

List every benchmark with its license and citation.

Generated from the benchmark adapters. Lasagna redistributes no benchmark data: each dataset is fetched from its own source under its own terms, and those terms are yours to honor.

Options

Option	Type	Default	Description
--output, -o	str		Write markdown to this path

lasagna benchmark list

$ lasagna benchmark list [OPTIONS]

List all available benchmarks.

Options

Option	Type	Default	Description
--category	str		Filter by category (single_hop, multi_hop, fact_verification, passage_ranking)

lasagna benchmark run

$ lasagna benchmark run [OPTIONS] NAME

Run one benchmark, or a data file of your own, and print its leaderboard.

Arguments

Argument	Required	Description
NAME	yes	A benchmark name, as lasagna benchmark list shows it, or your own data: a .jsonl or .csv file or a BEIR folder (docs/own-data.md).

Options

Option	Type	Default	Description
--samples, -n	int	100	Queries to evaluate, at most.
--runs, -r	int	1	Runs per arm. Repeat runs when an LLM stage is in the loop.
--mode	str	auto	auto, live (retrieve from the benchmark's corpus) or generation_only (answer from the gold passages).
--split	str	test	Dataset split.
--output, -o	str		Output directory (default: a new folder under ~/.lasagna).
--seed	int	42	Random seed for sampling queries.
--profile, -p	str	speed	Profile every arm starts from. speed needs no API key and downloads 92 MB; standard downloads 3.2 GB and sends complex queries to an LLM.
--tracks	str		retrieval, generation, or both, comma-separated. Default: retrieval, or both with --generator. Generation needs an LLM API key and the answer-scoring models, so it runs only when asked for.
--reranker	str		Run with this registered reranker.
--query-enhancer	str		Run with this registered query enhancer.
--generator	str		Write answers with this registered generator.

lasagna benchmark synthesize

$ lasagna benchmark synthesize [OPTIONS] CORPUS

Write a question set from your own documents with an LLM, for development.

Each question is checked by a second call, and rows that fail are dropped. The output runs with lasagna benchmark run <out>. Synthetic questions favor the phrasing of the model that wrote them: report results on human-written benchmarks (docs/own-data.md).

Arguments

Argument	Required	Description
CORPUS	yes	A folder of your documents (.md, .txt, .pdf, .docx, .html, ...), or one file

Options

Option	Type	Default	Description
--n	int	100	Number of questions to write
--out	str	synthetic_qa.jsonl	JSONL file to write
--mix	str	factoid=0.6,multihop=0.3,unanswerable=0.1	Share of each question type: factoid, multihop, unanswerable
--seed	int	42	Seed for choosing the source passages
--model	str		LLM that writes and checks the questions (default: MODEL_NAME)
--dry-run		off	Print the plan and a token estimate; call no LLM, write nothing
--overwrite		off	Replace --out if it exists

lasagna benchmark validate-data

$ lasagna benchmark validate-data PATH

Check your own benchmark data and say which tracks it supports.

Exits 0 when the data can be run, 1 with every problem listed when not. The formats are in docs/own-data.md.

Arguments

Argument	Required	Description
PATH	yes	A .jsonl or .csv file, or a BEIR folder (corpus.jsonl, queries.jsonl, qrels/test.tsv)

Results

Read, compare, test and publish what a run wrote.

lasagna results bundle

$ lasagna results bundle [OPTIONS] RESULTS_PATH

Package a run into a self-contained, publishable bundle.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a run

Options

Option	Type	Default	Description
--output, -o	str	run.json	Bundle path to write
--name	str		Submitter name
--affiliation	str		Submitter affiliation

lasagna results compare

$ lasagna results compare [OPTIONS] A B

Compare two runs, reporting whether they are comparable at all.

Each side is a run's results.json (or its folder) or a bundle. A bundle is checked first, as results validate checks it, and one that fails is refused. Per benchmark, configs are comparable when their comparability keys match: the keys results bundle prints and the leaderboard groups by.

Arguments

Argument	Required	Description
A	yes	First bundle or results.json
B	yes	Second bundle or results.json

Options

Option	Type	Default	Description
--metric, -m	str	ndcg@10	Metric to compare.

lasagna results interaction

$ lasagna results interaction [OPTIONS] RESULTS_PATH

Do two techniques compose, or do they overlap?

Estimates (AB - neither) - (A - neither) - (B - neither) from a 2x2 run. The p-value is a paired sign-flip permutation test on each query's interaction, and the confidence interval a t interval. A is reported against a baseline, B is reported against a baseline, and whether A+B is worth A alone cannot be recovered from the two, because the interaction is not a function of the main effects.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a factorial run

Options

Option	Type	Default	Description
--benchmark	str		Which benchmark (default: the only one)
--metric, -m	str	ndcg@10	Metric to test.
--neither	str	neither	Config with both techniques off
--only-a	str		Config with technique A only
--only-b	str		Config with technique B only
--both	str		Config with both on
--alpha	float	0.05	Significance level of the test.
--resamples	int	10000	Random sign patterns for the sign-flip permutation test when more than 30 queries differ; with 30 or fewer it is exact. The interval is a t interval.
--bootstrap	int		Old name of --resamples, removed in 0.2.0.

lasagna results leaderboard

$ lasagna results leaderboard [OPTIONS] DIRECTORY

Leaderboards of bundles or a run's results.json, by comparability key.

Rows inside a group held the same configuration fixed, so they are comparable by construction. Rows in different groups are not, and are never put in the same table. A results.json with no --output prints the run's own leaderboard, the one benchmark experiment prints when it finishes. Bundles are checked as results validate checks them: one that fails is refused when named on its own and left out of a folder, unless --allow-invalid shows it marked INVALID. A results.json is not validated.

Arguments

Argument	Required	Description
DIRECTORY	yes	A directory of validated bundles, one bundle, or a run's results.json (or its folder)

Options

Option	Type	Default	Description
--metric, -m	str	ndcg@10	Metric to rank by.
--output, -o	str		Folder to write one page per benchmark into (.md, or .tex with --format latex), plus index.json
--format	str	markdown	markdown, or latex: one booktabs table per comparability group, printed when no --output is given
--allow-invalid		off	Show bundles results validate rejects, each number marked INVALID

lasagna results per-query

$ lasagna results per-query [OPTIONS] RESULTS_PATH

One row per query, retrieval and generation metrics side by side.

Turns "config A lost" into "config A lost on the multi-hop questions, at retrieval rather than generation".

In the JSONL export, _retrieved lists each document's score and rank. The rank is authoritative: scores can tie, so sorting by score does not rebuild the ranking the metrics were computed on.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a run

Options

Option	Type	Default	Description
--output, -o	str		Write to .csv or .jsonl
--benchmark	str		Restrict to one benchmark
--config	str		Restrict to one config
--limit	int	20	Rows to print when not writing a file
--sort-by	str		Metric to sort ascending (worst first)

lasagna results power

$ lasagna results power [OPTIONS] RESULTS_PATH CONFIG_A CONFIG_B

Could this run have detected the effect you care about?

A non-significant result has two readings: the techniques are the same, or the run was too small to tell. They call for opposite next steps. Reports the smallest difference this run could have detected, and how many queries the observed difference would need.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a run
CONFIG_A	yes	Baseline config
CONFIG_B	yes	Candidate config

Options

Option	Type	Default	Description
--metric, -m	str	ndcg@10	Metric to test.
--benchmark	str		Which benchmark
--alpha	float	0.05	Significance level of the test.
--power	float	0.8	Chance of detecting the effect, for the smallest one reported.

lasagna results schema

$ lasagna results schema [OPTIONS]

Print the JSON Schema for a results bundle.

Generated from the same constants the bundler uses, so a hub validating against it can never require a different set of fields from the one this package writes.

Options

Option	Type	Default	Description
--output, -o	str		Write to a file

lasagna results significance

$ lasagna results significance [OPTIONS] RESULTS_PATH

Test every pair of configs at once, correcting for having asked N times.

Running results compare across a grid one pair at a time is the standard way to manufacture a false positive: at alpha=0.05, six configs make fifteen comparisons and roughly a 54% chance that at least one clears the bar by luck alone. Holm-Bonferroni controls the family-wise error rate over the whole set, so what comes out is a claim about the grid rather than about the pair that happened to look best. Each pair is a paired sign-flip test.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a run

Options

Option	Type	Default	Description
--metric, -m	str	ndcg@10	Metric to test.
--benchmark	str		Which benchmark
--correction	str	holm	'holm' (Holm-Bonferroni) or 'none'
--alpha	float	0.05	Family-wise significance level
--all		off	Include pairs that did not reach significance

lasagna results validate

$ lasagna results validate [OPTIONS] BUNDLE_PATH

Check a bundle is well-formed, complete, and internally consistent.

Recomputes the comparability key, the run id and every aggregate from the recorded fields, so a number edited after the run no longer matches its bundle. It detects mistakes and accidental edits, not tampering: the run id is a content hash, not a signature, and anyone who edits a number can recompute it.

Arguments

Argument	Required	Description
BUNDLE_PATH	yes	run.json bundle to check

Options

Option	Type	Default	Description
--strict		off	Treat integrity warnings as failures

lasagna results view

$ lasagna results view [OPTIONS] RESULTS_PATH

Write one HTML page with everything a run measured.

The header names the experiment, its date and versions; then the stage isolation check, and per benchmark the leaderboard, the Holm-corrected significance table with its verdict, every metric per arm, and a per-query diff between two arms with what each retrieved. The page is one file with no external requests, so it opens offline and can be attached anywhere. A bundle is checked as results validate checks it, and one that fails is refused unless --allow-invalid; a results.json is not validated.

Arguments

Argument	Required	Description
RESULTS_PATH	yes	results.json from a run (or its folder), or a bundle from results bundle

Options

Option	Type	Default	Description
--metric, -m	str		Metric to rank, test and compare queries by (default: ndcg@10 when recorded)
--benchmark	str		Show one benchmark only
--diff			The two arms the per-query table compares (default: the top two)
--output, -o	str	view.html	HTML file to write
--open		off	Open the page in your browser
--allow-invalid		off	Show a bundle results validate rejects, the page marked INVALID

Components

List the components that fill each stage, and check one of yours.

lasagna component list

$ lasagna component list [STAGE]

List the components a sweep can name, by stage.

Built-in components and those of installed plugins, with the paper each one implements, or the docs page of a method that has none. A component of your own module is named as module:function and does not appear here.

Arguments

Argument	Required	Description
STAGE	no	Show one stage only: agentic_pipeline, chunker, document_processor, embedder, generator, query_enhancer, reranker or retriever.

lasagna component validate

$ lasagna component validate [OPTIONS] TARGET

Check a component satisfies its stage contract.

Checks what makes a component safe to swap: it returns the declared type, survives empty input, and does not change what it was handed. The last is what makes a comparison attributable: a component that edits its input changes the results of whatever runs after it.

The target is resolved from the working directory, as a sweep resolves it, so the function you name in a sweep is the one checked here. A function decorated with @lasagna.reranker (or another stage decorator) is checked as the component the sweep would run.

Arguments

Argument	Required	Description
TARGET	yes	What a sweep would name: a registered component (cross_encoder), my_ideas:keyword_overlap (a decorated function), my_pkg.rerankers:MyReranker (a class) or path/to/file.py:name

Options

Option	Type	Default	Description
--stage	str		The stage a plain, undecorated function implements: reranker, query_enhancer, chunker, embedder, retriever, document_processor, generator
--profile, -p	str	speed	Profile whose model a registered component is built with (default speed: the 92 MB cross-encoder, not the settings file's 881 MB one)

Plugins

See which installed packages add components or benchmarks.

lasagna plugins list

$ lasagna plugins list

Show discovered plugins, including the ones that failed to load.

One broken plugin does not stop the others loading, so a plugin that fails is simply absent from the registry. This lists it with its error. Set LASAGNA_STRICT_PLUGINS=1 to make a failure raise instead.

Pipelines

See the agentic RAG pipelines you can select.

lasagna pipelines list

$ lasagna pipelines list [OPTIONS]

List all registered agentic pipelines.

Shows name, description, implementing class, and which pipeline the session runs when a query reaches the agentic tier (from its profile). Use it to check that a pipeline you registered with @registry.register("agentic_pipeline", ...) is there.

Options

Option	Type	Default	Description
--session, -s	str	default	Session whose pipeline to mark as the one that runs.

Skills

Install the agent skill that teaches a coding agent to use Lasagna.

lasagna skills install

$ lasagna skills install [OPTIONS]

Copy the bundled skills where a coding agent will find them.

Skills teach an agent how to use Lasagna: which mode to run a benchmark in, why the first search is slow, how to file a useful bug report.

Options

Option	Type	Default	Description
--target, -t	str	.claude/skills	Where to write them (Claude Code/Desktop use .claude/skills)
--force		off	Overwrite existing files

lasagna skills list

$ lasagna skills list

Show the agent skills this package ships.

Setup and serving

Set up, configure, diagnose and serve.

lasagna configure

$ lasagna configure [OPTIONS]

Configure RAG settings.

With --profile, applies a preset; with --reset, drops the session's own settings. Without arguments, lists available profiles.

Options

Option	Type	Default	Description
--profile, -p	str		Apply a profile: speed, standard, balanced, max_quality, or default (the settings file)
--session, -s	str	default	Session ID
--force		off	Apply even if the session's stored documents would no longer be searched (they stay where they are until reindexed); the new models must load
--reindex		off	Reindex the session's documents with the new profile, then apply it; if one fails, the session keeps its profile and every document stays searchable
--resume-switch		off	Finish a profile switch with --reindex whose process stopped before it ended (doctor reports one): runs the same switch again
--reset		off	Drop the session's own settings (set by an SDK client, a patch or an import), so its profile's apply as they are; with --profile, switch as well. The same documents check, --force and --reindex apply

lasagna doctor

$ lasagna doctor [OPTIONS]

Check this installation and say what to fix.

Answers the questions every support thread opens with: version, install source, backend, credentials, model cache, and anything that failed to load quietly.

Output is redacted: no absolute paths, no credential values. --json is for agents; --issue produces a collapsible block for a GitHub issue.

Options

Option	Type	Default	Description
--json		off	Machine-readable output
--issue		off	Print a block to paste into a bug report
--session, -s	str	default	Session whose profile to report.

lasagna serve

$ lasagna serve [OPTIONS]

Start the REST API server, with the configurator web page.

While it runs it holds the local store; lasagna status, search, upload and configure go through it, and benchmark run and benchmark experiment use a store of their own.

Options

Option	Type	Default	Description
--port	int	8000	Port to listen on.
--host	str	127.0.0.1	Bind address. Default is loopback; --host 0.0.0.0 exposes the API on every interface, and it is UNAUTHENTICATED (see https://github.com/dolev31/lasagna/blob/main/SECURITY.md).
--configurator / --no-configurator		on	Serve the configurator web page at /configurator.
--open / --no-open		off	Open the configurator in a browser once the server starts.
--mcp		off	Also serve the MCP server (SSE) at /mcp/sse, from this process. Milvus Lite admits one process per store, so this is how an agent and the REST API share one.
--session, -s	str		The session for MCP tool calls and REST requests that name none (default: RAG_SESSION_ID, else 'default').