This page is the full CLI reference. For setup and the shortest common paths, start with Getting started and Common tasks. For the operating loop and machine-readable routes, use Preflight, run, verify and Automation and JSON.
A typical order is:
uv run reader lsto find experiments.uv run reader protocolsoruv run reader initto choose a protocol and scaffold a new experiment.uv run reader inspectto see one experiment’s config, inputs, pipeline chain, plots, exports, and current outputs.uv run reader stepsoruv run reader explainto inspect the compiled plan.uv run reader validateto run preflight checks.uv run reader run,uv run reader plot,uv run reader export, anduv run reader notebookto materialize outputs.
uv run reader commands accept a config path, experiment directory, or an index from uv run reader ls (shown below as CONFIG|DIR|INDEX).
uv run reader <command> CONFIG|DIR|INDEX [options]If CONFIG|DIR|INDEX is omitted, uv run reader searches upward from the current working directory for
config.yaml. If a numeric index is provided, it is resolved against the nearest experiments/
directory (or ./experiments if none is found) using the same default experiment inventory as
uv run reader ls; indices shown by uv run reader ls --all are accepted too.
List experiments:
uv run reader ls --root experimentsShow protocol ids, selected-plan summaries, and current output counts:
uv run reader ls --root experiments --detailsAdd readiness state so the inventory tells you whether each experiment is draft/template, blocked, ready to run, or already has a record catalog:
uv run reader ls --root experiments --details --readinessEmit the same inventory as JSON for agents or automation:
uv run reader ls --root experiments --details --format json
uv run reader ls --root experiments --details --readiness --format jsonThe JSON payload uses explicit catalog, selection, summary, and
experiments blocks so agents do not need to reconstruct fleet state by
walking every row or guessing which filters produced the current view.
When --readiness is enabled, selection.readiness is true, each experiment
entry gains a readiness block, and summary.by_readiness counts the fleet by
config_error, draft, template, dependency_blocked, blocked, runnable,
legacy_outputs_present, or records_ready.
Filter the inventory down to one assay family, one lifecycle, or just broken configs:
uv run reader ls --root experiments --details --protocol plate_reader/dual_reporter_screen
uv run reader ls --root experiments --details --protocol plate_reader/single_reporter_screen
uv run reader ls --root experiments --details --protocol plate_reader/retron_sponge_screen
uv run reader ls --root experiments --details --lifecycle draft
uv run reader ls --root experiments --details --status config_errorInclude scaffold/template directories too:
uv run reader ls --root experiments --allIf --root is omitted, uv run reader auto-detects the nearest experiments/ directory.
Inspect plugins, protocols, and notebook templates:
uv run reader plugins
uv run reader plugins --category plot
uv run reader plugins --protocol plate_reader/dual_reporter_screen --category transform
uv run reader plugins --protocol plate_reader/single_reporter_screen --category plot
uv run reader plugins --protocol plate_reader/retron_sponge_screen --category transform
uv run reader protocols
uv run reader protocols plate_reader/dual_reporter_screen
uv run reader protocols plate_reader/single_reporter_screen
uv run reader protocols plate_reader/retron_sponge_screen
uv run reader protocols <protocol-id> --example-config
uv run reader protocols --family screen_analysis
uv run reader protocols --family matched_control_screen
uv run reader notebook --list-templatesScaffold a new experiment from a protocol:
uv run reader init ./experiments/20260317_new_assay --protocol <protocol-id>Use plate_reader/dual_reporter_screen for CFP/YFP-style dual-reporter panels. Use plate_reader/single_reporter_screen for RFP-or-other single-reporter panels normalized to a configured denominator. Use plate_reader/retron_sponge_screen when the assay contract depends on matched same-sensor tetO controls plus compiled burden, leakiness, induced-effect, and cross-sensor ranking nodes.
For the matched-control sponge workflow itself, use the Retron sponge screen guide. That guide maps the direct-ratio analysis sequence, the compiled semantic tables, and the retron-specific plot/export surface.
Inspect one experiment end to end:
uv run reader inspect CONFIG|DIR|INDEXEmit the experiment as layered JSON with authoring, semantics, and
implementation:
uv run reader inspect CONFIG|DIR|INDEX --format jsonList just the pipeline chain and bindings:
uv run reader steps CONFIG|DIR|INDEX
uv run reader steps CONFIG|DIR|INDEX --format jsonGuided walkthrough:
uv run reader demoProtocol descriptions are the main discovery surface for assay-specific inputs and outputs. For the compact route, use Common tasks. For machine-readable contracts, use Automation and JSON.
In short:
uv run reader protocols <id>shows the protocol authoring surface, selected outputs, and compiled defaults.uv run reader protocols <id> --example-configprints a starterreader/v7outline.uv run reader inspect,config,steps, andexplainshow one bound experiment; JSON mode uses sharedauthoring,semantics, andimplementationsections.uv run reader ls --details --readinessis the fleet-level inventory and preflight view.uv run reader plot --list,uv run reader export --list, anduv run reader recordsshow selected outputs and generated records.uv run reader plugins --protocol <id> --category ...scopes registry inspection to the plugins a protocol uses by default.
Inspect the experiment summary before reading the lower-level plan:
uv run reader inspect CONFIG|DIR|INDEXThe default table view now includes a readiness panel so you can see, in one place, whether the config is blocked by files or dependencies, already has records, and which next command is appropriate.
Print the compiled config/IR:
uv run reader config CONFIG|DIR|INDEXPrint the config as JSON:
uv run reader config CONFIG|DIR|INDEX --format jsonIn JSON mode, authoring is the full reader/v7 document, while
implementation carries the compiled plan.
Validate schema, wiring, and inputs:
uv run reader validate CONFIG|DIR|INDEX
uv run reader validate CONFIG|DIR|INDEX --format jsonIn JSON mode, uv run reader validate keeps the preflight mode in selection,
then separates overall status/counts into summary from file-check details in
validation. uv run reader validate --no-files --format json still reports
declared file and auto-root counts even when the checks are skipped.
If you want the same preflight signal while browsing the whole workbench, use
uv run reader ls --details --readiness. If you want the readiness view beside
one experiment’s compiled plan and current outputs, use uv run reader inspect.
For the full operating loop, use Preflight, run, verify.
Skip file checks (config-only):
uv run reader validate CONFIG|DIR|INDEX --no-files
uv run reader validate CONFIG|DIR|INDEX --no-files --format jsonInspect the resolved plan without execution:
uv run reader explain CONFIG|DIR|INDEX
uv run reader explain CONFIG|DIR|INDEX --format jsonRun the pipeline section only (produces dataframe records + outputs/manifests/records.json):
uv run reader run CONFIG|DIR|INDEX
uv run reader run CONFIG|DIR|INDEX --dry-run --format jsonSlice the pipeline:
uv run reader run CONFIG|DIR|INDEX --from step_a --until step_c
uv run reader run CONFIG|DIR|INDEX --only step_b
uv run reader run CONFIG|DIR|INDEX --from step_a --until step_c --dry-run --format jsonuv run reader run fails fast if --from comes after --until in pipeline order.
Inspect the emitted record catalog:
uv run reader records CONFIG|DIR|INDEX
uv run reader records CONFIG|DIR|INDEX --format json
uv run reader records CONFIG|DIR|INDEX --all --format jsonIn JSON mode, uv run reader records keeps experiment identity at the top level, then
adds the record-manifest path, a summary by record kind and producer, and the
latest record entries. --all does not dump every historical revision; it adds
per-record revision counts and a total revision summary so the surface stays
compact.
Useful flags:
--from <step_id>/--until <step_id>(pipeline only)--only <step_id>(single pipeline step)--dry-run--log-level <level>--compact(use the compact progress view instead of per-step logs)
Run plot specs only (saves files to outputs/plots):
uv run reader plot CONFIG|DIR|INDEXRun plots for all experiments in a year (expects experiments/YYYY):
uv run reader plot --year 2025Override the experiments root when using --year:
uv run reader plot --year 2025 --root /path/to/experimentsList resolved semantic plot outputs and their upstream dataframe bindings:
uv run reader plot CONFIG|DIR|INDEX --list
uv run reader plot CONFIG|DIR|INDEX --list --format jsonIn JSON mode, uv run reader plot --list keeps the bound experiment at the top level,
then adds catalog, selection, and summary blocks before the resolved
plots entries.
Dry-run a plot plan without executing:
uv run reader plot CONFIG|DIR|INDEX --dry-runFilter plots:
uv run reader plot CONFIG|DIR|INDEX --only raw_kinetics --only ratio_heatmap
uv run reader plot CONFIG|DIR|INDEX --exclude value_distributionsAd-hoc overrides (plot/export only):
uv run reader plot CONFIG|DIR|INDEX --only raw_kinetics --input 'df={record: ratio_yfp_od600/df}'
uv run reader plot CONFIG|DIR|INDEX --only endpoint_by_condition --set with.time=6.0--input expects a structured YAML/JSON binding such as {record: ...},
{file: ...}, or {resource: ...}.
--set paths must start with reads., with., or writes..
Run export specs only:
uv run reader export CONFIG|DIR|INDEXList resolved semantic export artifacts and their upstream dataframe bindings:
uv run reader export CONFIG|DIR|INDEX --list
uv run reader export CONFIG|DIR|INDEX --list --format jsonIn JSON mode, uv run reader export --list mirrors the same shape as plot listings:
experiment identity, then catalog, selection, summary, and resolved
exports entries.
Dry-run an export plan without executing:
uv run reader export CONFIG|DIR|INDEX --dry-runFilter exports:
uv run reader export CONFIG|DIR|INDEX --only crosstalk_pairs_table
uv run reader export CONFIG|DIR|INDEX --exclude logic_summary_workbookAd-hoc overrides:
uv run reader export CONFIG|DIR|INDEX --only crosstalk_pairs_table --set with.path="exports/crosstalk_pairs.csv"Scaffold a marimo notebook (no pipeline execution). If --template is omitted, the CLI
uses the first configured notebooks.specs entry, otherwise auto-picks a default
template from declared template capabilities:
- plot-capable template when plots exist
- cytometry EDA template when the pipeline is cytometry-shaped
- fallback basic template otherwise
Notebooks are written under outputs/notebooks/.
uv run reader notebook CONFIG|DIR|INDEXChoose a template explicitly:
uv run reader notebook CONFIG|DIR|INDEX --template notebook/edaAllow explicit record scanning when the canonical catalog is missing:
uv run reader notebook CONFIG|DIR|INDEX --scan-recordsName the notebook explicitly:
uv run reader notebook CONFIG|DIR|INDEX --name EDA_custom.pyLaunch modes:
--mode edit(default): open Marimo editor--mode run: run as a read-only app--mode none: create only (no launch)--headless: keep the server in the terminal and print a loopback URL for browser automation--port <n>: request a specific loopback port instead of the reader-managed clean-port selection
Runtime notes:
reader notebookmanages Marimo runtime state under.cache/marimo/.- It reuses a live reader-managed session for the same notebook only when the notebook file and reader runtime fingerprint still match.
- If the notebook or runtime has drifted, it restarts the stale session instead of silently reusing it.
- It prunes older reader-managed sessions for the same experiment and launch mode before starting a new one.
- For agent review, prefer
--mode run --headless, then open the printed URL in Chrome MCP.
See templates:
uv run reader notebook --list-templatesOverwrite an existing notebook:
uv run reader notebook CONFIG|DIR|INDEX --template notebook/basic --forceCreate a new notebook with a numeric suffix if the name already exists:
uv run reader notebook CONFIG|DIR|INDEX --newRegenerate a notebook in-place:
uv run reader notebook CONFIG|DIR|INDEX --refreshFilter plots injected into a template that declares plot-filter capability
(currently notebook/eda):
uv run reader notebook CONFIG|DIR|INDEX --template notebook/eda --only raw_kinetics
uv run reader notebook CONFIG|DIR|INDEX --template notebook/eda --exclude value_distributionsList pipeline steps (resolved):
uv run reader steps CONFIG|DIR|INDEXList workbench records from outputs/manifests/records.json:
uv run reader records CONFIG|DIR|INDEXShow record history counts:
uv run reader records CONFIG|DIR|INDEX --allList step ids and plugins:
uv run reader steps CONFIG|DIR|INDEX
uv run reader plugins