CLI reference #

litmus is a Click application; every command, group, option, and argument below is enumerated from litmus.cli:main. To regenerate after touching any command:

uv run python scripts/generate_reference_docs.py cli

The pre-commit hook runs the same generator in --check mode, so source / docs drift fails the commit.

Installation #

uv pip install litmus-test       # PyPI name is litmus-test; the import is `litmus`
litmus --help

After install, litmus is on $PATH. The litmus entry point is registered by pyproject.toml (litmus = "litmus.cli:main").

Commands #

litmus catalog (group) {#cli-catalog} #

Catalog commands.

litmus catalog datasheet {#cli-catalog-datasheet} #

Generate a formatted datasheet from a catalog YAML file.

litmus daemon (group) {#cli-daemon} #

Manage Litmus background daemons (events / runs / channels).

litmus daemon restart {#cli-daemon-restart} #

Restart selected daemons (SIGTERM the running process; respawn on next access).

litmus daemon status {#cli-daemon-status} #

Show running daemons, their PIDs, refs, and locations.

(no options or arguments.)

litmus daemon stop {#cli-daemon-stop} #

Stop selected daemons without respawning.

litmus data (group) {#cli-data} #

Data retention and management.

litmus data promote {#cli-data-promote} #

Move a starter project's local runs to the global store.

litmus data prune {#cli-data-prune} #

Delete date-partitioned data older than the specified period.

litmus data reindex {#cli-data-reindex} #

Kill index daemons and rebuild on next access.

litmus discover {#cli-discover} #

Scan for available instruments.

litmus export {#cli-export} #

Export a test run or session to a different format via event replay.

litmus grafana (group) {#cli-grafana} #

Grafana dashboard provisioning and data server.

litmus grafana export {#cli-grafana-export} #

Export dashboards and provisioning templates for manual setup.

litmus grafana serve {#cli-grafana-serve} #

Start the pgwire server for Grafana.

litmus grafana setup {#cli-grafana-setup} #

Install provisioning config and dashboards into Grafana.

litmus init {#cli-init} #

Initialize a new Litmus project.

litmus instrument (group) {#cli-instrument} #

Instrument management commands.

litmus instrument cal {#cli-instrument-cal} #

Update calibration information for an instrument.

litmus instrument list {#cli-instrument-list} #

List all instrument configuration files.

litmus instrument show {#cli-instrument-show} #

Show details for a specific instrument.

litmus mcp (group) {#cli-mcp} #

MCP server commands for AI-assisted workflows.

litmus mcp serve {#cli-mcp-serve} #

Start the MCP server for AI agents.

litmus metrics (group) {#cli-metrics} #

Manufacturing-test analytics (yield, pareto, cpk, trend, retest, time-loss).

litmus metrics cpk {#cli-metrics-cpk} #

Process capability (Cpk/Cp) per measurement.

litmus metrics pareto {#cli-metrics-pareto} #

Top failures (Pareto). Group by product / step / measurement.

litmus metrics retest {#cli-metrics-retest} #

Retest rates: how often DUTs are retried.

litmus metrics summary {#cli-metrics-summary} #

Yield summary: FPY, final yield, run counts, duration stats.

litmus metrics time-loss {#cli-metrics-time-loss} #

Time lost to failures and errors.

litmus metrics trend {#cli-metrics-trend} #

Yield trend over time.

litmus new-test {#cli-new-test} #

Scaffold a new test file.

litmus refs (group) {#cli-refs} #

Stream curated reference docs to stdout.

litmus refs list {#cli-refs-list} #

List available reference topics.

(no options or arguments.)

litmus refs show {#cli-refs-show} #

Print the named reference doc to stdout.

litmus runs {#cli-runs} #

List recent test runs.

litmus sbom {#cli-sbom} #

Export CycloneDX SBOM for a test run's software environment.

litmus schema (group) {#cli-schema} #

JSON Schema generation for YAML validation.

litmus schema export {#cli-schema-export} #

Export JSON Schema files for all Litmus YAML types.

litmus schema refresh {#cli-schema-refresh} #

Refresh .vscode/schemas/ and .vscode/settings.json after a Litmus upgrade.

litmus serve {#cli-serve} #

Start the operator UI server.

litmus setup (group) {#cli-setup} #

Configure AI tool integrations.

litmus setup claude-code {#cli-setup-claude-code} #

Configure Litmus MCP server for Claude Code.

litmus setup claude-desktop {#cli-setup-claude-desktop} #

Configure Litmus for Claude Desktop.

litmus setup cline {#cli-setup-cline} #

Configure Litmus MCP server for Cline (VS Code extension).

litmus setup copilot {#cli-setup-copilot} #

Configure Litmus for GitHub Copilot (VS Code + CLI).

litmus setup cursor {#cli-setup-cursor} #

Configure Litmus MCP server for Cursor.

litmus setup show {#cli-setup-show} #

Show current MCP server configuration.

(no options or arguments.)

litmus show {#cli-show} #

Show details for a specific test run.

litmus station (group) {#cli-station} #

Station management commands.

litmus station init {#cli-station-init} #

Initialize a new station configuration.

litmus station update {#cli-station-update} #

Re-discover and update instrument identity in configuration.

litmus station validate {#cli-station-validate} #

Validate station instruments against configuration.

litmus validate {#cli-validate} #

Validate YAML configuration files.

Test phase #

test_phase tags every run with the maturity tier it was produced for (development, validation, characterization, production). It lands on every parquet row so dashboards and queries can filter by phase.

Setting the phase #

Resolution order (first match wins):

1. pytest --test-phase=<phase> — explicit per-run.
2. LITMUS_TEST_PHASE env var.
3. Profile YAML — a profile can set test_phase: <phase> for every test it runs.
4. Auto-detect — production if the git tree is clean, development if dirty.

Git-status enforcement #

Non-development phases require a clean git repository. Uncommitted changes (or no git at all) force the phase down to development regardless of what was requested. This guarantees a production-tagged row is reproducible from a commit hash.

Query by phase #

import duckdb
 
duckdb.sql("""
    SELECT * FROM read_parquet('data/runs/**/*.parquet')
    WHERE test_phase = 'production'
""")
 
# Exclude dev work
duckdb.sql("""
    SELECT * FROM read_parquet('data/runs/**/*.parquet')
    WHERE test_phase != 'development'
""")

See Profiles for the profile YAML shape.

Environment variables #

Exit codes #

See also #

• Platform architecture — what each entry point owns
• MCP tools — the agent-side parallel to most litmus subcommands
• Configuration — YAML files the CLI reads
• API reference — HTTP routes the litmus serve UI mounts