CLI reference #

The full command list below is generated from litmus itself.

Installation #

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

After install, litmus is on $PATH.

Commands #

litmus benchmark {#cli-benchmark} #

Measure this machine's per-store performance.

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 import {#cli-data-import} #

Merge another data_dir into this one; the store daemons rebuild from the files.

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

Move a starter project's local runs + their referenced data 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, ppk, trend, retest, time-loss).

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

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

litmus metrics ppk {#cli-metrics-ppk} #

Process performance (Ppk/Pp) per measurement.

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

Retest rates: how often UUTs are retried.

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

Yield summary: FPY, final yield, run counts, RTY, DPMO, DPPM, 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. Default — development when neither is set.

Git-status and mock enforcement #

Non-development phases require a clean git repository and real instruments. Uncommitted changes (or no git at all), or running with --mock-instruments, force the stamp down to development regardless of what was requested — a production-tagged row is then always reproducible from a commit hash and came from real hardware. (Profile selection still honors the requested phase; only the recorded stamp is demoted.)

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